diff options
Diffstat (limited to 'doc/user/file-removal.in')
| -rw-r--r-- | doc/user/file-removal.in | 223 |
1 files changed, 0 insertions, 223 deletions
diff --git a/doc/user/file-removal.in b/doc/user/file-removal.in deleted file mode 100644 index 479530c..0000000 --- a/doc/user/file-removal.in +++ /dev/null @@ -1,223 +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> - - There are two occasions when &SCons; will, - by default, remove target files. - The first is when &SCons; determines that - an target file needs to be rebuilt - and removes the existing version of the target - before executing - The second is when &SCons; is invoked with the - <literal>-c</literal> option to "clean" - a tree of its built targets. - - These behaviours can be suppressed with the - &Precious; and &NoClean; functions, respectively. - - </para> - - <section> - <title>Preventing target removal during build: the &Precious; Function</title> - - <para> - - By default, &SCons; removes targets before building them. - Sometimes, however, this is not what you want. - For example, you may want to update a library incrementally, - not by having it deleted and then rebuilt from all - of the constituent object files. - In such cases, you can use the - &Precious; method to prevent - &SCons; from removing the target before it is built: - - </para> - - <scons_example name="precious-ex1"> - <file name="SConstruct" printme="1"> - env = Environment(RANLIBCOM='') - lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) - env.Precious(lib) - </file> - <file name="f1.c"> - int f1() { } - </file> - <file name="f2.c"> - int f2() { } - </file> - <file name="f3.c"> - int f3() { } - </file> - </scons_example> - - <para> - - Although the output doesn't look any different, - &SCons; does not, in fact, - delete the target library before rebuilding it: - - </para> - - <scons_output example="precious-ex1"> - <scons_output_command>scons -Q</scons_output_command> - </scons_output> - - <para> - - &SCons; will, however, still delete files marked as &Precious; - when the <literal>-c</literal> option is used. - - </para> - - </section> - - <section> - <title>Preventing target removal during clean: the &NoClean; Function</title> - - <para> - - By default, &SCons; removes all built targets when invoked - with the <literal>-c</literal> option to clean a source tree - of built targets. - Sometimes, however, this is not what you want. - For example, you may want to remove only intermediate generated files - (such as object files), - but leave the final targets - (the libraries) - untouched. - - In such cases, you can use the &NoClean; method to prevent &SCons; - from removing a target during a clean: - - </para> - - <scons_example name="noclean-ex1"> - <file name="SConstruct" printme="1"> - env = Environment(RANLIBCOM='') - lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) - env.NoClean(lib) - </file> - <file name="f1.c"> - int f1() { } - </file> - <file name="f2.c"> - int f2() { } - </file> - <file name="f3.c"> - int f3() { } - </file> - </scons_example> - - <para> - - Notice that the <filename>libfoo.a</filename> - is not listed as a removed file: - - </para> - - <scons_output example="noclean-ex1"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -c</scons_output_command> - </scons_output> - - </section> - - <section> - <title>Removing additional files during clean: the &Clean; Function</title> - - <para> - - There may be additional files that you want removed - when the <literal>-c</literal> option is used, - but which &SCons; doesn't know about - because they're not normal target files. - For example, perhaps a command you invoke - creates a log file as - part of building the target file you want. - You would like the log file cleaned, - but you don't want to have to teach - SCons that the command - "builds" two files. - - </para> - - <para> - - You can use the &Clean; function to arrange for additional files - to be removed when the <literal>-c</literal> option is used. - Notice, however, that the &Clean; function takes two arguments, - and the <emphasis>second</emphasis> argument - is the name of the additional file you want cleaned - (<filename>foo.log</filename> in this example): - - </para> - - <scons_example name="clean-ex1"> - <file name="S" printme="1"> - t = Command('foo.out', 'foo.in', 'build -o $TARGET $SOURCE') - Clean(t, 'foo.log') - </file> - <file name="SConstruct"> - env = DefaultEnvironment() - import os - env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() - SConscript('S') - </file> - <file name="foo.in"> - foo.in - </file> - <file name="foo.log"> - foo.log - </file> - <file name="build" chmod="0755"> - cat $3 > $2 - </file> - </scons_example> - - <para> - - The first argument is the target with which you want - the cleaning of this additional file associated. - In the above example, - we've used the return value from the - &Command; function, - which represents the - <filename>foo.out</filename> - target. - Now whenever the - <filename>foo.out</filename> target is cleaned - by the <literal>-c</literal> option, - the <filename>foo.log</filename> file - will be removed as well: - - </para> - - <scons_output example="clean-ex1"> - <scons_output_command>scons -Q</scons_output_command> - <scons_output_command>scons -Q -c</scons_output_command> - </scons_output> - - </section> |