I proposed this on the general lists, and got a couple +1s
from the folks there. Please let me know if this makes sense
for us. This proposal is a minimum set of targets and
conventions for build.xml files. This allows a familiar
environment for all projects (if adopted).
-------------------------------------------------------------
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
.antrc file). The properties and default values follow:
* 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'
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
'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.
'javadocs'
This simply generates the javadocs for the project.
'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.
'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 unit tests that
are built into the project.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
