GPC: Vona's Java Utils Build System

The Super-Ninja Makefile

There is one master makefile in the base package. makefiles are generated in all subpackages by typing

make makefiles

you only need to do this after changing (or getting an update to) the master makefile or after adding a package (which will then need a makefile).

Note that the makefile is checked-in to version control only in the base package.

When setting up a new project, you put an instance of makefile and makefile.project in the root package, edit the variables in the latter, check them in to version control, and then make makefiles. makefile.project defines the project name, project-specific build options, and library dependencies. From then on the makefiles know how to find libraries and build tools (see below) and you normally do not have to set any environment variables, paths, classpaths, etc. Instead of running javac MyClass.java or java MyClass to compile or run Java code, use these invocations:

make MyClass.class
make MyClass.run

If you need different makefile settings in particular subdirectories that's what (the optional) makefile.package is for. See, for example, vona/compileserver/makefile.package.

The makefile has many targets, you should read it to see them all. In addition to make makefiles, make *.class, and make *.run, some of the most useful are

make package: (the default, you also get this just by typing "make") builds all classfiles in the current directory
make project: goes to the project base dir and does a recursive make package, effectively building the whole project. You can do this from any subdir.
make clean: removes all generated files in this dir
make project-clean: removes all generated files in all project dirs
make project-javadoc: makes javadoc for the whole project in BASE_PACKAGE/APPNAME-javadoc
make jars: makes the (current sub)project jarfile(s)

In most cases the makefile will suppress the actual command lines it executes. Add VERBOSE=1 to the make command line to show them.

Finding Tools and Libraries

The super-ninja makefile has some smarts for finding the JDK it should use. It will automatically build CLASSPATH and can build distribution jarfiles that fold in the library jars your application requires. See the documentation here.

Because it can be a little time consuming to search for the various tools, the super-ninja makefile caches the results in a file named .makefile_cache_P in the top-level project directory. The P part of the cachefile name encodes the OS and CPU architecture so that the same filesystem can be used for builds on different machines. Run

make cacheclean

to force regeneration of the cachefile.

Requirements

The super-ninja makefile has only been tested with GNU Make, which is probably required. Standard JDK tools like java, javac, jar, javadoc, etc, are required depending on what you're building.

A few other tools are potentially required if you want to use the (non-javadoc) documentation building targets:

For making html from m4 (html with m4 macros): GNU M4, wwwimagesize (included with VonaUtils, but requires (perl).
For making html from phtml (html with C preprocessor macros): GCC (used for preprocessor only), wwwimagesize.
For making html from htex (html with TeX formulas in <eq> tags): Gladtex, wwwimagesize.
For making htex from md (markdown): Pandoc.
For makint htex from m4d (markdown with m4 macros): GNU m4, pandoc.

The super-ninja makefile has been tested mainly under Ubuntu Linux and Macintosh OS X. Some testing has been done under CYGWIN on Windows.

Compile Server

The java compiler, javac, is itself written in java. Thus, every time you invoke it, the JVM must be loaded. This takes time.

compileserver can reduce this time. The compile server hangs around and listens on a TCP port for requests to compile java classes. Thus, the JVM is only loaded once. This can greatly accelerate compile times, especially when javac is on a network-mounted (i.e. slow) filesystem.

The compile server needs to be started manually, thereafter it will be used automatically by the makefile. It is invoked by running the script CompileServer-ensure-running.

You can kill the compile server with the script CompileServer-kill.

Note that if you are building on machine m then the makefile will look for a compile server running as you on m. Also note that at most one instance of the compile server can be run on any machine (because it binds to a set TCP port). Thus it is not appropriate to run the compile server on shared machines.

You can stop the makefile from attempting to use the compile server by setting the environment variable NO_COMPILE_SERVER to some value, say 1. E.g. in sh or bash

export NO_COMPILE_SERVER=1

Scripts

All in vona/scripts:

run-class

interacts with the makefile to run a class. This is mostly useful for running a class with command-line arguments because the make *.run target won't do that. Example:

make MyClass.run arg1 arg2 # fails -- args aren't passed
run-class MyClass arg1 arg2 # works

find-in-{c,java,lisp,make,scheme,python}-source

recursive grep in source files (ignoring version control internal files)

And a number of others...

Disclaimer

THIS INFORMATION AND/OR SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS INFORMATION AND/OR SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.