doc/user/file-removal.xml

   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     <programlisting>
  60         env = Environment(RANLIBCOM='')
  61         lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
  62         env.Precious(lib)
  63     </programlisting>
  64
  65     <para>
  66
  67     Although the output doesn't look any different,
  68     &SCons; does not, in fact,
  69     delete the target library before rebuilding it:
  70
  71     </para>
  72
  73     <screen>
  74         % <userinput>scons -Q</userinput>
  75         cc -o f1.o -c f1.c
  76         cc -o f2.o -c f2.c
  77         cc -o f3.o -c f3.c
  78         ar rc libfoo.a f1.o f2.o f3.o
  79     </screen>
  80
  81     <para>
  82
  83     &SCons; will, however, still delete files marked as &Precious;
  84     when the <literal>-c</literal> option is used.
  85
  86     </para>
  87
  88   </section>
  89
  90   <section>
  91   <title>Preventing target removal during clean: the &NoClean; Function</title>
  92
  93     <para>
  94
  95     By default, &SCons; removes all built targets when invoked
  96     with the <literal>-c</literal> option to clean a source tree
  97     of built targets.
  98     Sometimes, however, this is not what you want.
  99     For example, you may want to remove only intermediate generated files
 100     (such as object files),
 101     but leave the final targets
 102     (the libraries)
 103     untouched.
 104
 105     In such cases, you can use the &NoClean; method to prevent &SCons;
 106     from removing a target during a clean:
 107
 108     </para>
 109
 110     <programlisting>
 111         env = Environment(RANLIBCOM='')
 112         lib = env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
 113         env.NoClean(lib)
 114     </programlisting>
 115
 116     <para>
 117
 118     Notice that the <filename>libfoo.a</filename>
 119     is not listed as a removed file:
 120
 121     </para>
 122
 123     <screen>
 124         % <userinput>scons -Q</userinput>
 125         cc -o f1.o -c f1.c
 126         cc -o f2.o -c f2.c
 127         cc -o f3.o -c f3.c
 128         ar rc libfoo.a f1.o f2.o f3.o
 129         % <userinput>scons -c</userinput>
 130         scons: Reading SConscript files ...
 131         scons: done reading SConscript files.
 132         scons: Cleaning targets ...
 133         Removed f1.o
 134         Removed f2.o
 135         Removed f3.o
 136         scons: done cleaning targets.
 137     </screen>
 138
 139   </section>
 140
 141   <section>
 142   <title>Removing additional files during clean: the &Clean; Function</title>
 143
 144     <para>
 145
 146     There may be additional files that you want removed
 147     when the <literal>-c</literal> option is used,
 148     but which &SCons; doesn't know about
 149     because they're not normal target files.
 150     For example, perhaps a command you invoke
 151     creates a log file as
 152     part of building the target file you want.
 153     You would like the log file cleaned,
 154     but you don't want to have to teach
 155     SCons that the command
 156     "builds" two files.
 157
 158     </para>
 159
 160     <para>
 161
 162     You can use the &Clean; function to arrange for additional files
 163     to be removed when the <literal>-c</literal> option is used.
 164     Notice, however, that the &Clean; function takes two arguments,
 165     and the <emphasis>second</emphasis> argument
 166     is the name of the additional file you want cleaned
 167     (<filename>foo.log</filename> in this example):
 168
 169     </para>
 170
 171     <programlisting>
 172         t = Command('foo.out', 'foo.in', 'build -o $TARGET $SOURCE')
 173         Clean(t, 'foo.log')
 174     </programlisting>
 175
 176     <para>
 177
 178     The first argument is the target with which you want
 179     the cleaning of this additional file associated.
 180     In the above example,
 181     we've used the return value from the
 182     &Command; function,
 183     which represents the
 184     <filename>foo.out</filename>
 185     target.
 186     Now whenever the
 187     <filename>foo.out</filename> target is cleaned
 188     by the <literal>-c</literal> option,
 189     the <filename>foo.log</filename> file
 190     will be removed as well:
 191
 192     </para>
 193
 194     <screen>
 195         % <userinput>scons -Q</userinput>
 196         build -o foo.out foo.in
 197         % <userinput>scons -Q -c</userinput>
 198         Removed foo.out
 199         Removed foo.log
 200     </screen>
 201
 202   </section>