Sometimes the way an action is defined causes effects on files
that SCons does not recognize as targets. The SideEffect
method can be used to informs SCons about such files.
This can be used just to flag a dependency for use in subsequent
build steps, although there is usually a better way to do that.
The primary use for the SideEffect
method
is to prevent two build steps from simultaneously modifying
or accessing the same file in a way that could impact each other.
In this example, the rule to build file1
will also put data into log
, which is used
as a source for the command to generate file2
,
but log
is unknown to SCons on a clean
build: it neither exists, nor is it a target output by any builder.
The SConscript
uses
SideEffect
to inform SCons about the additional output file.
env = Environment() f2 = env.Command( target='file2', source='log', action=Copy('$TARGET', '$SOURCE') ) f1 = env.Command( target='file1', source=[], action='echo >$TARGET data1; echo >log updated file1' ) env.SideEffect('log', f1)
Without the SideEffect
, this build would fail with a message
Source `log' not found, needed by target `file2'
,
but now it can proceed:
% scons -Q
echo > file1 data1; echo >log updated file1
Copy("file2", "log")
However, it is better to actually identify
log
as a target, since in this
case that's what it is:
env = Environment() f2 = env.Command( target='file2', source='log', action=Copy('$TARGET', '$SOURCE') ) f1 = env.Command( target=['file1', 'log'], source=[], action='echo >$TARGET data1; echo >log updated file1' )
% scons -Q
echo > file1 data1; echo >log updated file1
Copy("file2", "log")
In general, SideEffect
is not intended for the case when
a command produces extra target files (that is, files which
will be used as sources to other build steps). For example, the
the Microsoft Visual C++ compiler is capable of performing
incremental linking, for which it uses a status file - such that
linking foo.exe
also produces
a foo.ilk
, or uses it if it was already present,
if the /INCREMENTAL
option was supplied.
Specifying foo.ilk
as a
side-effect of foo.exe
is not a recommended use of SideEffect
since foo.ilk
is used by the link.
SCons handles side-effect files
slightly differently in its analysis of the dependency graph.
When a command produces multiple output files,
they should be specified as multiple targets of
the call to the relevant builder function.
The SideEffect
function itself should really only be used
when it's important to ensure that commands are not executed in parallel,
such as when a "peripheral" file (such as a log file)
may actually be updated by more than one command invocation.
Unfortunately, the tool which sets up the Program
builder
for the Microsoft Visual C++ compiler chain does not come prebuilt
with an understanding of the details of the .ilk
example - that the target list would need to change
in the presence of that specific option flag. Unlike the trivial
example above where we could simply tell the Command
builder
there were two targets of the action, modifying the
chain of events for a builder like Program
,
though not inherently complex, is definitely an
advanced SCons topic. It's okay to use SideEffect
here
to get started, as long as it comes with an understanding
that it's "not quite right". Perhaps leave a comment in
the file as a reminder, if it does turn out to cause problems later.
So if the main use is to prevent parallelism problems,
here is an example to illustrate.
Say a program that you need to call to build a target file
will also update a log file describing what the program
does while building the target.
The following configuration
would have SCons invoke a hypothetical
script named build
(in the local directory)
with command-line arguments telling it to write
log information to a common
logfile.txt
file:
env = Environment() env.Command( target='file1.out', source='file1.in', action='./build --log logfile.txt $SOURCE $TARGET' ) env.Command( target='file2.out', source='file2.in', action='./build --log logfile.txt $SOURCE $TARGET' )
This can cause problems when running the build in parallel if SCons decides to update both targets by running both program invocations at the same time. The multiple program invocations may interfere with each other writing to the common log file, leading at best to intermixed output in the log file, and at worst to an actual failed build (on a system like Windows, for example, where only one process at a time can open the log file for writing).
We can make sure that SCons does not
run these build
commands at the same time
by using the SideEffect
function
to specify that updating
the logfile.txt
file
is a side effect of building the specified
file1
and
file2
target files:
env = Environment() f1 = env.Command( target='file1.out', source='file1.in', action='./build --log logfile.txt $SOURCE $TARGET' ) f2 = env.Command( target='file2.out', source='file2.in', action='./build --log logfile.txt $SOURCE $TARGET' ) env.SideEffect('logfile.txt', f1 + f2)
This makes sure the the two
./build steps are run sequentially,
even with the --jobs=2
in the command line:
% scons -Q --jobs=2
./build --log logfile.txt file1.in file1.out
./build --log logfile.txt file2.in file2.out
The SideEffect
function can be called multiple
times for the same side-effect file.
In fact, the name used as a SideEffect
does not
even need to actually exist as a file on disk -
SCons will still make sure
that the relevant targets
will be executed sequentially, not in parallel.
The side effect is actually a pseudo-target, and SCons
mainly cares whether nodes are listed as depending on it,
not about its contents.
env = Environment() f1 = env.Command('file1.out', [], action='echo >$TARGET data1') env.SideEffect('not_really_updated', f1) f2 = env.Command('file2.out', [], action='echo >$TARGET data2') env.SideEffect('not_really_updated', f2)
% scons -Q --jobs=2
echo > file1.out data1
echo > file2.out data2