xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Berin Loritsch <blorit...@apache.org>
Subject Standardizing build.xml files
Date Thu, 06 Sep 2001 19:13:38 GMT
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.

---------------------------------------------------------------------
In case of troubles, e-mail:     webmaster@xml.apache.org
To unsubscribe, e-mail:          general-unsubscribe@xml.apache.org
For additional commands, e-mail: general-help@xml.apache.org


Mime
View raw message