Introduction

By default, Jambase.jam is the first Jam file loaded by Jam.

Missing rules

The default Jambase.jam provides implementation of the missing rule function FindMissingRule. That means that Jam makes a good attempt at automatically finding rules that have not been specifically loaded by a script via IncludeModule or include or similar mechanism. FindMissingRule splits the rule name into its components (separated by periods) and then searches the disk for a file of the component name. Each component file found is loaded and tested for the rule name.

For example, if the script asks for C.Application, Jam loads modules/c.jam and looks for a C.Application rule. It will find the C.Application rule and execute it.

As another example, if the script calls CopyFile, Jam will look in modules/copyfile.jam for the CopyFile rule.

If the script wants to execute the rule Assets.Build.Something, the following happens:

modules/assets.jam is loaded. A test is performed for the rule Assets.Build.Something. If it is found, it is executed.
modules/assets/build.jam is loaded. A test is performed for the existence of the rule Assets.Build.Something.
modules/assets/build/something.jam is loaded. A test is performed for the existence of the rule Assets.Build.Something.
Assuming the search made it this far, the rule Assets.Build.Something does not exist. Now, Jam begins looking for a more generic rule called Assets.Build.Something.*.
If that is not found, Assets.Build.* is searched for.
If that is not found, Assets.* is searched for.
If any are found, $(__MISSING_RULE_COMPONENTS) is filled in with the string list Assets Build Something. $(__MISSING_RULE_SCAN_LIST) is filled in with the rules that were searched for and can be used for error reporting.

The following is a list of rules available in bin/Jambase.jam.

If [square] brackets are used the argument is optional.

rule ActiveTarget TARGET

Set the default target to use when the target isn't specified. Calls rule C.ActiveTarget TARGET under the hood.

Parameters

TARGET The default target name to use for upcoming rules.

rule AutoSourceGroup [ TARGET ] [ : SOURCES ]

For workspace projects that support grouping of files into folders, the AutoSourceGroup rule is used to tell the

jam --workspace

generator to create folders within a project based on the relative paths of the SOURCES.

Parameters

TARGET	(optional) The project for which the folders will be created. If no project is specified, `AutoSourceGroup` will be automatically applied to all projects.
SOURCES	(optional) The list of files to derive folder names from.

# Put helloworld.cpp and .h in the top-level project folder.
# Put filename.cpp and .h in a project folder called platform\\directory (in SourceGroup syntax).
SRCS =
        helloworld.cpp
        helloworld.h
        platform/directory/filename.cpp
        platform/directory/filename.h
;
 
# Apply to every project:
AutoSourceGroup ;
 
# or just a specific project:
AutoSourceGroup MyProject : $(SRCS) ;

rule Clean TARGETS : FILES

When executing actions for TARGETS, the specified list of FILES are removed from the disk, and any empty directories resulting from the file deletions are removed, too.

Parameters

TARGETS	A list of one or more targets. Generally, the target name is `clean` or `clean:SOMETARGET`.
FILES	A list of files to be deleted.

Clean clean : <mytarget>myfile.txt $(TEMP)/anotherfile.txt ;

rule CleanTree TARGETS : DIRECTORIES

When executing actions for TARGETS, the specified list of DIRECTORIES are removed from the disk.

Parameters

TARGETS	A list of one or more targets. Generally, the target name is `clean` or `clean:SOMETARGET`.
DIRECTORIES	A list of directories to be deleted.

CleanTree clean : $(TEMP)/a/directory ;

rule ExternalProject PROJECT_NAME : PROJECT_PATH

When generating a workspace, it can sometimes be useful to include projects that are not generated by the Jam workspace generator. These projects can be made available via a combination of the ExternalProject and Workspace rules.

Currently, only external projects are supported within Visual Studio 201x and must be either .vcxproj or .csproj project files.

Parameters

PROJECT_NAME	The name of the project.
PROJECT_PATH	The path to the project file to include in the workspace.

ExternalProject MyClassLibrary : $(TOP)/MyClassLibrary/MyClassLibrary.csproj ;

Workspace testapp : MyClassLibrary ;

rule FGristDirectories DIRECTORIES

Given a list of DIRECTORIES, a gristed version of each is returned. Currently, this means the directories are returned in the form: <!dir!>directory/name

Parameters

DIRECTORIES The directories to grist.

Returns: Returns the gristed version of each directory.

Echo [ FGristDirectories $(TEMP)/stuff ] ;

rule IncludeModule MODULE_NAME

Loads a Jam module. It searches in the following manner:

The current $(SUBDIR)
The current working directory $(CWD)
The current working directory $(CWD)/jam/
$(JAM_MODULES_USER_PATH)
$(JAM_MODULES_PATH) which includes the bin/modules/ directory

When IncludeModule is specified more than once for the same MODULE_NAME, the module is only loaded once.

Parameters

MODULE_NAME The name of the module, which is the filename without an extension.

Returns: Returns the module name if successful. If the MODULE_NAME was not found, nothing is returned.

# Make the C.UseDirectX rule available.

IncludeModule c/directx ;

rule MakeLocate TARGETS : DIRECTORY : OPTIONS

Creates DIRECTORY and causes TARGETS to be built into the directory. It does so by setting the special Jam variable LOCATE on each of the TARGETS and then arranges with rule MkDir DIRECTORY to create the target directory.

Parameters

TARGETS	The targets to set the output directory on.
DIRECTORY	The output directory to build the targets into.
OPTIONS	If `combine` is specified, then any directory attached to the `TARGETS` name is created, and a `BINDING` is set to allow the target to work properly.

# Set the output location of the given target to be the TEMP directory.
MakeLocate junkfile.txt : $(TEMP) ;
 
# Creates the directory $(TEMP)/abc/def, sets the LOCATE for target abc/def/file.txt
# to $(TEMP)/abc/def and sets the BINDING to be file.txt.
MakeLocate abc/def/file.txt : $(TEMP) : combine ;

rule MkDir DIRECTORY

Creates DIRECTORY and its parent directories.

If using MkDir separately from rule MakeLocate TARGETS : DIRECTORY : OPTIONS, it is necessary to set dependencies using the properly gristed directory name obtained through rule FGristDirectories DIRECTORIES.

Parameters

DIRECTORY The output directory to create.

# Create a directory in the TEMP directory called stuff/.
MkDir $(TEMP)/stuff ;
 
# Link it into the dependency graph.
Depends sometarget : [ FGristDirectories $(TEMP)/stuff ] ;

rule NoWorkspace WORKSPACE_NAME

Workspaces are automatically generated for any executable processed while reading in the Jamfiles. To prevent a workspace from automatically exporting, this rule is used.

Parameters

WORKSPACE_NAME The name of the new workspace to suppress the export of.

NoWorkspace lua ;

rule Project PROJECT_NAME : SOURCES

When generating a workspace, projects are automatically made of each executable or library processed while reading in the Jamfiles. When a project isn't an executable or library, such as one containing data files, the Project rule can be used to generate a project containing those files.

Parameters

PROJECT_NAME	The name of the new project to generate.
SOURCES	The list of files representing the contents of the new project.

Project Data : $(DATA_FILES) ;

rule ProjectGroup TARGET : FOLDERNAME : PROJECTS

For workspaces that support grouping of projects into folders, the ProjectGroup rule is used to tell JamToWorkspace which projects go into which folders.

Parameters

TARGET	The workspace to which the project folders will be created.
FOLDERNAME	The backslash separated folder name to which `PROJECTS` will be inserted into.
PROJECTS	The list of projects to put into the folder.

ProjectGroup MyApp : "Plugins\\Data Generators" : DataGeneratorA DataGeneratorB ;

rule RmTemps TARGETS : SOURCES

Marks SOURCES as temporary with the Temporary rule and deletes SOURCES once TARGETS are built. RmTemps must be the last rule invoked on TARGETS. Used internally.

rule SearchSource SOURCES

Applies $(SEARCH_SOURCE) to all SOURCES that do not already have a SEARCH applied. Generally, SEARCH_SOURCE is applied through rules just as Application or Library.

Parameters

SOURCES The list of sources to apply $(SEARCH_SOURCE) to.

SearchSource $(SRCS) ;

rule SourceGroup TARGET : FOLDERNAME : SOURCES

For workspace projects that support grouping of files into folders, the SourceGroup rule is used to tell JamToWorkspace which files are to be placed into which folders within a project.

Parameters

TARGET	The project to which the folders will be created.
FOLDERNAME	The backslash separated folder name to which `SOURCES` will be inserted.
SOURCES	The list of files to put into the folder.

SourceGroup Misc : "zlib" : $(ZLIB_SRCS) ;

SourceGroup Misc : "string\\trio" : $(TRIO_SRCS) ;

rule SubDir VAR d1...dn : TARGET_DIRECTORY : OPTIONS

Sets up housekeeping for the source files located in /d1/.../dn:

Reads in rules file associated with VAR, if it hasn't already been read.
Initializes subdirectory specific variables for search paths, output directories, compiler flags, and grist, using d1...dn tokens.

Parameters

VAR	The name of a variable
d1...dn	Additional directory components from making up the total path of `/d1/.../dn/`.
TARGET_DIRECTORY	(optional) Additional directory components building `LOCATE_SOURCE` and `LOCATE_TARGET`.
OPTIONS	(optional) If `register` is specified, then the subdirectory internal variables are set up, but no Jamfile is read and no SubDir change occurs.

rule SubInclude VAR d1...dn : FILENAME : OPTIONS

Reads the Jamfile in /d1/.../dn/. Assumes a default Jamfile name of Jamfile.jam. If FILENAME is specified, .jam is read instead of Jamfile.jam.

A given Jamfile is only ever read in once, even if multiple SubInclude calls are made with the same arguments.

Internal detail: If the variable SubInclude_PreInclude is set, the rule specified in SubInclude_PreInclude is executed before the Jamfile is included.

Parameters

VAR	A previously specified `TOP` variable created with rule SubDir VAR d1...dn : TARGET_DIRECTORY : OPTIONS.
d1...dn	Additional directory components from making up the total path of `/d1/.../dn/`.
FILENAME	(optional) If specified, a Jamfile called `.jam` is read instead of the default `Jamfile.jam`. If a second list item for `FILENAME` is specified, then that is used as the calculated target name for this rule SubDir VAR d1...dn : TARGET_DIRECTORY : OPTIONS transition. Otherwise, the base of `FILENAME` is used as the target name.
OPTIONS	(optional) If `nocare` is specified, then `FILENAME` does not have to exist. See rule SubDir VAR d1...dn : TARGET_DIRECTORY : OPTIONS for further `OPTIONS`.

rule SubIncludeRelative RELATIVE_PATH : FILENAME : OPTIONS

After a SubDir rule has been called, SubIncludeRelative can be used to move within the SubDir structure. Currently, it only works traversing into child directories. It cannot be used with a .. to move to a parent directory.

Further information may be found in SubInclude.

Parameters

RELATIVE_PATH	The relative child directory to move into.
FILENAME	(optional) See SubInclude.
OPTIONS	(optional) See SubInclude.

SubDir TOP ;
 
# ...
 
SubIncludeRelative MyProject ;  # The same as: SubInclude TOP MyProject

rule Workspace WORKSPACE_NAME : TARGETS

Workspaces are automatically generated for any executable processed while reading in the Jamfiles. To create additional workspaces, such as one that combines all executables into one workspace, the Workspace rule is used.

Parameters

WORKSPACE_NAME	The name of the new workspace to generate.
TARGETS	The list of targets representing the projects of the new workspace.

Workspace Project-all : AppA AppB AppC ;

rule WorkspaceConfig WORKSPACE_NAME : CONFIG_NAME : JAM_CONFIG_NAME : COMMAND_LINE

Usually, configurations are created in a workspace according to the VALID_CONFIGS variable found within the generated workspace's Jambase.jam. These configurations can come from the defaults or from a config file passed to 'jam –workspace'.

Using the WorkspaceConfig rule, the default generated configurations can be overridden for a given generated workspace/solution.

Each user-specified workspace config gets its Jam command-line replaced entirely with the one specified on the WorkspaceConfig invocation. For that reason, it is very important to provide the C.TOOLCHAIN variable to the command-line, or Jam will not know what compiler, platform, and configuration it is building.

Please make note that workspace configurations are not Jam configurations, so confusion may arise. Assumptions about output and intermediate directories are made based on the platform and config specified via C.TOOLCHAIN. Unless Jam rules are altered from the shipping defaults, there is not a unique intermediate and output location per provided WorkspaceConfig.

In reality, a WorkspaceConfig is a hack. Just modify the generated customsettings.jam file instead, as it better represents what is actually happening within the build.

Parameters

WORKSPACE_NAME	The name of the workspace to modify.
CONFIG_NAME	The name of the new configuration for the workspace.
JAM_CONFIG_NAME	The name of the Jam build configuration being built on top of.
COMMAND_LINE	Any additional command line parameters to pass on the Jam command-line for this `CONFIG_NAME`.

# Generate workspaces with the following configs:
#
#   * debug_d3d
#   * debug_opengl
#   * debug_sdl
#   * release_d3d
#   * release_opengl
#   * release_sdl
if $(JAM_CREATING_WORKSPACE) {
    local config ;
    for config in debug release {
        local engine ;
        for engine in d3d opengl sdl {
            WorkspaceConfig $(THE_WORKSPACE_NAME) : $(config)_$(engine) : $(config) : C.TOOLCHAIN=$(DOLLAR)(PLATFORM)/$(config) THE_ENGINE=$(engine) ;
        }
    }
}

actions WriteFile TARGETS

WriteFile is an action that writes the setting CONTENTS to the specified TARGETS.

To ensure changes in CONTENTS are written to the TARGETS, use rule UseCommandLine TARGETS : COMMANDLINE; to signify changes.

Parameters

TARGETS The targets to write to.

CONTENTS on abc.txt = "abcdefghijklmnopqrstuvwxyz" ;
UseCommandLine abc.txt : $(CONTENTS:Z=abc.txt) ;
WriteFile abc.txt ;

rule WriteFileContents TARGETS : CONTENTS

Use WriteFileContents to write CONTENTS into the file(s) specified by TARGETS.

This is a wrapper over the top of actions WriteFile TARGETS.

Its implementation is:

rule WriteFileContents TARGETS : CONTENTS
{
    CONTENTS on $(TARGETS) = $(CONTENTS) ;
    UseCommandLine $(TARGETS) : $(CONTENTS) ;
    WriteFile $(TARGETS) ;
    return $(TARGETS) ;
}

Parameters

TARGETS The targets to write to.

WriteFileContents abc.txt : "abcdefghi jklmnopqrstuv wxyz" ;