README.txt revision 6426
|| Requirements for building OpenDJ
================================
Mandatory:
- Sun/Oracle JDK 6 (latest)
- ant 1.9.1
Optional:
- OpenDMK
- for building DS SNMP extensions
- xsltproc 1.1.26 incl. libxml 20706, libxslt 10126 and libexslt 815
- for building man pages from docbook source
- 'xsltproc' directory must be in your PATH environment variable
- docbook-xsl 1.75.2
- for building man pages from docbook source
- ksh93
- for building a Solaris/Illumos+ friends SVR4 packages
- Solaris/Illumos+ SVR4 pkg tools
- included in your OS
- for building a Solaris/Illumos+ friends SVR4 package
- IPS pkg tools
- https://java.net/projects/ips/pages/Home (or part of your OS)
- for building a Solaris/Illumos+ friends IPS package
- Debian Ant Task package
- for building a Debian package (put the jdeb-0.10.jar in the lib
directory of your ant installation)
- subclipse
- for Subversion support in the eclipse IDE
- Mercurial Eclipse
- for Mercurial support in the eclipse IDE
- TestNG Eclipse
- for TestNG support within eclipse
NOTES:
Shown versions numbers imply: works PROBABLY IF the tool has a HIGHER
version, works probably NOT IF the tool has a LOWER version.
Usually all modern OS provide precompiled packages - so try those before
waisting time to compile/install them from source.
All binaries aka external progs need to be found via your PATH environment
variable. I.e. you should be able to start them on the command line just
by using their names like 'ant' or 'ant.bat', no matter what your current
working directory is.
(see also http://stackoverflow.com/questions/9262712/ant-is-not-recognized-as-an-internal-or-external-command)
If you use a Mercurial repo, the 'hg' tool is needed via CLI as well.
Illumos+ means: OpenSolaris and derivates/distributions like OmniOS,
SmartOS, OpenIndiana.
All unmentioned tools are either in the repository or downloaded on demand
by the ant build process.
Howto build
===========
- satisfy requirements (see above)
- copy etc/build.properties to your ${HOME}/config/ant/opendj2.properties
and than make the adjustments to match your environment using an text
editor of your choice
- cd to your opendj source directory
- run ant or ant.bat
Hints
=====
- to be able to better distinguish the messages ant emits, one should use
the AnsiColorLogger. E.g.:
ant -logger org.apache.tools.ant.listener.AnsiColorLogger ...
(see also http://ant.apache.org/manual/listeners.html#AnsiColorLogger )
- to view ansi colored redirected output, use less with the option -R. E.g.:
less -R /tmp/ant.out
- to build only certain parts of the DS, have a look at the output of
ant -projecthelp
and build, what you need. E.g.:
ant proto dsml api
- only the targets 'nightly', 'nightly.build', 'precommit' and 'release'
will clean up all generated source files and build directories before
rebuilding to ensure everything works as expected. So if you intent to
make an OpenDJ package publicly available, you should run one of those or
pass the 'clean' target explcitly to ant.
- the "test*" targets have a lot of test tuning options. To get the details,
have a look at etc/test.help.txt
- to debug a remote instance in a secure manner, one may tunnel the
Java Debug Wire Protocol (JDWP) via SSH. E.g.: If 'ldap' is the name of
the internal machine, which runs an OpenDJ instance, and 'my.gateway.org'
is the machine, which allows you to login into your internal network,
one may use 'ssh -f -x -N -L 15005:ldap:5005 my.gateway.org' to tunnel
the port 5005 of ldap to the localhost's port 15005. The OpenDJ instance
should have JWDP enabled of course - one can do that by passing the
following parameters to the JVM:
-agentlib:jdwp=transport=dt_socket,server=y,address=5005,suspend=n
(e.g. by adding them to the 'start-ds.java-args' property in the
$instance.dir/config/java.properties and running dsjavaproperties).
Than, if you are running eclipse, you may use the 'OpenDJ - ServerRemote'
launch configuration to start debugging. Otherwise you need to tell your
IDE/Debugger, that it should connect to localhost on port 15005 ...
- to debug a client (e.g. the control-panel or resource/bin/idsconfig),
common preparation could be:
rm -rf build/instance
ant gen.instance
ant run.server
One can access the server than on port 1389 or 4444. The initial password
for "cn=Directory Manager" is 'password'.
- the TestNG eclipse plug-in is pretty dumb wrt. finding the right pathes:
sometime it assumes / as the base directory, sometimes the project dir,
and it does not expand variables like ${workplace_loc} etc. So to get it
work, open Project | Properties -> TestNG and give it the pathes:
Output directory: build/test-output
Template XML file: /home/myUserName/workspace/opendj2/build/unit-tests/resource/testng.xml
When you create a new TestNG Launch configuration, enter the
Template XML file as shown above into the Suite text field, but without
the project prefix (i.e. /build/unit-tests/resource/testng.xml for the
example above) and the following Jvm arguments with values adjusted as
you like into the VM arguments text area:
-Dorg.opends.server.debug.target=org.opends.server:level=warning,category=caught|data|database-access|message|protocol,stack,cause
-Dtest.progress=false
-Xms512m -Xmx512m
- further Developement related documentation can be found via:
Eclipse
=======
Once:
- Download the OpenDMK and adjust the build.properties as described above
if not already done
- Install the eclipse repository support, if not already done
- Checkout the OpenDJ source tree by opening the repo corresponding view
Window | Show View | Other
Mercurial
Mercurial Repositories
SVN
SVN Repositories
and add the required infos. Use 'opendj2' as project name!
- change back to the Java perspective (if not done automatically)
Window | Open Perspective | Other
Java
- copy etc/opendmklib.eclipse to /tmp/ and adjust the pathes to the
OpenDMK Jars
- import the OpenDMK libraries info:
Window | Preferences
-> Java -> Build Path -> User Libraries:
Import...
choose /tmp/opendmklib.eclipse and "OK"
- import the OpenDJ formatting rules etc/opendj-eclipse-formatter-rules.xml
a) select the project e.g. by clicking on the 'opendj2' node in
the navigator view
b) import:
Project | Properties
-> Java Code Style -> Formatter:
x Enable project specific settings
Import...
choose etc/opendj-eclipse-formatter-rules.xml and "OK"
- adjust Ant formatting rules:
Window | Preferences...
-> Ant -> Editor -> Formatter:
Tabe size: 4
x Use tab character instead of spaces
Maximum line width (characters): 80
x Wrap long element tags
x Align final '>' in multi-line element tags
"OK"
- import the Compiler Preferences
File | Import...
-> Genaral -> Preference: "Next"
Browse: etc/eclipse-compiler.prefs
Finish
- last but not least the following Editor Prefs should be set:
Window | Preferences ...
-> General -> Editors -> Text Editors:
Undo history size: 500
Display tab width: 4
/ Insert spaces for tabs ( / == unset )
x Show print margin
Print margin column: 80
x Show line numbers
x Warn before editing a derived file
x Smart caret positioning at line start and end
-> General -> Editors -> Text Editors -> Annotations:
Errors: Enable all
Warnings: Enable all
"OK"
Sometimes:
- 'ant eclipse': dueto the strange source tree layout it is pretty
cumbersome to adjust the library pathes via includes, excludes etc. to
avoid classpath overlappings. So to keep it simple, we package the
build tools into lib/build-tools.jar and required message properties incl.
generated stubs into lib/opendj-resources.jar. Finally the needed
java source files gets generated to src/{admin,messages,snmp}/generated/
-> usually required if something in src/{admin|messages}/messages/ or
src/snmp/resource/mib/ gets changed
-> always required if one did a 'ant realclean'
- 'ant gen.instance': setup a OpenDJ data instance directory for testing,
which can be used by the OpenDJ_Server launcher.
-> depends on your needs (see also etc/build.properties).
- 'ant test.prepare' to create the test output directories below build/
and to prepare the required testng.xml config file (if necessary).