Simple Transform Overview

Setup

Add a file called source.txt to the directory with the contents:

# source.txt

source

Transform source to destination

We want to build a file destination.txt from source.txt. This involves setting a dependency between the two files using rule Depends targets1 : targets2 [ : target3 ... targets9 ] ;. We will depend the default all target on def.txt for simpler command-line usage. Additionally, def.txt will be added to the clean target.

//! [Adding dependencies]
local source = source.txt ;
local destination = destination.txt ;
 
# all -> destination.txt -> source.txt
Depends all : $(destination) : $(source) ;
Clean clean : $(destination) ;
//! [Adding dependencies]
 

Adding dependencies

# Jamfile.jam
local source = source.txt ;
local destination = destination.txt ;
 
# all -> destination.txt -> source.txt
Depends all : $(destination) : $(source) ;
Clean clean : $(destination) ;

Running jam at this point will not do anything, as we have not yet set up the action. We will call the action ConvertFile and cause it to create a copy of the source file and append extra destination text to the destination file.

# Jamfile.jam
local source = source.txt ;
local destination = destination.txt ;
 
Depends all : $(destination) : $(source) ;
Clean clean : $(destination) ;
 
# CAT comes from Jambase.jam and is either 'type' on Windows or 'cat' on non-Windows.
actions ConvertFile
{
    $(CAT) $(2) > $(1)
    echo extra destination text >> $(1)
}
 
# The first parameter to an action is the destination target(s). The second parameter to an action is the source target(s).
ConvertFile $(destination) : $(source) ;

Running jam yields:

# Shell
> jam
    found 3 target(s)...
    updating 1 target(s)...
@ ConvertFile destination.txt
    updated 1 target(s)...

On disk will be the new file destination.txt.

Build behaviors

There have been no changes to source.txt, so running jam again shows there is nothing to be done:

# Shell
> jam
    found 3 target(s)...

Modify source.txt:

# source.txt

The modified source

As we would expect, running jam now with the modified source.txt causes a build to run for destination.txt.

# Shell
> jam
    found 3 target(s)...
    updating 1 target(s)...
@ ConvertFile destination.txt
    updated 1 target(s)...

If the timestamp of source.txt is ever later than destination.txt, Jam will cause the ConvertFile action to run.

Applying UseCommandLine

In addition to a timestamp update, sometimes we want to force a build anyway.

An incorrect way of doing this is to use the rule Always targets ; flag to mark the target as always needing to build.

# Jamfile.jam
local source = source.txt ;
local destination = destination.txt ;
 
Depends all : $(destination) : $(source) ;
Clean clean : $(destination) ;
Always $(destination) ;
 
actions ConvertFile
{
    $(CAT) $(2) > $(1)
    echo extra destination text >> $(1)
}
 
ConvertFile $(destination) : $(source) ;

Running jam will build destination.txt.

# Shell
> jam
    found 3 target(s)...
    updating 1 target(s)...
@ ConvertFile destination.txt
    updated 1 target(s)...

Running jam again will build destination.txt again. And again. And again.

The goal of using a tool like Jam is to get it to identify what actually needs to be done and only do that and nothing more.

Instead, we can use rule UseCommandLine TARGETS : COMMANDLINE; to add some extra text into the build calculation such that changing the text will result in a forced build regardless of timestamp change.

# Jamfile.jam
local source = source.txt ;
local destination = destination.txt ;
 
Depends all : $(destination) : $(source) ;
Clean clean : $(destination) ;
UseCommandLine $(destination) : now-on-version-2 ;
 
actions ConvertFile
{
    $(CAT) $(2) > $(1)
    echo extra destination text >> $(1)
}
 
ConvertFile $(destination) : $(source) ;