I recently proposed a build.xml standardization, and mostly
it has been well received. I have gotten a few comments when
I posted it to the Avalon team, and so I would like to present
the proposal in its entirety (with the slight modifications)
here. I will mark the updated lines with a bar ('|') on the
right margin. You will need a wide window for this one as
a brief description of the change was put after the change
marker. Please post your comments. This is something that
should be on Jakarta's site soon. It would be nice to get a
standard we all agree on.
---------------------------------------------------------------
I propose that we all use a standard target convention for
all Ant based projects. This is something that helps adopters
of GNU software all over. A person who has never seen GNOME
or GCC knows they can compile it by running "./configure"
and "make all check install". These conventions make it
easier for the newbie to come up to a fresh project and
get it to compile.
One of the reasons I have come up with the proposal is that
every project has its own conventions. I have been involved
in at least seven Apache projects in some capacity or another
and have contributed code to four of them. They each have
different conventions. One of the ways I work is building
the project completely fresh before testing--I uncover more
bugs that way. I would very much like to run "./build clean all"
but most projects have a different target name for the default
build target. Already most projects use the following target
names: "clean", "docs", "dist", and "javadocs". Most "clean"
targets leave some artifacts behind, and only a couple projects
have the concept of "distclean".
I propose we borrow a number of conventions from the GNU
"make" utility manual
(http://www.gnu.org/manual/make-3.79.1/html_chapter/make_14.html).
If a program can be installed, then a build file must
use these properties (which can be overridden by a user's
.ant.properties file). The properties and default values follow: | (.antrc was
the wrong file)
* install.dir=.
* install.bin.dir=${install.dir}/bin
* install.lib.dir=${install.dir}/lib
* install.data.dir=${install.dir}/conf
* install.doc.dir=${install.dir}/docs
By using these properties, Ant is able to customize how the
program is installed and filter the scripts to point to the
proper jars, etc.
The standard targets I propose we all adopt are similar to
the Make utility conventions ('all' is the default target):
'all'
This is the default target. There was a suggestion to | (Copy
suggestion from
have 'main' be the default target so that by default a | Leo Simmons
for a 'main'
project can have it call 'all check' or whatever. If that | target as
the default)
is allowed, then the 'main' target must call this target. |
Compiles the program with debugging enabled by default.
This target is not required to build documentation. Standard
compilation properties and defaults are:
* build.debug=on
* build.optimize=off
(build.optimize can be set to 'on' for releases, but debug | (additional
information is invaluable for reporting bugs--only someone | reasoning
for
who knows what they are doing should turn it off) | debug
setting)
'install'
This target ensures that everything is built, including
documentation. It then copies the files in the corresponding
directories already mentioned above. All jars should be
considered libraries, and scripts should be provided to run
them. If installation is not provided by a project, the
build script should display a message to that effect. Optionally,
{build.optimize} could be set to "on" for this target.
'uninstall'
This target removes all the project files from the afformentioned
directories. IMPORTANT: The uninstall script should NOT
assume that the {install.[*].dir} directories are direct decendants
of the {install.dir} directory. If installation is not provided
by the project, the build script should display a message to
that effect.
'clean'
This target deletes all files that are generated by the build
process--but does not delete files used to configure the build
process.
'distclean'
This deletes all files that are left from clean and returns the
project to its distributed state.
'docs'
This generates all documentation for a project. This includes
user docs and javadocs. If there are no user docs, then we just |
(Clarification for
generate the javadocs. | action with
no user docs)
'javadocs'
This simply generates the javadocs for the project.
**Suggestion (from Leo Simmons): | (Copy
suggestion from
provide standardized build property for including additional | Leo
Simmons. It is worth
location for javadocs so links resolve correctly. | considering)
'printerdocs'
This generates a printer friendly version of the documentation.
Most projects dynamically build their documentation from XML
anyway. They should provide a nice and simple stylesheet that
avoids all the HTML tables embedded in tables approach most
site docs use. If there are no user docs, then we do nothing. |
(Clarification for
This target is only meant for user docs. | action with
no user docs)
'dist'
This target should be used for generating all the artifacts used
for a distribution. That means the tar ball and zip file used to
distribute projects, and any dynamically generated announcement
files.
'check'
This target is used to compile and execute any tests that | (remove the
word 'unit')
are built into the project. If a project likes the target name | (Optional
alias of 'test')
'test', they can make it an alias to this target. |
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
