Typically, Ant build files define properties first, then construct targets using
those definitions to avoid hard-coding everything.
JAM follows this pattern, specifying a Maven compatible directory layout and
default properties in the props-global.xml file. Technically you
can get away with just importing this file (followed by the
classpath.xml file), but this does not result in a very modular
setup, especially when you start breaking your project into sub-modules.
Properties can be organized at the module, project, or user levels to avoid redundancy, for example:
<import file="${user.home}/.ant/props-user.xml" optional="true"/>
<import file="${project.home}/props-project.xml" optional="true"/>
<import file="${basedir}/src/jam/props-maven.xml" optional="true"/>
<import file="${jam.home}/props-global.xml"/>
<import file="${basedir}/src/jam/classpath.xml"/> The first three property files are optional (if not present they are ignored). The
props-project.xml file only makes sense if you have more than one module in
your project.
If you follow this property import layout, here are the intended uses for these files
(remember, Ant binds a property on first encountering it, ignoring subsequent settings):
| props-user.xml | Sets user-specific properties - properties apply to all projects under user's account. |
|---|---|
| props-project.xml | Sets project-specific properties - properties apply to all modules within project. |
| props-maven.xml | Generated file that sets basic properties pulled from the POM file. To generate type:maven jam:properties or maven jam. |
| props-global.xml | Default settings used by JavaGen (required). |
| classpath.xml | Classpath and library handling code (required). This file is
generated from your POM dependencies (see JAM and Maven) by typing:maven jam:classpath or maven jam
|
Organize your properties in what ever way make sense for your project.
If your company always requires certain settings, you could have an additional file called
props-co.xml and so on. However, the one place not to change properties is in
props-global.xml because this will be overwritten the next time you upgrade JAM.
Some of the more important properties used by JAM are:
| jam.home | Must be defined in each build file before the import statements
so Ant can find the JAM modules.
To avoid hard-coding, the JAM location define JAM_HOME as an environmental variable (see OS Issues) pointing to
the directory you installed JAM in, for example:
Windows: set JAM_HOME=c:\javagen-ant-modules-2.1 Unix: export JAM_HOME=/home/username/javagen-ant-modules-2.1Then include the following two lines above your import statements: <property environment="env"/>
<property name="jam.home" location="${env.JAM_HOME}"/>
|
|---|---|
| project.name | Set in props-maven.xml from pom.id. It is only used in multi-module projects for naming all project-wide artifacts. |
| project.version | Set in props-maven.xml from pom.currentVersion. It is only used in multi-module projects for distribution file names and version tracking. |
| project.home | Only used in multi-module projects. Usually set to .. in multi-module projects. Should be defined in each build file because it is used to import other Ant scripts. Defaults to ${basedir}. |
| module.name | Set in props-maven.xml from pom.id. It is used for naming all module-wide artifacts. |
| module.version | Set in props-maven.xml from pom.currentVersion. |
| user.home | Ant's built-in property for your user directory. As of Ant 1.6, any libraries
placed in ${user.home}/.ant/lib are included in Ant's classpath. Likewise, by default JAM uses this location
to store user-specific properties (i.e. ${user.home}/.ant/props-user.xml). |
| maven.repo | Set in props-maven.xml and specifies the location of the local Maven repository. Defaults to ${user.home}/.maven/repository
|
| maven.groupId | Set in props-maven.xml from pom.groupId, it is used as the repository sub-directory name. |
| maven.type | Used as distribution file extension (i.e. jar, war, ear) and in building maven.folder property. |
| maven.folder | Relative location distribution file will be placed in Maven repository. Defaults to ${maven.groupId}/${maven.type}s. |
| dist.name | Name of distribution file. Defaults to ${module.name}-${module.version}.${maven.type}. |
The first target you should execute when setting up a new Ant script is,
ant setup which will
tell you if your basic setup is correct as well as showing some of the above properties.
Occasionally you may get unexpected results or need to figure out where a property is being set.
You can get a property setting dump by using Ant's debug flag (ant -d setup). Better yet,
you can debug your scripts using a few strategically placed print-line statements, which in Ant looks like:
<echo>jam.home = ${jam.home}</echo>