Build Rules

It was important to keep the SCons syntax similar to the Make syntax so that everyone is comfortable using it. We have created rules for different types of files and figures. Below is an example of a Make rule and the same rule in SCons. The Makefile rule is given by,

RESDIR=./Fig
%.v: %.H
        <$*.H  Grey >/dev/null gainpanel=a pclip=100 title=$* out=$@
${RESDIR}/images.v: image1.v image2.v image3.v
        vp_SideBySideAniso image1.v image2.v image3.v > $@

We assume all ``.H'' files are already made. In the Make rule, we have the targets followed by a colon, then the dependencies. The next lines are indented and give the commands. Here we have two rules: one to make ``.v'' files from ``.H'' files and a second to combine the .v files into a single figure. The % are used as command line wild cards, $* call dependencies, such as RESDIR, $@ is the target. Now look at the same rule in SCons.

RESDIR= ``./Fig''
ResultER(RESDIR+'images.v',['image1.H','image2.H','image3.H'],
         '''
         <${SOURCES[0]} Grey >/dev/null gainpanel=a pclip=100 title="Image 1" out=image1.v;
         <${SOURCES[1]} Grey >/dev/null gainpanel=a pclip=100 title="Image 2" out=image2.v;
         <${SOURCES[2]} Grey >/dev/null gainpanel=a pclip=100 title="Image 3" out=image3.v;
         vp_SideBySideAniso image1.v image2.v image3.v > ${TARGET}
         ''')

In the SCons rule, we have combined both of the previous Make rules. In SCons, first you give the target (or list of targets) then the dependency (or list of dependencies) and then the commands. The triple quotes mean that the command is broken up into more than one line. We can replace a string with a variable. In this case,''./Fig'' has been replaced by RESDIR. Targets and sources can be referred to as ${SOURCES[i]}$ or ${TARGETS[i]}$ if there are multiple sources or targets, where i is the position in the list on the first line. If there is only on source or target they can be called in the build rule as ${SOURCE} or ${TARGET}.

In Make there was no way to distinguish between different build objects except with the RESULTSER/RESULTSCR/RESULTSNR listed at the top of the Makefile. In SCons we adapted rules from RSF for different objects:

• Flow is used to build intermediate files;
• Plot used to view intermediate figure files; and
• ResultER, ResultCR, ResultNR, which are easily-, conditionally-, and con-reproducible results.

The Result commands are used to create anything that should not be removed when a clean is used. ResultER is an easily reproducible result. If there is any change in the rule or the dependency that figure will be rebuilt. ResultCR is a conditionally reproducible result that has one of the following properties:

• require large or proprietary data set
• require parallel processing or special software
• or take 20 minutes or more to build

SCons handles a CR result by first checking to see if the file exists. If the file does not exist, then it is created using the provided build rule. If the file does exist, then it checks to make sure there are rules to build all of the dependencies for that file. If so, then nothing is done. If at least one rule to build a dependency is missing then the build aborts and gives an error message to that affect. ResultNR serves to let the ``tex'' portion know there is a figure and as a place to put commands for figures that could be build, but the data has been lost.