#----------------------------------------------------------------------------
# Makefiles for managing a Java project consisting of multiple packages
#----------------------------------------------------------------------------

** Overview **

The following directory structure is assumed by the Makefiles, letting
ROOT be the project root directory:

${ROOT}/	# Root directory of the project
	src/	# Root directory of the source
	include/	# Makefile includes are kept here

The directory structure underneath ${ROOT}/src should exactly mirror
the package structure.

In addition, the following directory structure is set as default:

${ROOT}/
	classes/	# Default installation directory
	doc/api/	# Default API (javadoc) documation directory
	jars/	# Default .jar directory

These directories may be modified in Defs.mk (see below.)


The Makefiles themselves consist of the following:

Root.mk		# Used as ${ROOT}/Makefile
Defs.mk		# Used as ${ROOT}/include/Defs.mk
Rules.mk		# Used as ${ROOT}/include/Rules.mk
SrcRoot.mk	# Used as ${ROOT}/src/Makefile
Makefile		# Used in all source directories below ${ROOT}/src

In a default installation, these files are kept in ${ROOT}/etc.

Root.mk, Defs.mk, and Rules.mk are not modified by the developer,
and hence in the default installation are symbolically linked to where
they are actually used. SrcRoot.mk and Makefile, on the other hand,
must be modified for the particular package.


** Usage **

The following example illustrates how to use the Makefiles.

* Setup

Suppose we have two packages:
	foo.bar	- contains class BarThing
	foo.baz	- contains class BazBean which is a JavaBean

Assuming that the source code BarThing.java and BazBean.java already
exist, we would first create the following directory structure:

${ROOT}/src/
		foo/
			bar/
				BarThing.java
			baz/
				BazBean.java


Then we would do the following:

1. Copy SrcRoot.mk to ${ROOT}/src/Makefile. Edit Makefile so that
	SUBPACKAGES = foo

2. Copy Makefile to ${ROOT}/src/foo/Makefile. Edit Makefile so that
	PACKAGE = foo
	SUBPACKAGES = bar baz

3. Copy Makefile to ${ROOT}/src/foo/bar/Makefile. Edit Makefile so that
	PACKAGE = foo.bar
	JAVA_FILES = BarThing.java

4. Copy Makefile to ${ROOT}/src/foo/baz/Makefile. Edit Makefile so that
	PACKAGE = foo.baz
	JAVA_FILES = BazBean.java
	JAVABEANS = BazBean

* Building

To compile the entire project, go to ${ROOT} and type `make'.

Other make options at ${ROOT} include:
	make install	# Installs .class files into ${CLASS_DIR}
	make docs		# Makes API documentation into ${APIDOC_DIR}
	make jars		# Makes a .jar file for each top-level package into ${JAR_DIR}
	make clean	# Cleans .class files, etc underneath ${ROOT}/src
	make realclean	# Cleans everything that was made

In all directories underneath and including ${ROOT}/src,
the following make options are available:
	make		# Compiles the .java files in the directory
	make install	# Installs .class files into ${CLASS_DIR}
	make clean	# Cleans .class files, etc.
Note that these make commands do not recursively make in the
subdirectories, and hence have behavior different from the
corresponding commands when executed at ${ROOT}.