Documentation

There is very little documentation at this time for JamPlus, but I am writing it as quickly as possible. For now, I will just concentrate on the new JamPlus features.

Update: There is a great deal of JamPlus now documented in the source code distribution's docs/ directory. Those sections now documented within the distribution are marked as (Documented) below.

Jam Executable

(Documented) The Jam executable has several new command line options:

  • (Documented) -Ccurrent/working/directory - Set the initial startup current working directory as if Jam was executed from directly from that directory.
  • (Documented) -df - Fate changes.
  • (Documented) -dg - Dump a detailed dependency graph.
  • (Documented) -dh - Show everything going into the calculation of the md5sums for the file cache.
  • (Documented) -dM - Show more verbose information about the build.
  • (Documented) -dT - Show memory totals.
  • (Documented) -T - Toggle printing of a target's name.

Other miscellaneous changes:

  • (Documented) The number of active JamPlus jobs defaults to the NUMBER_OF_PROCESSORS environment variable.
  • (Documented) The current working directory is made available to Jamfiles via the CWD variable.
  • (Documented) The path containing the jam.exe is stored as JAM_PROCESS_PATH.
  • (Documented) More detailed reporting of time elapsed and percentage of the build complete.
  • (Documented) Changed ... text globally to *** to work better in the Visual Studio IDE.

(Documented) -= Operator

The -= operator is the reverse of the += operator. The -= operator removes any elements from the left hand list that are in the right hand list.

See source:tests/minusequals/

(Documented) Lua Support

See Lua Support.

(Documented) BINDING on a Target

When the BINDING variable is set on a given target, the contents of BINDING are used as the filename portion of the bound name. LOCATE and SEARCH are still processed as normal.

See source:tests/bindingname/testbindingname.jam.

(Documented) Command-line Dependency

The "command line" of a target (not necessarily the real command line... just some unique string) is compared against the previous build's command line for the same target. If it differs, regardless of timestamps being equal, the target is rebuilt. JamPlus is told about the command line through the UseCommandLine rule.

Example: During the last build, the #defines for a somefile.cpp file were -DMYDEFINE -DSOMEDEFINE. The user then alters the defines for somefile.cpp to be -DMYDEFINE -DYOURDEFINE. somefile.cpp file will be rebuilt, even though the timestamp hasn't changed.

UseCommandLine somefile.cpp : -DMYDEFINE -DYOURDEFINE ;

Example 2: The file format for .model files changes. It is desirable to cause the .model files to be rebuilt on the next build. This can be done by altering the 'command line' to be 'version2'.

UseCommandLine $(TARGETS) : version2 ;

(Documented) Dependency (Header) Cache

JamPlus contains an enhanced version Craig McPheeters' header cache patch. Most notably, JamPlus' version of the code has the ability to enable more than one dependency cache and stores the md5 information for the file cache and the md5 information for the command line in the dependency cache, too.

(Documented) Multiple Caches

The default dependency cache is known as standard. The location of the dependency cache must be specified in the form:

DEPCACHE.standard = $(ALL_LOCATE_TARGET)/.depcache ;

When a given target needs to be assigned to an alternate dependency cache, the UseDepCache rule is used:

UseDepCache $(TARGET) : platform ;

(Documented) Shelling Processes

When HDRPIPE is set on a target, during the dependency scan for headers, the process command line specified by HDRPIPE is run. Any dependencies printed by the process to stdout are run through the normal HDRSCAN regular expression mechanism.

If HDRPIPEFILE is set on the target, then the filename specified by HDRPIPEFILE is opened and parsed for dependencies after the HDRPIPE process exits.

(Documented) Filtering Unwanted Dependencies

When HDRFILTER is set on a target to a rule name, the rule bearing that name is executed with the following signature.

rule DoHeaderFilter TARGET_NAME : DEPENDENCIES : TARGET_BOUNDNAME
{
    # Filter any unwanted dependencies.
    return $(NEW_DEPENDENCIES) ;
}

(Documented) No Downshift

By default on Windows, header file names are converted to lowercase. This can be prevented by setting a target's HDRDOWNSHIFT to false.

(Documented) Depends Rule (Update)

The Depends rule can now specify a chain of dependencies:

Depends $(TARGETS) : $(SOURCES) : $(SOME_OTHER_TARGETS) : $(AND_SO_ON) ;

(Documented) Expansion of Rule Names

When running a rule, the name of the rule may use typical expansion modifiers.

FLAG = Dirty ; # or clean

rule MarkDirty
{
}

rule MarkClean
{
}

Mark$(FLAG) ;

(Documented) Glob Rule

The Glob rule has been enhanced to return directories with a closing /, so files and directories may be distinguished. In addition, the third argument to the rule may be set to 0 to disallow Glob from prepending the starting directory on each filename.

(Documented) Math Rule

Since Jam has no mathematical functionality in its language, basic math functionality is available through the Math rule. See the source:tests/math/math.jam sample for more information.

(Documented) maxtargets

When batching, the action can specify maxtargets # to limit the number of source files passed to the action's command each time.

See source:tests/batch/Jamfile.jam.

(Documented) MD5 Rules

MD5 and MD5File (fill me in).

(Documented) Multiple Passes

The QueueJamfile rule queues up a Jamfile to be executed immediately after the actions for the current pass are run.

(Documented) Needs Rule

The Needs rule is used when a set of dependencies are required for the build to proceed, but no dependency on timestamps is required. Fill me in more...

Needs $(TARGETS) : $(SOURCES) ;

(Documented) Network File Cache

Built into JamPlus is a MD5sum based network cache. The network cache can be applied to any target through the UseFileCache rule. There can be one or more categoric network caches made available to the build. The author of the network cache code is Alen Ladavac.

A network cache is defined with the following settings.

FILECACHE.cachename.PATH = \\\\uncshare\\networkcache\\cachename ;
FILECACHE.cachename.GENERATE = 1 ;
FILECACHE.cachename.USE = 1 ;

To assign a file cache to a given target:

UseFileCache $(TARGET) : cachename ;

(Documented) Response Files

Response files are made available by adding the modifier response to an action. Within the action, (at)(stuff to write out) is used to make a temporary response file. (Figure out how to do at signs in Redmine's Textile.)

(Documented) Semaphores

By setting the SEMAPHORE variable on a target, serialized execution of targets containing the same semaphore is performed. This solves issues, for instance, with the Visual C++ compiler accessing the same .pdb and .idb file from multiple processes.

(Documented) Serial Output

Multiprocess output is kept separate and displayed all at once when the process completes. This prevents interleaving of unrelated output from multiple concurrently running processes.

(Documented) Variable Expansion

The following new variable expansion modifiers are available in JamPlus:

  • $(VAR:/) - Convert all backslashes (\) to slashes (/).
  • $(VAR:\\) - Convert all slashes (/) to backslashes (\).
  • $(VAR:I=regex) - From VAR, only return those list items that match regex.
  • $(VAR:X=regex) - From VAR, only return those list items that do not match regex.
  • $(VAR:W) - Wilcard glob files on the disk. Supports all features as described at http://www.codeproject.com/KB/files/fileglob.aspx.
  • (at)(The string) - Expand the literal contents The string. (Pardon the syntax. I don't know how to get an (at) symbol to show up in Redmine.

Examples: source:tests/substitution/substitution.jam and source:tests/substitution/testwildcards.jam

(Documented) Windows Registry Access

Document W32_GETREG. There is an example in source:bin/Jambase.jam.

(Documented) Workspace Generation Scripts

JamPlus comes equipped with a number of scripts suitable for generating workspaces and Jamfiles from .vcproj files or existing directory structures. All scripts reside in the bin/scripts/ directory.

  • (documented) FoldersToJamfile: This script recursively scans files from the current working directory and outputs a Jamfile with the file list and SourceGroup breakdowns to create project folders within IDEs that support it.
  • (documented) JamToWorkspace: Given a set of Jamfiles making up a project, JamToWorkspace outputs a workspace suitable for usage within an IDE given on the command line. Examples of its usage are in the source:samples/ directory.
  • (documented) VCProjToJamfile: For a .vcproj, a Jamfile is output containing the files and folder structure from the .vcproj. Not all features of a .vcproj are output in the current version of this script.

(Documented) Writing a Text File

Within an action, a text file may be written by use the ^^(filename|contents) syntax. See WriteFile in source:bin/Jambase.jam.

Recipes

  • ...

Samples

For any sample, run CreateVS2005Workspace.bat to create a Visual Studio 2005 capable workspace.

The samples can be found in source:samples/

  • helloworld - A simple Hello, World sample. Run CreateVS2005Workspace.bat to create a Visual Studio 2005 capable workspace.
  • projects - Illustrates the creation of multiple custom projects within the workspace.
  • sharedlib - Creates multiple DLLs and statically links an application against the DLLs' import libraries.
  • simplemfc - An AppWizard created MFC example converted to Jam. Illustrates how to use lumping in conjunction with precompiled headers.
  • simplewx - The wxWidgets auidemo example converted to Jam.