[proposal]: directory structure for a Beehive distribution

[Eddie O'Neil <ek...@bea.com>]

All--

   One thing that might help people become involved in Beehive is if
it's easy to take Beehive and start writing applications with the
runtime.  We can enable this by making it possible to produce a 
"distribution" from the Beehive build; the structure of this would 
mirror the structure a developer would see when Beehive is distributed 
for download on the web and unzipped.

   There are a couple of benefits to starting to do this now:

- it's easier to build a Beehive enabled application.  Currently, this 
requires understanding the SVN tree structure and how the various 
Beehive pieces fit together.
- it causes the Beehive build files to be something that can be used 
outside of the SVN tree.  For example, we've got a webapp build file 
that compiles an XMLBean/Controls/NetUI enabled web project, but it's 
not usable outside of the dev tree.  The Pollinate folks have asked 
about having a build file that does this.  SVN checkin 47616 starts to 
make some of this possible.

   The distribution directory structure would be created in one of two ways:

- as the last step in a "deploy" run from $BEEHIVE_HOME and would be 
rooted in the $BEEHIVE_HOME/build/dist directory.
- as a separate "build.dist" target which populates build/dist/ and 
builds the samples / docs / project templates described below.

The reason that "build.dist" may need to be separated from the "deploy" 
target is that constructing the distribution will slow down a Beehive 
"clean deploy".

A top-level "clean" would delete the build/ directory and either 
"deploy" or "build.dist" would re-create the distribution.

   The proposal below considers only one type of distribution -- that 
which includes docs, samples, template projects, and runtime bits but no 
servers on which to run a Beehive application.  One can envision having 
other distribution formats that include only the runtime JARs or a 
"heavy" distribution that includes all of the distribution plus Ant / 
Axis / Tomcat / etc.

   Below is a strawman for the structure of build/dist/ and descriptions 
of each sub-directory.

   ant/
      buildWebappCore.xml
      tomcat/
          deployWebapp.xml
      ...
   docs/
      <exploded Beehive doc / Javadoc>
   lib/
      common/
          apache-xbean.jar
          log4j-1.2.8.jar
          ...
      controls/
           runtime/
               controls.jar
               ...
      netui/
           struts.jar
           beehive-netui-pageflow.jar
           ...
      wsm/
           wsm.jar
   samples/
      <exploded Controls / WSM / NetUI samples>
   templates/
      netui-blank.war
      wsm-blank.war
      controls-blank.jar
   README.txt
   LICENSE.txt
   INSTALL.txt
   NOTICE.txt

Descriptions of the sub-directories:

- the ant/ directory contains the build files for compiling various 
Beehive enabled projects.  For example, a skeleton webapp build file 
would be included that has targets to build / clean a Beehive-enabled 
web project.  There would also be Ant targets to help (un|re)deploying a 
webapp on Tomcat and a target to obtain a copy of the NetUI runtime.  In 
general, the build files would contain the core tasks needed to build / 
clean each project type and would be structured such that they could be 
called directly or included in project-specific build files using the 
Ant 1.6 <import> tag.

- the lib/ directory contains the runtime bits divided by sub-component. 
  This breakdown helps developers understand which runtime pieces are 
used by each of WSM, Controls, and NetUI.
- the lib/common/ directory contains the runtime bits that are shared
between two or more sub-projects.  Currently, this includes XMLBeans and 
Log4J
- the lib/controls/ directory contains the controls.jar and related
Velocity JARs; the latter are used at build time
- the lib/netui/ directory contains the NetUI JPF runtime, compiler, tag
libraries, skeleton config files, and the Struts / Commons JARs
- the lib/wsm/ directory contains wsm.jar and any related runtime JARs

- the templates/ directory contains project templates for the various 
Beehive components including a WSM enabled webapp, a controls JAR 
project, and a NetUI / Controls / XMLBeans enabled webapp.  These can be 
unzipped and used as a starting point for building Beehive projects and 
should ship compiled such that they can be dropped into a container and 
run when possible.

- the docs/ directory will contain Beehive documentation and API Javadoc

- the samples/ directory will contain the samples that we decide should 
be distributed with the runtime

   I'm sure there are pieces missing here, so what else should be a part
of this?  Any feedback from how people have seen other projects
structure / build their distributions?

   If there's general consensus on this approach, I'll take the task of
starting to create the dist/ directory,  and populate it with the Ant
build files, common/, netui/, and templates/ bits.

   Other thoughts?

Eddie