A summary of the Build system

This could be an introduction as to why we did our own build system, the others we tried, and how we got here as a rational compromise, but it isn't.

Overview

• Provide a command line based cross platform (e.g. Unix and Windows) build system.
• Decouple the implicit relationship between packages and directories. Java language source files from many different packages may be in the same source directory. Conversely, Java language source files from a single package may be spread across many directories.
• Establish the notion of source packages, whose boundaries are orthogonal to Java language package names, and whose dependency relationships are made explicit.
• A streamlined infrastructure, so the cost of learning and navigation the sources tree won't be too onerous..

Summary of the parts

The build system is comprised of the following three pieces:

• The common Makefile
  Known as Makefile.common on Unix systems, this contains the definitions that are common to all Brazil projects. These are either the standard make targets, or macro definitions, which point to the build tools, such as javac, jar, etc. (Here is a portion of Makefile.common)

  Usually, only a couple of macros, those that point to the tool directories need to be changed in this file, and only one is needed for all users and projects that share a filesystem.

• The Project Makefile
  The project Makefile is called Makefile, and one exists for every Brazil project. Each project has one or more directories, with the Makefile in one of them. This file defines which source files belong to the project. Here is a simple example:

  First, every project should have a unique name:

    PROJECT=my_project_name
  

  Next, all of the Java language source files are listed. They may be in arbitrary directories or Java language packages.

    SRCS=
    SRCS += file1.java
    SRCS += file2.java
    SRCS += tests/test1.java
  

  The common makefile is read in:

    include ${DIR}/Makefile.common
  

  In the Brazil system, it is common for some Brazil packages to be dependent upon other Brazil packages. For example, a project that uses the server might be dependent on the server package. all Brazil projects that this one depends on are listed as in:

    DEPENDS = ../server ../handlers
  

  where ../server and ../handlers represent the directories containing that project's Makefile.

  The effect of the DEPENDS line is to cause all of the dependent projects to be made up to date with respect to our project.

  Finally The macro EXTRA_CLASSPATH may be used to specify additional classpath information, for classes or jar files that are required to build the project, but have no sources available.

  Once the Makefile is complete, the default make target builds all of the project dependencies, then all of the project sources, placing all of the class files in the classes directory.

• The support tools
  There are some deficiencies in some versions of javac when combining source files from multiple packages on the same command line in conjunction with the -d option. The build system runs the command jMkdirs, supplied as part of the build tools to insure all directories in the class hierarchy exist prior to any attempts to run javac. This works around the bug alluded to above. Without this utility, javac prints spurious messages, and the make command may need to be repeated several times.

  Since it is poor programming practice to use wild-card import declarations in the Java language (e.g. import java.io.*), the utility jImport , supplied in the toolkit, searches though Java language source files, and identifies the specific classes implied by any wildcard imports, so they may be corrected.

  The other tools included in the tool kit are:

  jUpdate

  Computes the exact list of class files that are out of date with respect to their sources. The current make system no longer uses jUpdate, choosing a simpler scheme instead.

  jRepackage

  This is an aid to changing the package name of a Java language source file, by identify and changing other files that depend on the package name.

  jExplode

  This creates a directory tree that mimics the Java language package hierarchy, by creating symbolic links to the actual Java language files. This is useful in conjunction with javadoc package documentation, which requires a fixed directory structure.

  java2html

  This converts java language source code into html for easier perusal in a web page. It has a special comment convention (which is subject to change) that causes fragment references to be embedded in the html, to allow the syncing of code fragments with associated commentary.