26.8. Declaring Additional Outputs: the `SideEffect` Function
Prev | Chapter 26. Miscellaneous Functionality | Next

## 26.8. Declaring Additional Outputs: the `SideEffect` Function

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 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 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

Prev | Up | Next
26.7. Finding the Invocation Directory: the `GetLaunchDir` Function | Home | 26.9. Using Python Virtual Environments