THE JAM BUILDING TOOL

Table of contents

What is Jam?
Where can I get it?
Why is Jam better than Make?
Simple Jam How-To
Where to get FT Jam?

What is Jam?

Jam is a small open-source build tool that can be used as a replacement for Make. Even though Jam is a lot simpler to use than Make, it is far more powerful and easy to master. It already works on a large variety of platforms (Unix, Windows, OS/2, VMS, MacOS, BeOS, etc.), it is trivial to port, and its design is sufficiently clear to allow any average programmer to extend it with advanced features at will.

The main differences between Jam and Make are as follows.

• Jam uses ‘Jamfiles’ instead of ‘Makefiles’.

• Jamfiles do not normally contain toolset-specific rules or actions. They are thus portable among distinct compilers.

• Jamfiles are a lot simpler than Makefiles to write and understand, while providing the same functionality, and much, much more.

Where can I get it?

There are currently two versions of Jam available.

• The classic Jam, which is available, with documentation, from the official Jam homepage at Perforce, the original Jam author.

• An improved version, named ‘FT Jam’, containing several enhancements (like the ability to run on Windows 9x systems, or additional compiler/toolset support). Look here for download information.

We highly recommend that you use FT Jam as it is 100% backwards compatible with classic Jam and can be used as a plug-in replacement for it. The list of changes between these two programs is available here.

Alternatively, FT Jam exists because Perforce hadn't the time to update Jam in a very long time, and we still hope that these improvements will be integrated back to classic Jam as soon as possible.

Why is Jam better than Make?

There really are a lot of reasons, we name just a few of them.

• Compiling simple things with Jam is trivial. However, compiling complex projects (usually with complex directory hierarchies) is still very simple.

• Jam automatically scans source files for #include statements and computes header dependencies automatically, and it does so fast.

• The Jam language is simple and expressive, and lets you define your own build rules, actions, and functions very easily, unlike the ALGOL-like syntax of Makefiles.

• Jam knows about platform-specific directory separators.

• Jam is fully customizable, and easy to extend.

• Jam has a tiny footprint, and is a lot faster than Make at building large projects (independent of target build times, of course).

• We have already mentioned that you don't need to modify Jamfiles in order to compile the same project with distinct compilers and toolsets.

• Jam parses all Jamfiles in a project before beginning to build targets. It knows the full dependency graph and can do parallel builds safely with the ‘-j’ flag.

• Jam is compatible with Autoconf. All configuration-specific definitions are gathered in a single file named ‘Jamrules’ that is shared by all Jamfiles of the same project. The ‘Jamrules’ file is generally generated by processing a ‘Jamrules.in’ template with the ‘configure’ script on Unix systems.

Simple Jam how-to

Assuming that the ‘jam’ executable is in your path (Visual Studio developers may additionally need to set the environment for command-line building, e.g. vcvars32.bat)

Building a project

Go to the project's top-level directory, then type

  jam

If you do not already have the JAM_TOOLSET environment variable set, JAM will display the available options. Set JAM_TOOLSET to the value appropriate for your environment.

Otherwise, this builds your project's file. In case of error, it prints the build command (compilation, link, etc.) that produced it.

Installing a project

Once your project is compiled, type

  jam install

This installs the project (on Unix-like systems).

Cleaning after a build or install

Simply type

  jam clean

To clean all temporary targets, i.e., object files, libraries, executables, etc.

Where to get FT Jam?

While the official Jam 2.5 (on which the current version of FT Jam is based) is available from the Jam homepage, we provide our modified version in several ways.

• Through SourceForge
  Check the package named ftjam on our SourceForge download page. Currently binary packages are available for older versions only.

• Through our FTP mirrors
  Check the directory tools/jam in one of our mirrors.

The Perforce public depot holds older versions of the FT Jam sources; they are located in a directory named //guest/david_turner/jam/src.

Note that we no longer provide a CVS module for our Jam sources, in order to avoid painful synchonisation issues between the CVS repository and the Perforce Public depot.