Introduction

JCons is a Make replacement, i.e. a program for building other programs. JCons is designed to build C/C++ programs, but any files that are produced in a well defined manner can be created under the control of JCons. As can be guessed from the name, JCons’ main inspiration is Cons, the make tool written in Perl (described in the Spring 1998 issue of “The Perl Journal”). To my knowledge Cons was the first make tool to combine a number of interesting ideas:

• The build description files can be programs written in an existing language (e.g. Perl), instead of using a description language that is unique to the make tool (e.g. Makefile-syntax or Jam-files).
• Cryptographic checksums can be used to get more reliable dependency checking than that provided by Make, where file timestamps are used to decide if a file should be rebuilt.
• Automatic detection of #include file dependencies makes building of C/C++ programs much more reliable.

JCons tries to steal most of the good ideas of Cons. But there are important differences too, for example:

• JCons uses Python as its primary language for description files.
• JCons can build in parallel.
• JCons is much faster than Cons when doing an up-to-date check.

The ideas pioneered by Cons are not so special today over fifteen years later. A number of similar tools exist, most notably SCons (also inspired by Cons). Compared to SCons, JCons is quite minimalistic and lacks many features.

So why develop JCons? First, because it was fun. Writing a make tool seems quite easy in the beginning. But to get a reliable, fast and useful tool requires attention to many small details. This has been an interesting challenge. Second, because I believe JCons does some things better than both Cons and SCons. JCons is for example much faster than both Cons and SCons.

About this document

The rest of this document tries to describe how to use JCons. First a simple example will be given to illustrate the overall way JCons works. Then a guide to the different JCons features follows. And finally a reference part will describe all the details.

If you have used Cons before, you should recognize many things. The biggest difference from Cons is of course that JCons uses Python as scripting language instead of Perl.

The examples in the text have actually been executed as real commands. This should ensure that they stay correct at all times.

How JCons works

1. JCons looks for a file construct.py, and loads it as Python code. The file has the same role for JCons as the Makefile has for Make.
2. The code in construct.py should call methods in the Cons class. These methods are used to inform JCons what things there are to build.
3. Once the construct.py has been read, JCons uses the collected information to start its build engine.

A minimal example of using JCons is given below:

# construct.py
e = Cons()
e.command("readme.pdf", "readme.ps",  "ps2pdf %INPUT %OUTPUT")
e.command("readme.ps",  "readme.txt", "enscript -q %INPUT -o %OUTPUT")

The calls to Cons.command() tells JCons how the output files can be produced from the input files:

$ echo a line of text > readme.txt   # create source file
$ jcons
enscript -q readme.txt -o readme.ps
ps2pdf readme.ps readme.pdf
$ jcons                             # nothing to do 2nd time
jcons: up-to-date: .
$ echo one more line >> readme.txt
$ jcons                             # input file has changed
enscript -q readme.txt -o readme.ps
ps2pdf readme.ps readme.pdf

All methods of the Cons class are of this type. Each method is useful in a different situation: program to build a program, static_library to create a library, etc. But all methods could in principle have been implemented on top of the command method.