----- Original Message -----
From: "Craig R. McClanahan" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Sunday, April 29, 2001 12:55 AM
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
Well, well, well ... this is not completely true. Cactus lets users define
dist.home property variable in the build.properties file to decide where to
create the distribution directory. When this value is not defined, the
default is ${package}/out/dist ... :)
> - 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)
>
As suggested by others on this list, I vote +1 for "dist". "build" is too
ambiguous. I'll update Cactus today to set the default dist.home to be
${package}/dist.
> (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
>
+1 with zipped distribution file containing the version (like
commons-cactus-1.0.zip)
> 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
>
+1 for including javadoc. However, I prefer to have a "docs" directory that
will include the javadoc + other files. For example, in Cactus, I like to
include a local copy of the web site (and I don't this this kind of
information will integrate well in the javadoc format ...).
So +1 for :
dist
|_ docs
|_ api | javadocs
|_ other documentation files
> 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.
>
+1
> What do you think?
>
> Craig
Thanks Craig.
Vincent.
