|| Requirements for building OpenDJ
================================
Mandatory:
	- Sun/Oracle JDK 6 (latest)
		- http://www.oracle.com/technetwork/java/javase/downloads/
	- ant 1.9.1
		- http://ant.apache.org/bindownload.cgi
Optional:
	- OpenDMK
		- for building DS SNMP extensions
	- xsltproc 1.1.26 incl. libxml 20706, libxslt 10126 and libexslt 815
		- http://xmlsoft.org/XSLT/downloads.html
		- for building man pages from docbook source
		- 'xsltproc' directory must be in your PATH environment variable
	- docbook-xsl 1.75.2
		- http://sourceforge.net/projects/docbook/files/docbook-xsl/
		- for building man pages from docbook source
	- ksh93
		- http://www2.research.att.com/~gsf/download/gen/ast-ksh.html
		- 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
		- http://repo1.maven.org/maven2/org/vafer/jdeb/0.10/
		- for building a Debian package (put the jdeb-0.10.jar in the lib
		  directory of your ant installation)
	- subclipse
		- http://subclipse.tigris.org/update_1.6.x
		- for Subversion support in the eclipse IDE
	- Mercurial Eclipse
		- http://mercurialeclipse.eclipselabs.org.codespot.com/hg.wiki/update_site/stable/
		- for Mercurial support in the eclipse IDE
	- TestNG Eclipse
		- http://beust.com/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:
		-Demma.coverage.out.file=build/coverage/gathereddata/unit.emma
		-Demma.coverage.out.merge=false
		-Dorg.opends.server.BuildRoot=.
		-Dorg.opends.server.BuildDir=build
		-Dorg.opends.server.RunningUnitTests=true
		-Dorg.opends.server.snmp.opendmk=/local/share/opendmk/lib
		-Dorg.opends.test.suppressOutput=false
		-Dorg.opends.test.pauseOnFailure=false
		-Dorg.opends.server.debug.target=org.opends.server:level=warning,category=caught|data|database-access|message|protocol,stack,cause
		-Dorg.opends.test.copyClassesToTestPackage=false
		-Dtest.progress=false
		-Xms512m -Xmx512m
	- further Developement related documentation can be found via:
		- https://wikis.forgerock.org/confluence/display/OPENDJ/OpenDJ+Developer+Documentation
		- https://java.net/projects/opends/pages/2_4_OpenDSDeveloperDocumentation


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).