%scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]>

Sometimes the way an action is defined causes effects on files that &SCons; does not recognize as targets. The &f-link-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 &f-SideEffect;, this build would fail with a message Source `log' not found, needed by target `file2', but now it can proceed: scons -Q 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 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/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 &b-Program; builder for the MSVC 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 &b-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) file1.in file2.in cat This makes sure the the two ./build steps are run sequentially, even with the --jobs=2 in the command line: scons -Q --jobs=2 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