You are viewing a plain text version of this content. The canonical link for it is here.
Posted to alexandria-dev@jakarta.apache.org by Berin Loritsch <bl...@apache.org> on 2001/09/07 15:50:29 UTC
Build.xml standardization
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: alexandria-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: alexandria-dev-help@jakarta.apache.org
Re: Build.xml standardization
Posted by Daniel Rall <dl...@finemaltcoding.com>.
Berin Loritsch <bl...@apache.org> writes:
> Perhaps this can be further bettered by further specifying standard
> names for the build and test directories:
>
> project.name - Name of the project (no default).
> temp.dir - Location of the system's temporary directory (default="/tmp")
Using the system's temp directory on a shared development box isn't
going to work very well if more than one developer is building the
same project. Yes, I know they can just override this, but managing
it can quickly become a pain. Better that the build be self-contained
in some fashion (even if this just means using some piece of
informatio when building into the system temp dir).
> build.dir - Build directory (default="${tmp.dir}/${project.name}/build")
Is this the destination directory for the build?
> check.dir - Test results directory (default="${tmp.dir}/${project.name}/check")
>
> This way, it is easy to specify that these artifacts are all
> outside of the project directory (one of my pet peeves).
---------------------------------------------------------------------
To unsubscribe, e-mail: alexandria-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: alexandria-dev-help@jakarta.apache.org
Re: Build.xml standardization
Posted by Berin Loritsch <bl...@apache.org>.
Perhaps this can be further bettered by further specifying standard
names for the build and test directories:
project.name - Name of the project (no default).
temp.dir - Location of the system's temporary directory (default="/tmp")
build.dir - Build directory (default="${tmp.dir}/${project.name}/build")
check.dir - Test results directory (default="${tmp.dir}/${project.name}/check")
This way, it is easy to specify that these artifacts are all
outside of the project directory (one of my pet peeves).
Berin Loritsch wrote:
>
> Can we discuss this further? I would like to know if this is
> something we want done up for Jakarta's web-site. If so, it
> would be a little more meaningful than the +1's I got from Sam,
> Peter, Giacomo, Paul, and more. I even got some constructive
> criticism to make it a little better.
>
> Is this the standard we want to uphold officially?
>
> Berin Loritsch wrote:
> >
> > 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: alexandria-dev-unsubscribe@jakarta.apache.org
> > For additional commands, e-mail: alexandria-dev-help@jakarta.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: alexandria-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: alexandria-dev-help@jakarta.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: alexandria-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: alexandria-dev-help@jakarta.apache.org
Re: Build.xml standardization
Posted by Berin Loritsch <bl...@apache.org>.
Can we discuss this further? I would like to know if this is
something we want done up for Jakarta's web-site. If so, it
would be a little more meaningful than the +1's I got from Sam,
Peter, Giacomo, Paul, and more. I even got some constructive
criticism to make it a little better.
Is this the standard we want to uphold officially?
Berin Loritsch wrote:
>
> 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: alexandria-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: alexandria-dev-help@jakarta.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: alexandria-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: alexandria-dev-help@jakarta.apache.org