doc/user/caching.xml

   1 <?xml version='1.0'?>
   2
   3 <!--
   4 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   5 SPDX-License-Identifier: MIT
   6 SPDX-FileType: DOCUMENTATION
   7
   8 This file is processed by the bin/SConsDoc.py module.
   9 -->
  10
  11 <!DOCTYPE sconsdoc [
  12     <!ENTITY % scons SYSTEM "../scons.mod">
  13     %scons;
  14
  15     <!ENTITY % builders-mod SYSTEM "../generated/builders.mod">
  16     %builders-mod;
  17     <!ENTITY % functions-mod SYSTEM "../generated/functions.mod">
  18     %functions-mod;
  19     <!ENTITY % tools-mod SYSTEM "../generated/tools.mod">
  20     %tools-mod;
  21     <!ENTITY % variables-mod SYSTEM "../generated/variables.mod">
  22     %variables-mod;
  23
  24 ]>
  25
  26 <chapter id="chap-caching"
  27          xmlns="http://www.scons.org/dbxsd/v1.0"
  28          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  29          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  30 <title>Caching Built Files</title>
  31
  32   <para>
  33
  34   On multi-developer software projects,
  35   you can sometimes speed up every developer's builds a lot by
  36   allowing them to share a cache of the derived files that they build.
  37   After all, it is relatively rare that any in-progress change affects
  38   more than a few derived files, most will be unchanged.
  39   Using a cache can also help an individual developer:
  40   for example if you wish to start work on a new feature in a clean tree,
  41   those build artifacts which could be reused can be
  42   retrieved from the cache to populate the tree and save
  43   a lot of initial build time.
  44   &SCons; makes this easy and reliable.
  45
  46   </para>
  47
  48   <section>
  49   <title>Specifying the Derived-File Cache Directory</title>
  50
  51     <para>
  52
  53     To enable caching of derived files,
  54     use the &f-link-CacheDir; function
  55     in any &SConscript; file:
  56
  57     </para>
  58
  59     <scons_example name="caching_ex1">
  60        <file name="SConstruct">
  61 env = Environment()
  62 env.Program('hello.c')
  63 CacheDir('cache')
  64        </file>
  65        <file name="hello.c">
  66 hello.c
  67        </file>
  68        <directory name="cache">
  69        </directory>
  70        <file name="not_used" printme="1">
  71 CacheDir('/usr/local/build_cache')
  72        </file>
  73     </scons_example>
  74
  75     <para>
  76
  77     The cache directory you specify must
  78     have read and write access for all developers
  79     who will be accessing the cached files
  80     (if <option>--cache-readonly</option> is used,
  81     only read access is required).
  82     It should also be in some central location
  83     that all builds will be able to access.
  84     In environments where developers are using separate systems
  85     (like individual workstations) for builds,
  86     this directory would typically be
  87     on a shared or NFS-mounted file system.
  88     While &SCons; will create the specified cache directory as needed,
  89     in this multiuser scenario it is usually best
  90     to create it ahead of time, so the access rights
  91     can be set up correctly.
  92
  93     </para>
  94
  95     <para>
  96
  97     Here's what happens:
  98     When a build has a &CacheDir; specified,
  99     every time a file is built,
 100     it is stored in that cache directory
 101     indexed by its &buildsig;.
 102     On subsequent builds,
 103     before an action is invoked to build a file,
 104     the &buildsig; is computed and &SCons; checks
 105     the derived-file cache directory
 106     to see if a file with the exact same &buildsig;
 107     already exists.
 108
 109       <footnote>
 110       <para>
 111       A few inside details: &SCons; tracks two main kinds of cryptographic
 112       hashes: a <emphasis>&contentsig;</emphasis>,
 113       which is a hash of the contents of a file participating in the
 114       build (dependencies as well as targets);
 115       and a <emphasis>&buildsig;</emphasis>, which is a hash of the
 116       elements needed to build a target, such as the command line,
 117       the contents of the sources, and possibly information about
 118       tools used in the build. The hash function produces a unique signature
 119       from its inputs, no other set of inputs can produce that same
 120       signature.  The &buildsig; from building
 121       a target is used as the filename of the target file in the
 122       derived-file cache - that way lookups are efficient, just compute
 123       a &buildsig; and see if a file exists with that as the name.
 124       </para>
 125
 126       <para>
 127       The use of the &buildsig; provides protection from conflicts:
 128       if two developers have different setups, so they would produce
 129       built objects that are not identical, then because the difference in
 130       tools will show up in the &buildsig;, which is used as the
 131       name of the cache entry, they will end up being
 132       stored as separate entries.
 133       </para>
 134       </footnote>
 135
 136     If so, the derived file will not be built locally,
 137     but will be copied into the local build directory
 138     from the derived-file cache directory,
 139     like this:
 140
 141     </para>
 142
 143     <scons_output example="caching_ex1" suffix="1">
 144       <scons_output_command>scons -Q</scons_output_command>
 145       <scons_output_command>scons -Q -c</scons_output_command>
 146       <scons_output_command>scons -Q</scons_output_command>
 147     </scons_output>
 148
 149     <para>
 150
 151     Note that the &CacheDir; feature requires that the &buildsig;
 152     be calculated,
 153     even if you configure &SCons; to use timestamps
 154     to decide if files are up to date
 155     (see the <xref linkend="chap-depends"></xref>
 156     chapter for information about the &f-link-Decider; function),
 157     since the &buildsig; is used to determine if a target file
 158     exists in the cache.
 159     Consequently, using &CacheDir; may reduce or negate any performance
 160     improvements from using timestamps for up-to-date decisions.
 161
 162     </para>
 163
 164   </section>
 165
 166   <section>
 167   <title>Keeping Build Output Consistent</title>
 168
 169     <para>
 170
 171     One potential drawback to using a derived-file cache
 172     is that the output printed by &SCons;
 173     can be inconsistent from invocation to invocation,
 174     because any given file may be rebuilt one time
 175     and retrieved from the derived-file cache the next time.
 176     This can make analyzing build output more difficult,
 177     especially for automated scripts that
 178     expect consistent output each time.
 179
 180     </para>
 181
 182     <para>
 183
 184     If, however, you use the <option>--cache-show</option> option,
 185     &SCons; will print the command line that it
 186     <emphasis>would</emphasis> have executed
 187     to build the file,
 188     even when it is retrieving the file from the derived-file cache.
 189     This keeps the build output consistent across builds:
 190
 191     </para>
 192
 193     <scons_output example="caching_ex1" suffix="2">
 194       <scons_output_command>scons -Q</scons_output_command>
 195       <scons_output_command>scons -Q -c</scons_output_command>
 196       <scons_output_command>scons -Q --cache-show</scons_output_command>
 197     </scons_output>
 198
 199     <para>
 200
 201     The trade-off, of course, is that you no longer
 202     know whether or not &SCons;
 203     has retrieved a derived file from cache
 204     or has rebuilt it locally.
 205
 206     </para>
 207
 208   </section>
 209
 210   <section>
 211   <title>Not Using the Derived-File Cache for Specific Files</title>
 212
 213     <para>
 214
 215     You may want to disable caching for certain
 216     specific files in your configuration.
 217     For example, if you only want to put
 218     executable files in a central cache,
 219     but not the intermediate object files,
 220     you can use the &f-link-NoCache;
 221     function to specify that the
 222     object files should not be cached:
 223
 224     </para>
 225
 226     <scons_example name="ex-NoCache">
 227        <file name="SConstruct" printme="1">
 228 env = Environment()
 229 obj = env.Object('hello.c')
 230 env.Program('hello.c')
 231 CacheDir('cache')
 232 NoCache('hello.o')
 233        </file>
 234        <file name="hello.c">
 235 hello.c
 236        </file>
 237        <directory name="cache">
 238        </directory>
 239     </scons_example>
 240
 241     <para>
 242
 243     Then, when you run &scons; after cleaning
 244     the built targets,
 245     it will recompile the object file locally
 246     (since it doesn't exist in the derived-file cache directory),
 247     but still realize that the derived-file cache directory
 248     contains an up-to-date executable program
 249     that can be retrieved instead of re-linking:
 250
 251     </para>
 252
 253     <!--
 254
 255     <scons_output example="caching_ex1" suffix="3">
 256       <scons_output_command>scons -Q</scons_output_command>
 257       <scons_output_command>scons -Q -c</scons_output_command>
 258       <scons_output_command>scons -Q</scons_output_command>
 259     </scons_output>
 260
 261     -->
 262
 263     <screen>
 264 % <userinput>scons -Q</userinput>
 265 cc -o hello.o -c hello.c
 266 cc -o hello hello.o
 267 % <userinput>scons -Q -c</userinput>
 268 Removed hello.o
 269 Removed hello
 270 % <userinput>scons -Q</userinput>
 271 cc -o hello.o -c hello.c
 272 Retrieved `hello' from cache
 273     </screen>
 274
 275   </section>
 276
 277   <section>
 278   <title>Disabling the Derived-File Cache</title>
 279
 280     <para>
 281
 282     Retrieving an already-built file
 283     from the derived-file cache
 284     is usually a significant time-savings
 285     over rebuilding the file,
 286     but how much of a savings
 287     (or even whether it saves time at all)
 288     can depend a great deal on your
 289     system or network configuration.
 290     For example, retrieving cached files
 291     from a busy server over a busy network
 292     might end up being slower than
 293     rebuilding the files locally.
 294
 295     </para>
 296
 297     <para>
 298
 299     In these cases, you can specify
 300     the <option>--cache-disable</option>
 301     command-line option to tell &SCons;
 302     to not retrieve already-built files from the
 303     derived-file cache directory:
 304
 305     </para>
 306
 307     <scons_output example="caching_ex1" suffix="4">
 308       <scons_output_command>scons -Q</scons_output_command>
 309       <scons_output_command>scons -Q -c</scons_output_command>
 310       <scons_output_command>scons -Q</scons_output_command>
 311       <scons_output_command>scons -Q -c</scons_output_command>
 312       <scons_output_command>scons -Q --cache-disable</scons_output_command>
 313     </scons_output>
 314
 315   </section>
 316
 317   <section>
 318   <title>Populating a Derived-File Cache With Already-Built Files</title>
 319
 320     <para>
 321
 322     Sometimes, you may have one or more derived files
 323     already built in your local build tree
 324     that you wish to make available to other people doing builds.
 325     For example, you may find it more effective to perform
 326     integration builds with the cache disabled
 327     (per the previous section)
 328     and only populate the derived-file cache directory
 329     with the built files after the integration build
 330     has completed successfully.
 331     This way, the cache will only get filled up
 332     with derived files that are part of a complete, successful build
 333     not with files that might be later overwritten
 334     while you debug integration problems.
 335
 336     </para>
 337
 338     <para>
 339
 340     In this case, you can use
 341     the <option>--cache-force</option> option
 342     to tell &SCons; to put all derived files in the cache,
 343     even if the files already exist in your local tree
 344     from having been built by a previous invocation:
 345
 346     </para>
 347
 348     <scons_output example="caching_ex1" suffix="5">
 349       <scons_output_command>scons -Q --cache-disable</scons_output_command>
 350       <scons_output_command>scons -Q -c</scons_output_command>
 351       <scons_output_command>scons -Q --cache-disable</scons_output_command>
 352       <scons_output_command>scons -Q --cache-force</scons_output_command>
 353       <scons_output_command>scons -Q</scons_output_command>
 354     </scons_output>
 355
 356     <para>
 357
 358     Notice how the above sample run
 359     demonstrates that the <option>--cache-disable</option>
 360     option avoids putting the built
 361     <filename>hello.o</filename>
 362     and
 363     <filename>hello</filename> files in the cache,
 364     but after using the <option>--cache-force</option> option,
 365     the files have been put in the cache
 366     for the next invocation to retrieve.
 367
 368     </para>
 369
 370   </section>
 371
 372   <section>
 373   <title>Minimizing Cache Contention:  the <option>--random</option> Option</title>
 374
 375     <para>
 376
 377     If you allow multiple builds to update the
 378     derived-file cache directory simultaneously,
 379     two builds that occur at the same time
 380     can sometimes start "racing"
 381     with one another to build the same files
 382     in the same order.
 383     If, for example,
 384     you are linking multiple files into an executable program:
 385
 386     </para>
 387
 388     <scons_example name="caching_ex-random">
 389        <file name="SConstruct" printme="1">
 390 Program('prog', ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
 391        </file>
 392        <file name="f1.c">f1.c</file>
 393        <file name="f2.c">f2.c</file>
 394        <file name="f3.c">f3.c</file>
 395        <file name="f4.c">f4.c</file>
 396        <file name="f5.c">f5.c</file>
 397        <file name="f6.c">f6.c</file>
 398     </scons_example>
 399
 400     <para>
 401
 402     &SCons; will normally build the input object files
 403     on which the program depends in their normal, sorted order:
 404
 405     </para>
 406
 407     <scons_output example="caching_ex-random" suffix="1">
 408       <scons_output_command>scons -Q</scons_output_command>
 409     </scons_output>
 410
 411     <para>
 412
 413     But if two such builds take place simultaneously,
 414     they may each look in the cache at nearly the same
 415     time and both decide that <filename>f1.o</filename>
 416     must be rebuilt and pushed into the derived-file cache directory,
 417     then both decide that <filename>f2.o</filename>
 418     must be rebuilt (and pushed into the derived-file cache directory),
 419     then both decide that <filename>f3.o</filename>
 420     must be rebuilt...
 421     This won't cause any actual build problems--both
 422     builds will succeed,
 423     generate correct output files,
 424     and populate the cache--but
 425     it does represent wasted effort.
 426
 427     </para>
 428
 429     <para>
 430
 431     To alleviate such contention for the cache,
 432     you can use the <option>--random</option> command-line option
 433     to tell &SCons; to build dependencies
 434     in a random order:
 435
 436     </para>
 437
 438     <!--
 439
 440     The following <screen> output was generated by this:
 441
 442     <scons_output example="caching_ex-random" suffix="2">
 443       <scons_output_command>scons -Q - -random</scons_output_command>
 444     </scons_output>
 445
 446 We captured it directly here to guarantee a "random" order,
 447 guarding against the potential for - -random to happen
 448 to return things in the original sorted order.
 449
 450 -->
 451
 452     <screen>
 453   % <userinput>scons -Q --random</userinput>
 454   cc -o f3.o -c f3.c
 455   cc -o f1.o -c f1.c
 456   cc -o f5.o -c f5.c
 457   cc -o f2.o -c f2.c
 458   cc -o f4.o -c f4.c
 459   cc -o prog f1.o f2.o f3.o f4.o f5.o
 460     </screen>
 461
 462     <para>
 463
 464     Multiple builds using the <option>--random</option> option
 465     will usually build their dependencies in different,
 466     random orders,
 467     which minimizes the chances for a lot of
 468     contention for same-named files
 469     in the derived-file cache directory.
 470     Multiple simultaneous builds might still race to try to build
 471     the same target file on occasion,
 472     but long sequences of inefficient contention
 473     should be rare.
 474
 475     </para>
 476
 477     <para>
 478
 479     Note, of course,
 480     the <option>--random</option> option
 481     will cause the output that &SCons; prints
 482     to be inconsistent from invocation to invocation,
 483     which may be an issue when
 484     trying to compare output from different build runs.
 485
 486     </para>
 487
 488     <para>
 489
 490     If you want to make sure dependencies will be built
 491     in a random order without having to specify
 492     the <option>--random</option> on very command line,
 493     you can use the &f-link-SetOption; function to
 494     set the <literal>random</literal> option
 495     within any &SConscript; file:
 496
 497     </para>
 498
 499     <scons_example name="caching_ex-random">
 500        <file name="SConstruct" printme="1">
 501 SetOption('random', 1)
 502 Program('prog', ['f1.c', 'f2.c', 'f3.c', 'f4.c', 'f5.c'])
 503        </file>
 504        <file name="f1.c">f1.c</file>
 505        <file name="f2.c">f2.c</file>
 506        <file name="f3.c">f3.c</file>
 507        <file name="f4.c">f4.c</file>
 508        <file name="f5.c">f5.c</file>
 509        <file name="f6.c">f6.c</file>
 510     </scons_example>
 511
 512   </section>
 513
 514   <section>
 515     <title>Using a Custom CacheDir Class</title>
 516
 517     <para>
 518
 519     You can customize the behavior of derived-file caching to
 520     add your own features, for example to support compressed and/or
 521     encrypted cache files, modify cache file permissions to better
 522     support shared caches, gather additional statistics and data, etc.
 523
 524     </para>
 525
 526     <para>
 527
 528     To define custom cache behavior, subclass the
 529     <classname>SCons.CacheDir.CacheDir</classname> class,
 530     specializing those methods you want to change.
 531     You can pass this custom class as the <parameter>custom_class</parameter>
 532     parameter when calling &f-link-CacheDir; for global reach,
 533     or when calling &f-link-env-CacheDir; for a specific environment.
 534     You can also set the &consvar;
 535     &cv-link-CACHEDIR_CLASS; to the custom class - this needs to happen
 536     before configuring the cache in that environment.
 537     &SCons; will internally invoke and use your custom class when performing
 538     cache operations.
 539     The below example shows a simple use case of overriding the
 540     <function>copy_from_cache</function>
 541     method to record the total number of bytes pulled from the cache.
 542
 543     </para>
 544
 545     <scons_example name="custom_caching">
 546       <file name="SConstruct" printme="1">
 547 import os
 548 import SCons.CacheDir
 549
 550 class CustomCacheDir(SCons.CacheDir.CacheDir):
 551     total_retrieved = 0
 552
 553     @classmethod
 554     def copy_from_cache(cls, env, src, dst):
 555         # record total bytes pulled from cache
 556         cls.total_retrieved += os.stat(src).st_size
 557         return super().copy_from_cache(env, src, dst)
 558
 559 env = Environment()
 560 env.CacheDir('scons-cache', custom_class=CustomCacheDir)
 561 # ...
 562       </file>
 563     </scons_example>
 564
 565   </section>
 566
 567   <!--
 568
 569   <section>
 570   <title>Troubleshooting Shared Caching:  the &cache-debug; Option</title>
 571
 572     <para>
 573
 574     XXX describe the - - cache-debug option
 575     XXX maybe point to the troubleshooting appendix?
 576
 577     </para>
 578
 579   </section>
 580
 581   -->
 582
 583   <!--
 584
 585   <section>
 586
 587     <para>
 588
 589     XXX describe CacheDir management:  monitoring, deleting, etc.
 590
 591     </para>
 592
 593   </section>
 594
 595   -->
 596
 597 </chapter>