<?xml version='1.0'?>
<!DOCTYPE sconsdoc [
    <!ENTITY % scons SYSTEM "../scons.mod">
    %scons;
    
    <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
    %builders-mod;
    <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
    %functions-mod;
    <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
    %tools-mod;
    <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
    %variables-mod;
]>

<chapter id="chap-sideeffect"
         xmlns="http://www.scons.org/dbxsd/v1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
<title>Sideeffect files</title>

<!--

  __COPYRIGHT__

  Permission is hereby granted, free of charge, to any person obtaining
  a copy of this software and associated documentation files (the
  "Software"), to deal in the Software without restriction, including
  without limitation the rights to use, copy, modify, merge, publish,
  distribute, sublicense, and/or sell copies of the Software, and to
  permit persons to whom the Software is furnished to do so, subject to
  the following conditions:

  The above copyright notice and this permission notice shall be included
  in all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

-->

 <para>

 If &SCons; is unaware that a build step produces an extra file,
 the &SideEffect; method can be used to identify it,
 so that the file can be used as a dependency in subsequent build steps.
 However, the primary use for the &SideEffect; method
 is to prevent two build steps from simultaneously modifying the same file.

 </para>

 <para>
 TODO: currently doesn't work due to issue #2154:
 http://scons.tigris.org/issues/show_bug.cgi?id=2154
 </para>
 
 <para>

 If more than one build step creates or manipulates the same file,
 it can cause unpleasant results if both build steps are run at the same time.
 The shared file is declared as a side-effect of building the primary targets
 and &SCons; will prevent the two build steps from running in parallel.

 </para>

 <para>

 In this example, the <filename>SConscript</filename> uses
 &SideEffect; to inform &SCons; about the additional output file.

 </para>

 <scons_example name="sideeffect_simple">
   <file name="SConstruct" printme="1">
env = Environment()
f2 = env.Command('file2', 'log', Copy('$TARGET', '$SOURCE'))
f1 = env.Command('file1', [],
    'echo >$TARGET data1; echo >log updated file1'))
env.SideEffect('log', env.Command('file1', [],
    'echo >$TARGET data1; echo >log updated file1'))
   </file>
 </scons_example>

 <para>

 Even when run in parallel mode, &SCons; will run the two steps in order:

 </para>

 <scons_output example="sideeffect_simple" suffix="1">
    <scons_output_command>scons -Q --jobs=2</scons_output_command>
 </scons_output>

 <para>

 Sometimes a program the you need to call
 to build a target file
 will also update another file,
 such as a log file describing what the program
 does while building the target.
 For example, we the folowing configuration
 would have &SCons; invoke a hypothetical
 script named <application>build</application>
 (in the local directory)
 with command-line arguments that write
 log information to a common
 <filename>logfile.txt</filename> file:

 </para>

 <screen>
env = Environment()
env.Command('file1.out', 'file.in',
            './build --log logfile.txt $SOURCE $TARGET')
env.Command('file2.out', 'file.in',
            './build --log logfile.txt $SOURCE $TARGET')
 </screen>

 <para>

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

 </para>

 <para>

 We can make sure that &SCons; does not
 run these <application>build</application>
 commands at the same time
 by using the &SideEffect; function
 to specify that updating
 the <filename>logfile.txt</filename> file
 is a side effect of building the specified
 <filename>file1</filename>
 and
 <filename>file2</filename>
 target files:

 </para>

 <scons_example name="sideeffect_shared">
   <file name="SConstruct" printme="1">
env = Environment()
f1 = env.Command('file1.out', 'file1.in',
                 './build --log logfile.txt $SOURCE $TARGET')
f2 = env.Command('file2.out', 'file2.in',
                 './build --log logfile.txt $SOURCE $TARGET')
env.SideEffect('logfile.txt', f1 + f2)
   </file>
   <file name="file1.in">file1.in</file>
   <file name="file2.in">file2.in</file>
   <file name="build" chmod="0755">
cat
   </file>
 </scons_example>

 <para>

 </para>

 <para>

 This makes sure the the two
 <application>./build</application> steps are run sequentially,
 even withthe <filename>--jobs=2</filename> in the command line:

 </para>

 <scons_output example="sideeffect_shared" suffix="1">
    <scons_output_command>scons -Q --jobs=2</scons_output_command>
 </scons_output>

 <para>

 The &SideEffect; function can be called multiple
 times for the same side-effect file.
 Additionally, 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:

 </para>

 <scons_example name="sideeffect_parallel">
   <file name="SConstruct" printme="1">
env = Environment()
f1 = env.Command('file1.out', [], 'echo >$TARGET data1')
env.SideEffect('not_really_updated', f1)
f2 = env.Command('file2.out', [], 'echo >$TARGET data2')
env.SideEffect('not_really_updated', f2)
   </file>
 </scons_example>

 <scons_output example="sideeffect_parallel" suffix="1">
    <scons_output_command>scons -Q --jobs=2</scons_output_command>
 </scons_output>

 <para>

 Note that it might be tempting to
 use &SideEffect; for additional target files
 that a command produces.
 For example, versions the Microsoft Visual C/C++ compiler
 produce a <filename>foo.ilk</filename>
 alongside compiling <filename>foo.obj</filename> file.
 Specifying <filename>foo.ilk</filename> as a
 side-effect of <filename>foo.obj</filename>
 is <emphasis>not</emphasis> a recommended use of &SideEffect;,
 because &SCons; handle 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,
 and 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 updated by more than one command invocation.

 </para>

 </chapter>