[Geotools-devel] maven build system ready to use

[James M. <j.m...@ge...>]

Finally, the maven build system is in a state that I think is usable by 
everyone, there are bound to be some problems but with good feedback they 
can be resolved quickly.

First off, what is maven?
Maven is a "Java project management and project comprehension tool", or in 
other words, yet another build tool.

It is built on top of ant and a number of other open source utilities and 
brings them together in a in an easy to use tool.

They key part of maven is the use of project files, you should now be able 
to find a project.xml file in every active module (note for example that 
awtRenderer does not have one, this is because it is very out of date and 
not currently being developed)

The project file tells you the name of the module, who maintains it, who 
develops it, what version it has reached and what it depends on.  Note that 
as all the modules have some things in common the module project files 
actually extend one which can be found in the geotools2 root directory.

The most important part of the project file is the dependencies section as 
maven uses this to determine what order to build the modules in and what 
support jars to download when needed.  (If we move over to maven 
exclusively we will no longer need the extbin folder)

The following is a first shot at a guide on how to get and use Maven as 
well as an overview of how the files are structured:
-----------
Getting Maven:
You will need Maven 1.0 beta 7 installed in order to use the maven build 
process on your machine, you can download it from:
http://www.ibiblio.org/maven/maven/distributions/

Installing Maven:
Unpack the archive you downloaded to a convenient location on your machine 
(c:\program files is good for windoze boxes)
Set an environment variable called MAVEN_HOME to point to this location 
(e.g. c:\program files\maven-1.0-beta-7)
Add MAVEN_HOME\bin to your systems PATH environment variable.

Using Maven to build ALL modules:
(To build ALL modules you must have the JAI extension from sun installed first)
put yourself in the geotools2 directory (the one that contains geotools-src 
and spike)
type 'maven'
All being well maven should startup and proceed to build all the modules in 
the right order, at the end of this process it will display a list of all 
the modules which were built and installed correctly.
NOTE: The first build can take a very long time as maven actually downloads 
a lot of the files it needs to run itself before starting on the main 
build, please be patient, subsequent builds do not take as long.

The Maven local repository:
On your machine you will find a directory in MAVEN_HOME called repository, 
this is where maven stores all downloaded jars and installed projects.
You should see that any third party jars, such as JTS, will have been 
installed in this repository, you should also see that all successful 
module builds have had their jars installed here too (e.g. core, 
defaultcore...)

Building an individual module:
Change to the modules home directory (e.g. geotools-src\defaultcore)
Type 'maven'
It should do a complete build, note that if you have not done a full build 
yet then the build may fail because it can't find the jar for a module it 
depends on.

Doing things other than building:
In any individual module home you can type maven -g to see a full list of 
goals that can be run for that module.
Handy examples include...
maven site   (generates a web site in the target\docs folder which provides 
a LOT of information about the module)
maven javadoc (generates the javadoc for the module)
maven test (runs the tests)
maven jar:install (installs the module into the Maven repository for use by 
other modules)

Project File structure:
Maven uses a number of files to work out what to do, the most important as 
mentioned above are the project.xml files, there are however a few others, 
the layout is as follows...
geotools2\project.xml - the parent template project file which the module 
files extend
geotools2\maven.xml - a control file which marchels the building of ALL 
modules and will soon generate a full website
geotools2\geotools-src\module\project.xml - the specific project file for a 
given module
geotools2\geotools-src\module\build.properties - some control properties 
that will eventually be inherited from a a parent, but not yet.
geotools2\geotools-src\module\target - folder generated during builds that 
contains all output (classes, jars and reports)
geotools2\geotools-src\module\xdocs - contains files such as logos or 
additional web pages that go into the web site

Remote File Structure:
There is a repository of jars required by geotools2 stored on the 
sourceforge site, you can browse it online at
http://www.geotools.org/gt2modules/extbin

If a module you are developing needs a third party jar to operate then this 
is the place to put it, the naming convention is:
projectname/jars/jarname-version.jar

You can find the remote repository on the shell sever at 
/home/groups/g/ge/geotools/htdocs/gt2modules/extbin it has group 
permissions set so you should be able to modify it if you have developer 
rights.

---------
I'm sure there is more information that people will need, and I'm sure that 
the maven build process will need some tweaking before it all works 
smoothly but I am convinced that it will be worth the effort especially 
onces maven get out of the beta stage.

Please take the time to install Maven on your machines and try using it to 
build GT2, let me know how far you get and what problems you come across.

All the best

James.


-- 
James Macgill
Center for Computational Geography http://www.ccg.leeds.ac.uk
Spell Checker (c) Creative Spelling inc (aka my dyslexic brain)
http://www.geotools.org a client side java mapping toolkit.