Java Project build rules for GNU Make

INTRODUCTION

This is a GNU make based approach to control the automatic build of a
Java project.

A Java _project_ in this context is a set of Java packages, which are
to be build by compiling the corresponding source files, generating
API documentation using javadoc and do some optional regression tests.

At first sight, Java seems to fit well into the Unix software
development model, where you have a set of source files which get
compiled into binary objects. But there are subtle conceptual
differences, that cannot be solved by writing a simple Makefile for
automatic build. Among these differences you should note the following:

* a source file can produce more than one class file

* the directory structure of source files and class files must match
  the package structure of these files

* compiling a single source might cause the (re)compilation of some
  other source files

* all tools must know the `right' class path if called in a
  subdirectory

* many of the JDK tools operate on classes and packages instead of
  files

* because of its long startup time it is not practical to call javac
  separately for each source file to compile

This package provides a set of GNU Make rules and Makefile templates
which you can use to create a set of Makefiles for your Java project.


BUILD STEPS

The full project build is controlled from the toplevel makefile.
Calling make at lower directory levels is solely intended to trigger
the compilation of files in that subdirectory only, eg. to compile
from within XEmacs. On the top level the following (phony) targets are
provided:

  world		do full build consisting of setup, all, doc, and tests

  setup		do necessary setup actions needed before anything can
		be compiled (optional)

  all		compile all sources

  doc		generate API documentation

  tests		do regression tests (optional)

  clean		remove intermediate files (mainly classfiles)

  realclean	remove everything that was created during build


In subdirectory Makefiles only the targets 'all', 'clean', and
'realclean' are supported. The default target is 'all'.


PROJECT STRUCTURE

A project should have the following directory structure:

   <toplevel>/Makefile			main makefile of the project

             project/			project configuration directory

		       Rules.mk		common rules (this file)

		       project.mk	project specific definitions

	     <package>/			package directory

		       Makefile		package makefile

		...			more packages possible

	     junit/			JUnit test cases

		    Makefile		project testdir makefile

		    AllTests.java	main project testsuite

		    ...			more testsuites/cases

		   <package>/		in-package testcases

	     api/			generated API directory


The basic idea is, that each Makefile only privides the specific
information about *what* to build in a subdirectory but not *how*. It
then includes the file project/Rules.mk, which contains all common
definitions and compilation rules that are needed to carry out the
actual build.

For non-standard targets the Makefiles can nevertheless define their
own rules to build these specific targets.

For a project at least the following files are required:

project.mk:
	Describes your project and its requirements, eg.
	project name, required JDK version, etc.

site.mk:
	Give site specific definitions, such as JDK installation
	location. In future this might be generated by autoconf.

Makefile:
	Toplevel Makefile. Its main purpose is to specify the list of
	Java package names that make up the project.

<package>/Makefile:
	For every package you have to provide a Makefile which
	specifies the full name of the package and the source files to
	compile. You may add special rules and definitions here as
	necessary.

There are templates for these files included which you may use as a
start for your project.

