GeoTools2 uses a system of modules to allow users to build only the component modules required for thier project. The structure of the modules is similar to the one used by netbeans To make the build process as easy as possible we have used ant. Apache Ant is a Java-based build tool. In theory, it is kind of like Make, but without Make's wrinkles. Geotools2 requires ant version 1.4.1 or later and the optional.jar file. More details are on the ant site.
back to contentsA kit with Jakarta Ant 1.4.1 can be found at ftp://gdal.velocet.ca/pub/outgoing/jakarta-ant-1.4.1-geotools2.zip. After unpacking this ensure that the ANT_HOME environment variable is pointed to the unpacked directory (ie. setenv ANT_HOME ~/jakarta-ant-1.4.1) and add $ANT_HOME/bin to your path (ie. set path = ($path $ANT_HOME/bin). This binary release includes optional.jar and junit.jar.
Otherwise ensure you have a current working version of ant, and also copy optional.jar from the Ant site into $ANT_HOME/lib, and junit.jar from www.junit.org into $ANT_HOME/lib.
If you want to build html documentation from the raw docbook format, then you will need to copy bsf.jar, xalan.jar and xerces.jar into $ANT_HOME/lib. These jars can be found at http://xml.apache.org/dist/xalan-j/old/xalan-j_1_2_2.tar.gz. Note that version 1.2.2 of xalan.jar works with ant version 1.5Beta1 however Xalan version 2.3.1 does not.
back to contentsInside each module is a pair of files that control the build process, build.xml
and build.ant.properties. If you simply want to build the module then run ant release
This will compile the code, run the unit tests, generate a jar and then place the jar and any other
jars required for its use in the release directory (folder) of the module.
If you are making changes to the code then you will probably want to use the ant targets compile and test which do what you would expect from thier names. Before you commit code back into the cvs tree please make sure that it passes the tests rather than just compiling. This makes sure you have not broken something else while you were adding a new feature or fixing a bug.
back to contentsThe way you build all of GeoTools2 is very similar to building a single module. You go to the gtbuild
directory (folder) and run ant release
exactly as before. This will build
a release of each module and place each module's jar and required support jars into the system
release directory (folder).
If you want to change which modules are built or where the final results are placed then see Changing aspects of the build process section.
back to contentsIf you want to control the modules that are built when using the project build (gtbuild/build.xm)
then you need to know a little more of how the build works.
What controls the build process is the build.ant.properties file. If you open this file then
it should look something like this:
#Ant Properties File
#Tue Jan 29 19:13:46 GMT 2002
#Path to folder where release will be placed
releaseFolder=../../release
#path to external binaries folder
extbin-extra=../../extbin/gtbuild/lib
#module set to include
modules=core,defaultcore,gmldatasource,shapefile
# are comments, the other lines are setting variables.
Ant loads this file in during the init target, once set these variables are used to
control parts of the build process.
In this case releaseFolder determines where
the output of the build process (jars etc) is put. Currently this points to a folder (directory)
two folders "up" from the gtbuild folder and called release. Note: make sure you use
unix style /'s instead of windows \'s it will still work on windows if you use the wrong
type but will fail on unix boxes, the right way round works on all machines. (I haven't tested this
on a Mac I'm afraid, but I guess it will work ok.)
The variable extbin-extra points to where the extra jars needed for the build
process are stored and you probably should not change this.
The variable you are most likely want to change is modules. This contains a
comma separated list of the modules you want to build. So if for example you only want to build
the gmldatasource and shapefile modules, you would set modules to be gmldatasource,shapefile.
The build process will call ant in each of the modules with the release target.
But by overriding the releaseFolder variable used in each case to the one set in the gtbuild
process, the outputs are all placed in that folder. You may be suprised to see that during the build
other modules that you didn't set are built, this is because some modules depend on others being
built before thier build.
If you are developing a new module, you are probably feeling despondant about the amount of work you will need to do to get the build process right. Don't be! The system is quite easy to use allowing you to concentrate on the coding.
geotools-src folder. Then within that directory make a src folder
containing an org folder, containing a geotools folder, containing a folder with the name of
your package. Note: your package name does not have to be the same as your module name,
see gmldatasource for an example.
In fact it doesn't even need to be unique, see defaultcore for an example. Then put
your source code within the package folder as usual.
Then add a tests/unit folder, inside this make a testData folder and an org/geotools/packagename folder. This is where you put your unit tests, any data files you need for your tests to run go in the testData folder.
build.xml file
from another module and edit its name, or create a new one that looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE project [
<!ENTITY common SYSTEM "../gtbuild/common.xml">
]>
<project basedir="." default="all" name="modulename">
&common;
</project>
#Ant Properties File
#Thu Mar 21 14:29:15 GMT 2002
releaseFolder=../${project.name}/release
dependancy=core,defaultcore
#the name of the project
project.name=gmldatasource
#where external binaries live
extbin=../../extbin/${project.name}/lib/
#name of testsuite
testsuite=org.geotools.gml.GmlSuite