Looks good to me, although I'd like to follow Peter's suggestion that we use
./doc/api rather than ./javadoc. (For all the reasons Peter suggested, plus
it gives us a place to put non-javadoc documentation.)
I prefer "build" to "dist", but that's the color of the bikeshed as far as
I'm concerned.
I'll try to change collections, pool and dbcp to conform, unless someone
beats me to it (hint, hint).
-----Original Message-----
From: Craig R. McClanahan [mailto:[EMAIL PROTECTED]]
Sent: Saturday, April 28, 2001 6:56 PM
To: [EMAIL PROTECTED]
Subject: Common "ant dist" Behavior
I've been reviewing the build processes for the various commons and
sandbox packages, and we seem to be converting on common practices that
ultimately need to be documented. One of the places we are not done with
yet (primarily because we haven't talked about it) is the definition of
what happens as a result of the "ant dist" command on a package, which
should create a "binary distribution". This "binary distribution"
would be the thing that would be packaged up (zip, tar.gz, tar.Z) and
utilized by projects wishing to take advantage of our code.
To increase commonality, I propose the following guidelines:
(1) "ant dist" Output Directory:
Suggestion:
${commons.home}/${package}/build
Reasoning:
- All current packages (except Cactus) do this already
- Give CJAN-like tools a common convention to assume
- Can point build.properties files at the name of this directory (eg.
commons-beanutils.home=${commons.home}/beanutils/build)
(2) Binary Distribution Contents
The "ant dist" target for a package should ensure that all of the
following contents are placed in the output directory:
Suggestion:
LICENSE Copy of Apache License
README README with dependencies, etc.
commons-xxxxx.jar Package JAR (no version number)
javadoc/ Package Javadocs
Reasoning for "No Version Number":
- Allows build.xml files that use these JARs to define properties
(commons-beanutils.jar=${commons-beanutils.home}/commons-beanutils.jar)
without worrying about version numbers
- We're going to maintain API stability, right? :-)
- Versioning information should be included in the MANIFEST.MF
file inside the JAR anyway, so it's redundant in the filename
Reasoning for Including Javadocs:
- Projects that utilize Commons packages will often want to copy the
Javadocs (along with the JAR file) into their own distributions
(I certainly want to do this for Struts, for example)
- High quality Commons packages will have included extensive usage
information in their Javadocs (including the package.html files
for each Java package), so no extra docs should normally be
required.
- Give CJAN-like tools a common convention to assume
Reasoning for No Source:
- Smaller downloads (although these packages are so small that this
is not necessarily a compelling issue for Commons).
- Source distributions (that is, mirrors of the package subdirectory
from the Commons CVS repository) should be available separately,
with snapshots matching the code included in a released binary
distribution.
What do you think?
Craig
