You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Berin Loritsch <bl...@apache.org> on 2001/09/07 04:26:34 UTC
Standardizing build.xml files
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: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Standardizing build.xml files
Posted by Berin Loritsch <bl...@apache.org>.
Jeff Turner wrote:
>
> On Thu, Sep 06, 2001 at 10:26:34PM -0400, Berin Loritsch wrote:
> > 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).
> >
> [..]
> > If a program can be installed, then a build file must
> > use these properties (which can be overridden by a user's
> > .antrc file).
>
> .antrc is for setting environment variables. It is distinct from
> .ant.properties (aka build.properties), which I presume you mean?
Yes.
> > 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
>
> Great. I've noticed a tendency for people to call this "main". Anyway,
> it's a good addition, because it allows "ant clean all" to be done on
> any project, whereas without knowing the default target, you're stuck
> with "ant clean ; ant".
Exactly. Actually, this isn't as standard as you might think.
For Avalon projects it is 'main'
For Cocoon projects it is 'package'
For Axis projects it is 'all'
Borrowing a convention from GNU in this respect is not bad.
> > '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.
>
> A bit off-topic but..
>
> I've managed to avoid "invoking scripts" in my projects by adding the
> following to the jar manifest:
>
> Class-Path: [requisite jars]
> Main-Class: [main class]
>
> Eg,
> Class-Path: crimson.jar jaxp.jar catalog.jar
> Main-Class: net.socialchange.validator.Validator
>
> Then the project can be invoked with "java -jar foo.jar".
Yep, but many projects have more things that have to be set up
for classpaths and setting java heap sizes, etc. Esp. servers.
I find it a little nicer to have an invoking script in many cases
so that I can simply type "foo" and the java app runs.
Although, in windows if you set ".jar" files to invoke "javaw -jar %1"
you only have to type "foo.jar"--but this isn't common for all
environments.
Besides, the number of jars used can be made dynamic when we use
invoking scripts.
> > 'check'
> > This target is used to compile and execute any unit tests that
> > are built into the project.
>
> Or just "test"?
Well, the common convention for make files is 'check'. Many
Jakarta/XML projects are just beginning to add unit testing--so
I thought standardizing on an already common convention (I believe
even for Apache httpd) would be a good idea. If you want "test"
to alias "check" that's fine.
> Another question: what is the default target? I don't see anything
> suitable above, because they all build docs, which usually takes a long
> time.
As I mentioned above in parenthesis (which is probably why you missed
it), the "all" target is the default.
> I'd suggest keeping a "main" target, defaulted to "all", which people
> can then change to "all, tests" or "clean, all, tests" as they see fit.
>
> --Jeff
> (wishing you success where others have failed)
Thanks. It seems to be meeting with decent reception right now.
---------------------------------------------------------------------
To unsubscribe, e-mail: avalon-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: avalon-dev-help@jakarta.apache.org
Re: Standardizing build.xml files
Posted by Berin Loritsch <bl...@apache.org>.
Jeff Turner wrote:
>
> On Thu, Sep 06, 2001 at 10:26:34PM -0400, Berin Loritsch wrote:
> > 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).
> >
> [..]
> > If a program can be installed, then a build file must
> > use these properties (which can be overridden by a user's
> > .antrc file).
>
> .antrc is for setting environment variables. It is distinct from
> .ant.properties (aka build.properties), which I presume you mean?
Yes.
> > 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
>
> Great. I've noticed a tendency for people to call this "main". Anyway,
> it's a good addition, because it allows "ant clean all" to be done on
> any project, whereas without knowing the default target, you're stuck
> with "ant clean ; ant".
Exactly. Actually, this isn't as standard as you might think.
For Avalon projects it is 'main'
For Cocoon projects it is 'package'
For Axis projects it is 'all'
Borrowing a convention from GNU in this respect is not bad.
> > '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.
>
> A bit off-topic but..
>
> I've managed to avoid "invoking scripts" in my projects by adding the
> following to the jar manifest:
>
> Class-Path: [requisite jars]
> Main-Class: [main class]
>
> Eg,
> Class-Path: crimson.jar jaxp.jar catalog.jar
> Main-Class: net.socialchange.validator.Validator
>
> Then the project can be invoked with "java -jar foo.jar".
Yep, but many projects have more things that have to be set up
for classpaths and setting java heap sizes, etc. Esp. servers.
I find it a little nicer to have an invoking script in many cases
so that I can simply type "foo" and the java app runs.
Although, in windows if you set ".jar" files to invoke "javaw -jar %1"
you only have to type "foo.jar"--but this isn't common for all
environments.
Besides, the number of jars used can be made dynamic when we use
invoking scripts.
> > 'check'
> > This target is used to compile and execute any unit tests that
> > are built into the project.
>
> Or just "test"?
Well, the common convention for make files is 'check'. Many
Jakarta/XML projects are just beginning to add unit testing--so
I thought standardizing on an already common convention (I believe
even for Apache httpd) would be a good idea. If you want "test"
to alias "check" that's fine.
> Another question: what is the default target? I don't see anything
> suitable above, because they all build docs, which usually takes a long
> time.
As I mentioned above in parenthesis (which is probably why you missed
it), the "all" target is the default.
> I'd suggest keeping a "main" target, defaulted to "all", which people
> can then change to "all, tests" or "clean, all, tests" as they see fit.
>
> --Jeff
> (wishing you success where others have failed)
Thanks. It seems to be meeting with decent reception right now.
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Standardizing build.xml files
Posted by Peter Donald <do...@apache.org>.
On Fri, 7 Sep 2001 14:40, Jeff Turner wrote:
> > 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
>
> Great. I've noticed a tendency for people to call this "main". Anyway,
> it's a good addition, because it allows "ant clean all" to be done on
> any project, whereas without knowing the default target, you're stuck
> with "ant clean ; ant".
...
> Another question: what is the default target? I don't see anything
> suitable above, because they all build docs, which usually takes a long
> time.
How about "main" as the default target. It builds all the files that a
developer generally needs to perform every build cycle and creates a minimal
product that ready to be tested in other systems. So what this means in real
terms is different for each project. For some projects this may mean just
building jars, others may build jars and perform some tests, others may build
jars and create a minimal distribution directory layout (like dist-lite in
phoenix).
> (wishing you success where others have failed)
me too ;)
--
Cheers,
Pete
*------------------------------------------------*
| Trying is the first step to failure. |
| So never try, Lisa - Homer Jay Simpson |
*------------------------------------------------*
---------------------------------------------------------------------
To unsubscribe, e-mail: avalon-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: avalon-dev-help@jakarta.apache.org
Re: Standardizing build.xml files
Posted by Jeff Turner <je...@socialchange.net.au>.
On Thu, Sep 06, 2001 at 10:26:34PM -0400, Berin Loritsch wrote:
> 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).
>
[..]
> If a program can be installed, then a build file must
> use these properties (which can be overridden by a user's
> .antrc file).
.antrc is for setting environment variables. It is distinct from
.ant.properties (aka build.properties), which I presume you mean?
> 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.
Good stuff. I've found that often, the source directories are made
painfully explicit in properties, but the destination is simple "dist"
or "build", with no further granularity of where individual parts of the
distribution go.
> 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
Great. I've noticed a tendency for people to call this "main". Anyway,
it's a good addition, because it allows "ant clean all" to be done on
any project, whereas without knowing the default target, you're stuck
with "ant clean ; ant".
> '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.
A bit off-topic but..
I've managed to avoid "invoking scripts" in my projects by adding the
following to the jar manifest:
Class-Path: [requisite jars]
Main-Class: [main class]
Eg,
Class-Path: crimson.jar jaxp.jar catalog.jar
Main-Class: net.socialchange.validator.Validator
Then the project can be invoked with "java -jar foo.jar".
> 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.
Very well noted :)
> 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.
Or just "test"?
Another question: what is the default target? I don't see anything
suitable above, because they all build docs, which usually takes a long
time.
I'd suggest keeping a "main" target, defaulted to "all", which people
can then change to "all, tests" or "clean, all, tests" as they see fit.
--Jeff
(wishing you success where others have failed)
---------------------------------------------------------------------
To unsubscribe, e-mail: avalon-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: avalon-dev-help@jakarta.apache.org
Re: Standardizing build.xml files
Posted by Peter Donald <do...@apache.org>.
+1
On Fri, 7 Sep 2001 12:26, Berin Loritsch wrote:
> 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: avalon-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: avalon-dev-help@jakarta.apache.org
--
Cheers,
Pete
--------------------------------------------------
you've made a dangerous leap right over common
sense, like some kind of metaphysical Evil Knievel
--------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: avalon-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: avalon-dev-help@jakarta.apache.org
Re: Standardizing build.xml files
Posted by Jeff Turner <je...@socialchange.net.au>.
On Thu, Sep 06, 2001 at 10:26:34PM -0400, Berin Loritsch wrote:
> 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).
>
[..]
> If a program can be installed, then a build file must
> use these properties (which can be overridden by a user's
> .antrc file).
.antrc is for setting environment variables. It is distinct from
.ant.properties (aka build.properties), which I presume you mean?
> 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.
Good stuff. I've found that often, the source directories are made
painfully explicit in properties, but the destination is simple "dist"
or "build", with no further granularity of where individual parts of the
distribution go.
> 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
Great. I've noticed a tendency for people to call this "main". Anyway,
it's a good addition, because it allows "ant clean all" to be done on
any project, whereas without knowing the default target, you're stuck
with "ant clean ; ant".
> '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.
A bit off-topic but..
I've managed to avoid "invoking scripts" in my projects by adding the
following to the jar manifest:
Class-Path: [requisite jars]
Main-Class: [main class]
Eg,
Class-Path: crimson.jar jaxp.jar catalog.jar
Main-Class: net.socialchange.validator.Validator
Then the project can be invoked with "java -jar foo.jar".
> 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.
Very well noted :)
> 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.
Or just "test"?
Another question: what is the default target? I don't see anything
suitable above, because they all build docs, which usually takes a long
time.
I'd suggest keeping a "main" target, defaulted to "all", which people
can then change to "all, tests" or "clean, all, tests" as they see fit.
--Jeff
(wishing you success where others have failed)
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Standardizing build.xml files
Posted by giacomo <gi...@apache.org>.
On Thu, 6 Sep 2001, Berin Loritsch wrote:
+1
Giacomo
> 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: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Standardizing build.xml files
Posted by Berin Loritsch <bl...@apache.org>.
Leo Simons wrote:
>
> +1 with some comments.....
>
> > '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.
>
> While I agree, I am not sure whether this should be a required part
> for all projects (ie a very small project that generates a single
> jar and some javadoc shouldn't have to bother) so this should be an
> optional part.
Point taken. In that case, it would mirror what docs does. But as
soon as a project starts producing output, the printable docs are
invaluable.
> On javadocs....it would be useful to have a mechanism where you can
> specify other locations for javadocs to link to using .ant.properties.
> Would it be smart to standardise this too?
You have a suggestion?
> > 'check'
> > This target is used to compile and execute any unit tests that
> > are built into the project.
>
> would remove "unit" there. Not everyone has come around to the concept
> yet ;-)
Gotcha!
---------------------------------------------------------------------
To unsubscribe, e-mail: avalon-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: avalon-dev-help@jakarta.apache.org
RE: Standardizing build.xml files
Posted by Leo Simons <ma...@leosimons.com>.
+1 with some comments.....
> '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.
While I agree, I am not sure whether this should be a required part
for all projects (ie a very small project that generates a single
jar and some javadoc shouldn't have to bother) so this should be an
optional part.
(same could be said for "docs" but by the definition you provided you
could just make it another name for "javadocs")
On javadocs....it would be useful to have a mechanism where you can
specify other locations for javadocs to link to using .ant.properties.
Would it be smart to standardise this too?
> 'check'
> This target is used to compile and execute any unit tests that
> are built into the project.
would remove "unit" there. Not everyone has come around to the concept
yet ;-)
grz,
- Leo, who's quite busy packing...
---------------------------------------------------------------------
To unsubscribe, e-mail: avalon-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: avalon-dev-help@jakarta.apache.org
RE: Standardizing build.xml files
Posted by Gerhard Froehlich <g-...@gmx.de>.
I've no right to vote, but a thought +1 to this idea
>-----Original Message-----
>From: Berin Loritsch [mailto:bloritsch@apache.org]
>Sent: Friday, September 07, 2001 4:27 AM
>To: Avalon Development; cocoon-dev@xml.apache.org
>Subject: Standardizing build.xml files
>
>
>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: cocoon-dev-unsubscribe@xml.apache.org
>For additional commands, email: cocoon-dev-help@xml.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Standardizing build.xml files
Posted by Berin Loritsch <bl...@apache.org>.
Leo Sutic wrote:
>
> Berin,
>
> great idea. I have some minor comments, though.
>
> > -----Original Message-----
> > From: Berin Loritsch [mailto:bloritsch@apache.org]
> >
> > '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
>
> I think this should be:
>
> * build.debug=off
> * build.optimize=on
>
> If we're targetting those who just download + install stuff without any
> intention of developing, there is no need for debug information, but need
> for optimization.
Yes and no. The GNU make docs made a good point on this. These are build
parameters so they can be overridden. By building with debug information
by default, we can get more information from stack traces. When people
send in pub reports with stacktraces where debug information is stripped,
we have no line numbers making the bug harder to fix. Optimization sometimes
makes it impossible for the JRE to give line numbers in certain situations,
but I am open to turning it on once there is a release to be made.
During development, optimization should be off and debug should be on. During
release, debug should be on and optimization can be turned on. If a user turns
off debug information, then it must be assumed that they know what they are
doing.
---------------------------------------------------------------------
To unsubscribe, e-mail: avalon-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: avalon-dev-help@jakarta.apache.org
RE: Standardizing build.xml files
Posted by Leo Sutic <le...@inspireinfrastructure.com>.
Berin,
great idea. I have some minor comments, though.
> -----Original Message-----
> From: Berin Loritsch [mailto:bloritsch@apache.org]
>
> '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
I think this should be:
* build.debug=off
* build.optimize=on
If we're targetting those who just download + install stuff without any
intention of developing, there is no need for debug information, but need
for optimization.
/LS
---------------------------------------------------------------------
To unsubscribe, e-mail: avalon-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: avalon-dev-help@jakarta.apache.org