doc/user/file-removal.in

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