6330N/ARequirements for building OpenDJ

6330N/A================================

6330N/AMandatory:

6330N/A - Sun/Oracle JDK 6 (latest)

6330N/A - http://www.oracle.com/technetwork/java/javase/downloads/

6330N/A - ant 1.9.1

6330N/A - http://ant.apache.org/bindownload.cgi

6330N/AOptional:

6330N/A - OpenDMK

6330N/A - for building DS SNMP extensions

6330N/A - xsltproc 1.1.26 incl. libxml 20706, libxslt 10126 and libexslt 815

6330N/A - http://xmlsoft.org/XSLT/downloads.html

6330N/A - for building man pages from docbook source

6330N/A - 'xsltproc' directory must be in your PATH environment variable

6330N/A - docbook-xsl 1.75.2

6330N/A - http://sourceforge.net/projects/docbook/files/docbook-xsl/

6330N/A - for building man pages from docbook source

6330N/A - ksh93

6330N/A - http://www2.research.att.com/~gsf/download/gen/ast-ksh.html

6330N/A - for building a Solaris/Illumos+ friends SVR4 packages

6330N/A - Solaris/Illumos+ SVR4 pkg tools

6330N/A - included in your OS

6330N/A - for building a Solaris/Illumos+ friends SVR4 package

6330N/A - IPS pkg tools

6330N/A - https://java.net/projects/ips/pages/Home (or part of your OS)

6330N/A - for building a Solaris/Illumos+ friends IPS package

6330N/A - Debian Ant Task package

6330N/A - http://repo1.maven.org/maven2/org/vafer/jdeb/0.10/

6330N/A - for building a Debian package (put the jdeb-0.10.jar in the lib

6330N/A directory of your ant installation)

6330N/A - subclipse

6330N/A - http://subclipse.tigris.org/update_1.6.x

6330N/A - for Subversion support in the eclipse IDE

6330N/A - Mercurial Eclipse

6330N/A - http://mercurialeclipse.eclipselabs.org.codespot.com/hg.wiki/update_site/stable/

6330N/A - for Mercurial support in the eclipse IDE

6330N/A

6330N/ANOTES:

6330N/A Shown versions numbers imply: works PROBABLY IF the tool has a HIGHER

6330N/A version, works probably NOT IF the tool has a LOWER version.

6330N/A

6330N/A Usually all modern OS provide precompiled packages - so try those before

6330N/A waisting time to compile/install them from source.

6330N/A

6330N/A All binaries aka external progs need to be found via your PATH environment

6330N/A variable. I.e. you should be able to start them on the command line just

6330N/A by using their names like 'ant' or 'ant.bat', no matter what your current

6330N/A working directory is.

6330N/A (see also http://stackoverflow.com/questions/9262712/ant-is-not-recognized-as-an-internal-or-external-command)

6330N/A

6330N/A If you use a Mercurial repo, the 'hg' tool is needed via CLI as well.

6330N/A

6330N/A Illumos+ means: OpenSolaris and derivates/distributions like OmniOS,

6330N/A SmartOS, OpenIndiana.

6330N/A

6330N/A All unmentioned tools are either in the repository or downloaded on demand

6330N/A by the ant build process.

6330N/A

6330N/A

6330N/AHowto build

6330N/A===========

6330N/A - satisfy requirements (see above)

6330N/A - copy etc/build.properties to your ${HOME}/config/ant/opendj2.properties

6330N/A and than make the adjustments to match your environment using an text

6330N/A editor of your choice

6330N/A - cd to your opendj source directory

6330N/A - run ant or ant.bat

6330N/A

6330N/AHints

6330N/A=====

6330N/A - to be able to better distinguish the messages ant emits, one should use

6330N/A the AnsiColorLogger. E.g.:

6330N/A ant -logger org.apache.tools.ant.listener.AnsiColorLogger ...

6330N/A (see also http://ant.apache.org/manual/listeners.html#AnsiColorLogger )

6330N/A - to view ansi colored redirected output, use less with the option -R. E.g.:

6330N/A less -R /tmp/ant.out

6330N/A - to build only certain parts of the DS, have a look at the output of

6330N/A ant -projecthelp

6330N/A and build, what you need. E.g.:

6330N/A ant proto dsml api

6330N/A - only the targets 'nightly', 'nightly.build', 'precommit' and 'release'

6330N/A will clean up all generated source files and build directories before

6330N/A rebuilding to ensure everything works as expected. So if you intent to

6330N/A make an OpenDJ package publicly available, you should run one of those or

6330N/A pass the 'clean' target explcitly to ant.

6330N/A - the "test*" targets have a lot of test tuning options. To get the details,

6330N/A have a look at etc/test.help.txt

6330N/A - to debug a remote instance in a secure manner, one may tunnel the

6330N/A Java Debug Wire Protocol (JDWP) via SSH. E.g.: If 'ldap' is the name of

6330N/A the internal machine, which runs an OpenDJ instance, and 'my.gateway.org'

6330N/A is the machine, which allows you to login into your internal network,

6330N/A one may use 'ssh -f -x -N -L 15005:ldap:5005 my.gateway.org' to tunnel

6330N/A the port 5005 of ldap to the localhost's port 15005. The OpenDJ instance

6330N/A should have JWDP enabled of course - one can do that by passing the

6330N/A following parameters to the JVM:

6330N/A -agentlib:jdwp=transport=dt_socket,server=y,address=5005,suspend=y

6330N/A (e.g. by adding them to the 'start-ds.java-args' property in the

6330N/A $instance.dir/config/java.properties and running dsjavaproperties).

6330N/A Than, if you are running eclipse, you may use the 'OpenDJ - ServerRemote'

6330N/A launch configuration to start debugging. Otherwise you need to tell your

6330N/A IDE/Debugger, that it should connect to localhost on port 15005 ...

6330N/A - further Developement related documentation can be found via:

6330N/A - https://wikis.forgerock.org/confluence/display/OPENDJ/OpenDJ+Developer+Documentation

6330N/A - https://java.net/projects/opends/pages/2_4_OpenDSDeveloperDocumentation

6330N/A

6330N/A

6330N/AEclipse

6330N/A=======

6330N/AOnce:

6330N/A - Download the OpenDMK and adjust the build.properties as described above

6330N/A if not already done

6330N/A - Install the eclipse repository support, if not already done

6330N/A - Checkout the OpenDJ source tree by opening the repo corresponding view

6330N/A Window | Show View | Other

6330N/A Mercurial

6330N/A Mercurial Repositories

6330N/A SVN

6330N/A SVN Repositories

6330N/A and add the required infos. Use 'opendj2' as project name!

6330N/A - change back to the Java perspective (if not done automatically)

6330N/A Window | Open Perspective | Other

6330N/A Java

6330N/A - copy etc/opendmklib.eclipse to /tmp/ and adjust the pathes to the

6330N/A OpenDMK Jars

6330N/A - import the OpenDMK libraries info:

6330N/A Window | Preferences

6330N/A -> Java -> Build Path -> User Libraries:

6330N/A Import...

6330N/A choose /tmp/opendmklib.eclipse and "OK"

6330N/A - import the OpenDJ formatting rules etc/opendj-eclipse-formatter-rules.xml

6330N/A a) select the project e.g. by clicking on the 'opendj2' node in

6330N/A the navigator view

6330N/A b) import:

6330N/A Project | Properties

6330N/A -> Java Code Style -> Formatter:

6330N/A x Enable project specific settings

6330N/A Import...

6330N/A choose etc/opendj-eclipse-formatter-rules.xml and "OK"

6330N/A - adjust Ant formatting rules:

6330N/A Window | Preferences...

6330N/A -> Ant -> Editor -> Formatter:

6330N/A Tabe size: 4

6330N/A x Use tab character instead of spaces

6330N/A Maximum line width (characters): 80

6330N/A x Wrap long element tags

6330N/A x Align final '>' in multi-line element tags

6330N/A "OK"

6330N/A - import the Compiler Preferences

6330N/A File | Import...

6330N/A -> Genaral -> Preference: "Next"

6330N/A Browse: etc/eclipse-compiler.prefs

6330N/A Finish

6330N/A - last but not least the following Editor Prefs should be set:

6330N/A Window | Preferences ...

6330N/A -> General -> Editors -> Text Editors:

6330N/A Undo history size: 500

6330N/A Display tab width: 4

6330N/A / Insert spaces for tabs ( / == unset )

6330N/A x Show print margin

6330N/A Print margin column: 80

6330N/A x Show line numbers

6330N/A x Warn before editing a derived file

6330N/A x Smart caret positioning at line start and end

6330N/A -> General -> Editors -> Text Editors -> Annotations:

6330N/A Errors: Enable all

6330N/A Warnings: Enable all

6330N/A "OK"

6330N/A

6330N/ASometimes:

6330N/A - 'ant eclipse': dueto the strange source tree layout it is pretty

6330N/A cumbersome to adjust the library pathes via includes, excludes etc. to

6330N/A avoid classpath overlappings. So to keep it simple, we package the

6330N/A build tools into lib/build-tools.jar and required message properties incl.

6330N/A generated stubs into lib/opendj-resources.jar. Finally the needed

6330N/A java source files gets generated to src/{admin,messages,snmp}/generated/

6330N/A -> usually required if something in src/{admin|messages}/messages/ or

6330N/A src/snmp/resource/mib/ gets changed

6330N/A -> always required if one did a 'ant realclean'

6330N/A - 'ant gen.instance': setup a OpenDJ data instance directory for testing,

6330N/A which can be used by the OpenDJ_Server launcher.

6330N/A -> depends on your needs (see also etc/build.properties).