diff options
Diffstat (limited to 'doc/user/sideeffect.in')
| -rw-r--r-- | doc/user/sideeffect.in | 216 |
1 files changed, 0 insertions, 216 deletions
diff --git a/doc/user/sideeffect.in b/doc/user/sideeffect.in deleted file mode 100644 index ece0300..0000000 --- a/doc/user/sideeffect.in +++ /dev/null @@ -1,216 +0,0 @@ -<!-- - - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation - - 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> - - TODO: currently doesn't work due to issue #2154: - http://scons.tigris.org/issues/show_bug.cgi?id=2154 - - <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="SideEffectSimple"> - <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="SideEffectSimple"> - <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="SideEffectShared"> - <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="SideEffectShared"> - <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="SideEffectParallel"> - <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="SideEffectParallel"> - <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> |