doc/user/file-removal.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE sconsdoc [
   3     <!ENTITY % scons SYSTEM "../scons.mod">
   4     %scons;
   5
   6     <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
   7     %builders-mod;
   8     <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
   9     %functions-mod;
  10     <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
  11     %tools-mod;
  12     <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
  13     %variables-mod;
  14
  15 ]>
  16
  17 <chapter id="chap-file-removal"
  18          xmlns="http://www.scons.org/dbxsd/v1.0"
  19          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  20          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  21 <title>Controlling Removal of Targets</title>
  22
  23 <!--
  24
  25   __COPYRIGHT__
  26
  27   Permission is hereby granted, free of charge, to any person obtaining
  28   a copy of this software and associated documentation files (the
  29   "Software"), to deal in the Software without restriction, including
  30   without limitation the rights to use, copy, modify, merge, publish,
  31   distribute, sublicense, and/or sell copies of the Software, and to
  32   permit persons to whom the Software is furnished to do so, subject to
  33   the following conditions:
  34
  35   The above copyright notice and this permission notice shall be included
  36   in all copies or substantial portions of the Software.
  37
  38   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  39   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  40   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  41   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  42   LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  43   OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  44   WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  45
  46 -->
  47
  48   <para>
  49
  50   There are two occasions when &SCons; will,
  51   by default, remove target files.
  52   The first is when &SCons; determines that
  53   an target file needs to be rebuilt
  54   and removes the existing version of the target
  55   before executing
  56   The second is when &SCons; is invoked with the
  57   <literal>-c</literal> option to "clean"
  58   a tree of its built targets.
  59
  60   These behaviours can be suppressed with the
  61   &Precious; and &NoClean; functions, respectively.
  62
  63   </para>
  64
  65   <section>
  66   <title>Preventing target removal during build: the &Precious; Function</title>
  67
  68     <para>
  69
  70     By default, &SCons; removes targets before building them.
  71     Sometimes, however, this is not what you want.
  72     For example, you may want to update a library incrementally,
  73     not by having it deleted and then rebuilt from all
  74     of the constituent object files.
  75     In such cases, you can use the
  76     &Precious; method to prevent
  77     &SCons; from removing the target before it is built:
  78
  79     </para>
  80
  81     <scons_example name="fileremoval_precious-ex1">
  82       <file name="SConstruct" printme="1">
  83   env = Environment(RANLIBCOM='')
  84   lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
  85   env.Precious(lib)
  86       </file>
  87       <file name="f1.c">
  88 int f1() { }
  89       </file>
  90       <file name="f2.c">
  91 int f2() { }
  92       </file>
  93       <file name="f3.c">
  94 int f3() { }
  95       </file>
  96     </scons_example>
  97
  98     <para>
  99
 100     Although the output doesn't look any different,
 101     &SCons; does not, in fact,
 102     delete the target library before rebuilding it:
 103
 104     </para>
 105
 106     <scons_output example="fileremoval_precious-ex1" suffix="1">
 107         <scons_output_command>scons -Q</scons_output_command>
 108     </scons_output>
 109
 110     <para>
 111
 112     &SCons; will, however, still delete files marked as &Precious;
 113     when the <literal>-c</literal> option is used.
 114
 115     </para>
 116
 117   </section>
 118
 119   <section>
 120   <title>Preventing target removal during clean: the &NoClean; Function</title>
 121
 122     <para>
 123
 124     By default, &SCons; removes all built targets when invoked
 125     with the <literal>-c</literal> option to clean a source tree
 126     of built targets.
 127     Sometimes, however, this is not what you want.
 128     For example, you may want to remove only intermediate generated files
 129     (such as object files),
 130     but leave the final targets
 131     (the libraries)
 132     untouched.
 133
 134     In such cases, you can use the &NoClean; method to prevent &SCons;
 135     from removing a target during a clean:
 136
 137     </para>
 138
 139     <scons_example name="fileremoval_noclean-ex1">
 140       <file name="SConstruct" printme="1">
 141 env = Environment(RANLIBCOM='')
 142 lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
 143 env.NoClean(lib)
 144       </file>
 145       <file name="f1.c">
 146 int f1() { }
 147       </file>
 148       <file name="f2.c">
 149 int f2() { }
 150       </file>
 151       <file name="f3.c">
 152 int f3() { }
 153       </file>
 154     </scons_example>
 155
 156     <para>
 157
 158     Notice that the <filename>libfoo.a</filename>
 159     is not listed as a removed file:
 160
 161     </para>
 162
 163     <scons_output example="fileremoval_noclean-ex1" suffix="1">
 164         <scons_output_command>scons -Q</scons_output_command>
 165         <scons_output_command>scons -c</scons_output_command>
 166     </scons_output>
 167
 168   </section>
 169
 170   <section>
 171   <title>Removing additional files during clean: the &Clean; Function</title>
 172
 173     <para>
 174
 175     There may be additional files that you want removed
 176     when the <literal>-c</literal> option is used,
 177     but which &SCons; doesn't know about
 178     because they're not normal target files.
 179     For example, perhaps a command you invoke
 180     creates a log file as
 181     part of building the target file you want.
 182     You would like the log file cleaned,
 183     but you don't want to have to teach
 184     SCons that the command
 185     "builds" two files.
 186
 187     </para>
 188
 189     <para>
 190
 191     You can use the &Clean; function to arrange for additional files
 192     to be removed when the <literal>-c</literal> option is used.
 193     Notice, however, that the &Clean; function takes two arguments,
 194     and the <emphasis>second</emphasis> argument
 195     is the name of the additional file you want cleaned
 196     (<filename>foo.log</filename> in this example):
 197
 198     </para>
 199
 200     <scons_example name="fileremoval_clean-ex1">
 201       <file name="S" printme="1">
 202 t = Command('foo.out', 'foo.in', 'build -o $TARGET $SOURCE')
 203 Clean(t, 'foo.log')
 204       </file>
 205       <!-- this is a non-displayed script that fiddles PATH to allow dummy "build" command to work -->
 206       <file name="SConstruct">
 207 def_env = DefaultEnvironment()
 208 def_env.AppendENVPath('PATH', Dir('.'))
 209 SConscript('S')
 210       </file>
 211       <file name="foo.in">
 212 foo.in
 213       </file>
 214       <file name="foo.log">
 215 foo.log
 216       </file>
 217       <file name="build" chmod="0o755">
 218 cat $3 > $2
 219       </file>
 220     </scons_example>
 221
 222     <para>
 223
 224     The first argument is the target with which you want
 225     the cleaning of this additional file associated.
 226     In the above example,
 227     we've used the return value from the
 228     &Command; function,
 229     which represents the
 230     <filename>foo.out</filename>
 231     target.
 232     Now whenever the
 233     <filename>foo.out</filename> target is cleaned
 234     by the <literal>-c</literal> option,
 235     the <filename>foo.log</filename> file
 236     will be removed as well:
 237
 238     </para>
 239
 240     <scons_output example="fileremoval_clean-ex1" suffix="1">
 241         <scons_output_command>scons -Q</scons_output_command>
 242         <scons_output_command>scons -Q -c</scons_output_command>
 243     </scons_output>
 244
 245   </section>
 246
 247 </chapter>