                             Project Description

                    Jeff Turner <jeff@socialchange.net.au>
                             Social Change Online
                $Revision: 1.2 $ $Date: 2001/11/18 10:49:13 $
                ==============================================

This file provides an overall description of a typical project, currently
share/template/code.

Directory Layout
----------------

/					# project root
/build.xml			# Generic Ant build file
/dependencies.xml	# Ant file for updating dependencies
/build.properties	# Project-specific Ant customizations
/lib				# compile-time jar dependencies for src/java
/src				# anything that will end up in the final product
/src/java			# java code
/src/lib			# runtime jar dependencies of src/java
/src/conf			# runtime config files (will be outside jar)
/src/res			# compile-time config files (will be inside jar)
/src/etc			# misc files, include Manifest

After building:

/build				# temporary files created during build process
/build/src			# temporary copy of /src/java (filtered)
/build/classes		# compiled build/src
/build/*.jar		# jars created from build/classes

After creating a distribution:

/dist				# where built distributions go
/dist/<name>/		# an unpacked distribution
/dist/<name>.tar.gz	# packaged distribution
/dist/<name>.zip	# packaged distribution


General principles:
-------------------

 - Keep "source" (src/) separated from "output" (build/).
 - Strictly separate types of "source" in src/*.
 - Distinguish between runtime jars and compile-time jars. Runtime jars live
   in src/lib, and are needed for runtime operation. Eg: log4j.jar.
   Compile-time jars are needed for compilation only, perhaps because they are
   supplied by the deployment environment. Eg: servlet.jar, junit.jar.
 - Two types of properties files:
   - resources, in src/res/, which get put in the jar, not user-editable. Eg
     mailcap
   - config files, in src/config/, left outside jar, user-editable. Eg
     log4j.properties

Ant targets
-----------

Assuming you have Ant installed, type 'ant -projecthelp' to get a list of
targets, and descriptions of what they all do. The output will be something
like:
Default target:

 main           Main (default) target

Main targets:

 clean          Cleans the build result.
 compile        Compiles the source code
 compile-tests  Compile the unit tests
 dist           Create a distribution with documentation
 dist.lite      Create a minimal distribution with no documentation
 dist.tgz       Creates a .tar.gz distribution
 dist.zip       Creates a zipped distribution
 docs           Build the non-javadoc docs
 jar            Creates a jar of the code
 javadocs       Creates the API documentation
 main           Main (default) target
 prepare        Prepare the directories
 prepare-tests  Create minimal unit test directories
 test           Run the unit tests
 test-report    Run the unit tests and generate HTML reports



Just typing 'ant' will run 'jar', creating a jar in build/, and then run the
unit tests.


Finding out what's in a jar
---------------------------

Every project should have a Version.java file, whose main() method is invoked
when a user types 'java -jar <name>.jar' on the project's jar. For example,
typing 'java -jar csgi-core.jar' will return:

Package:		csgi-core 1.2	May 3 2001  1720 (hhmm)
Description:		Package net.socialchange.*: Core CSGI classes
Last Tagged with:	
Last committer:		$Date: 2001/11/18 10:49:13 $ $Author: jeff $
Copyright:		1999-2001 Social Change Online

This mechanism lets one identify what the jar is and when is was created.


Updating dependencies
---------------------

Often, projects depend on other projects to build. These dependencies
typically take the form of jars in src/lib/, and associated config files in
src/conf/.

The file 'dependencies.xml' lets you keep these dependencies up-to-date. It will
automatically build projects which this project is dependant on, and copy the
relevant jar and config files to src/lib/ and src/conf/. It is assumed that
these projects are checked out of CVS and up-to-date themselves.

When this Ant project is invoked with 'ant -buildfile dependencies.xml', for
each project we depend on, it will:
 - Invoke 'ant dist'
 - Copy the generated jars to src/lib/
 - Copy the generated config files to src/conf/

If your project has customized other projects' config files (eg
DBConnectionManager.properties), then these will not be overwritten *if* the
modified file is more recent than the original. 


Creating a new project
----------------------

This project structure is intended to be reusable for most code-only projects.
The build.xml is totally generic, and project-specific customizations should
all be done in build.properties. If this principal is consistently applied (it
has been so far), then any project can 'upgrade' it's build.xml to the standard
in share/template/code/build.xml.

********************************
FIRE AND BRIMSTONE SHALL RAIN DOWN ON ANYONE CAUGHT MODIFYING A MAINSTREAM
PROJECT'S build.xml WITHOUT UPDATING THE TEMPLATE.
********************************

To create a new project:

1) Copy the template:

 - Create a new project directory, proj/<name> (assumed below) or share/<name>
 - Check out CVS module share/template/code
 - Copy share/template/code/* to proj/<name>
 - If on Unix, do a CVS update of proj/<name> to retrieve hidden files (\.*)
   the copy may have missed.
 - **NB** Remove all CVS directories left from copying from
   share/template/code/. This is done with the command:
   `find . -name "CVS" -type d -exec rm -r {} \;`
 - Ensure the project builds by typing 'ant' in proj/<name>. This should create
   build/template.jar.

2) Customize the new project

 - Edit build.properties, and customize the name, description and version for
   your project.
 - Copy your Java files to src/java/
 - Copy src/java/net/socialchange/template/Version.java to the main directory
   of your code, and remove the old template/ directory.
 - Modify src/etc/Manifest.mf and fix the version class.
 - Customize .projrc if you're on Unix, and use the JPE system
   (http://newgate.socialchange.net.au/~jeff/jpe/)

2.1) Updating dependencies (optional)

 - Customize dependencies.xml to reference SCO projects your project depends
   on.
 - Run 'ant -buildfile dependencies.xml' to automatically add these project
   dependencies to src/lib/ and src/conf/.
 - Copy any 3rd party jars to src/conf/

Check that everything compiles by typing 'ant'. Ensure that 'ant
build/<name>.jar' returns the correct information.

Once it is all working, import your files into CVS with 'cvs import'
