Jam Documentation
Jam is a software build tool that makes building simple things simple and building complicated things manageable. It has been freely available as C source for many years from the Perforce Workshop and is widely used to build commercial and academic software. Jam is a very good solution for conventional C/C++ compile-and-link builds.
Because Jam understands C/C++ dependencies, there is no need to declare header or object files. The built-in Jam rule "Main" handles header file dependencies and object files both automatically and on-the-fly. Table 1 compares a Makefile and a Jamfile for building a simple program.
Jamfile | Makefile |
| Main proga : data.c main.c io.c ; | proga: data.o main.o io.o cc data.o main.o io.o -o proga data.o: data.c data.h cc -c data.c main.o: data.h io.h main.c cc -c main.c io.o: io.h io.c cc -c io.c |
Table 1 - Jamfile vs Makefile for compiling a simple C program
Before any targets are updated, Jam gathers complete dependency information for C/C++ source files, allowing Jam to:
- Build as much as possible, instead of halting on the first build error.
- Avoid building targets if targets on which they depend fail to build.
- Build across parallel paths with multiple, concurrent processes.
Additional Jam features
| Unintrusive and clean | Jam is small, it has negligible CPU overhead, and it doesn't create or leave behind temporary files. |
| Scalable | Jam is able to build large projects spread across many directories in a single pass and can manage and distribute build steps to multiple processors on one or more networked machines. |
| Highly portable | Jam runs on UNIX, VMS, NT, OS/2, Mac OS X, and Mac MPW. Most Jamfiles (like the sample above) are also portable. |
| Multiplatform | Platform independent rules and platform specific actions can be defined separately from dependency rules. |
| Customizable | Developers can enhance/extend Jam by creating user defined rules to utilize other built-in directives. |
| Language | Jam includes flow-control statments, variables, and a few other features of general purpose languages. |
| Free | Jam is free and can be incorporated into commercial products without licensing restrictions. |
Getting the Source
The source for Jam is freely available from the Perforce Workshop.
White Papers and Examples
Jam has been around since 1993 and has a long history of use in many different settings. Here are some white papers and examples of Jam in use:
- Getting Started with Jam - A Tutorial (PDF) - from the 2001 Perforce User Conference.
- The UNIX Application Development Symposium paper on Jam - Jam product overview (1994).
- Constructing a Large Product with Jam - an experience report from SCM7, the 7th International Workshop on Software Configuration Management, Boston, May 1997.
- Getting and Building the Haiku Source Code with Jam
- Comparing the Jam language to other programming languages
Documentation
- Jam.html - Jam man page - a terse description of Jam and its language.
- Jambase.html - Reference for the rule boilerplate file.
- Jamfile.html - Easy reading on creating a Jamfile and using jam.
- RELNOTES - Current release notes.
- Porting - Notes on porting jam to wildcat platforms.
- README - Installation instructions.
- jam.c - Contains jam's main() as well as an introduction to the code, for serious hackers.
Support
Jam comes with no warranties or guarantees and is not supported by Perforce.
Release History
- November, 1993 - release 1.0
- March, 1995 - release 2.0
- February, 1996 - release 2.1
- November, 1997 - release 2.2
- December, 2000 - release 2.3
- March, 2002 - release 2.4
- April, 2003 - release 2.5
- August, 2014 - release 2.6