Doc/Manual/CCache.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <title>ccache-swig(1) manpage</title>
   5 <link rel="stylesheet" type="text/css" href="style.css">
   6 </head>
   7
   8 <body bgcolor="#ffffff">
   9 <H1><a name="CCache"></a>16 Using SWIG with ccache - ccache-swig(1) manpage</H1>
  10 <!-- INDEX -->
  11 <div class="sectiontoc">
  12 <ul>
  13 <li><a href="#CCache_nn2">NAME</a>
  14 <li><a href="#CCache_nn3">SYNOPSIS</a>
  15 <li><a href="#CCache_nn4">DESCRIPTION</a>
  16 <li><a href="#CCache_nn5">OPTIONS SUMMARY</a>
  17 <li><a href="#CCache_nn6">OPTIONS</a>
  18 <li><a href="#CCache_nn7">INSTALLATION</a>
  19 <li><a href="#CCache_nn8">EXTRA OPTIONS</a>
  20 <li><a href="#CCache_nn9">ENVIRONMENT VARIABLES</a>
  21 <li><a href="#CCache_nn10">CACHE SIZE MANAGEMENT</a>
  22 <li><a href="#CCache_nn11">CACHE COMPRESSION</a>
  23 <li><a href="#CCache_nn12">HOW IT WORKS</a>
  24 <li><a href="#CCache_nn13">USING CCACHE WITH DISTCC</a>
  25 <li><a href="#CCache_nn14">SHARING A CACHE</a>
  26 <li><a href="#CCache_nn15">HISTORY</a>
  27 <li><a href="#CCache_nn16">DIFFERENCES FROM COMPILERCACHE</a>
  28 <li><a href="#CCache_nn17">CREDITS</a>
  29 <li><a href="#CCache_nn18">AUTHOR</a>
  30 </ul>
  31 </div>
  32 <!-- INDEX -->
  33
  34
  35
  36 <p>
  37 <H2><a name="CCache_nn2"></a>16.1 NAME</H2>
  38
  39
  40 <p>
  41
  42 ccache-swig - a fast compiler cache
  43
  44 <p>
  45 <H2><a name="CCache_nn3"></a>16.2 SYNOPSIS</H2>
  46
  47
  48 <p>
  49 ccache-swig [OPTION]
  50 <p>
  51 ccache-swig &lt;compiler&gt; [COMPILER OPTIONS]
  52 <p>
  53 &lt;compiler&gt; [COMPILER OPTIONS]
  54 <p>
  55 <H2><a name="CCache_nn4"></a>16.3 DESCRIPTION</H2>
  56
  57
  58 <p>
  59 ccache-swig is a compiler cache. It speeds up re-compilation of C/C++/SWIG code
  60 by caching previous compiles and detecting when the same compile is
  61 being done again. ccache-swig is ccache plus support for SWIG. ccache
  62 and ccache-swig are used interchangeably in this document.
  63 <p>
  64 <H2><a name="CCache_nn5"></a>16.4 OPTIONS SUMMARY</H2>
  65
  66
  67 <p>
  68 Here is a summary of the options to ccache-swig.
  69 <p>
  70 <pre>
  71
  72 -s                      show statistics summary
  73 -z                      zero statistics
  74 -c                      run a cache cleanup
  75 -C                      clear the cache completely
  76 -F &lt;n&gt;                  set maximum files in cache
  77 -M &lt;n&gt;                  set maximum size of cache (use G, M or K)
  78 -h                      this help page
  79 -V                      print version number
  80
  81 </pre>
  82
  83 <p>
  84 <H2><a name="CCache_nn6"></a>16.5 OPTIONS</H2>
  85
  86
  87 <p>
  88 These options only apply when you invoke ccache as "ccache-swig". When
  89 invoked as a compiler none of these options apply. In that case your
  90 normal compiler options apply and you should refer to your compilers
  91 documentation.
  92 <p>
  93 <dl>
  94 <p><dt><strong><strong>-h</strong></strong><dd> Print a options summary page
  95 <p>
  96 <p><dt><strong><strong>-s</strong></strong><dd> Print the current statistics summary for the cache. The
  97 statistics are stored spread across the subdirectories of the
  98 cache. Using "ccache-swig -s" adds up the statistics across all
  99 subdirectories and prints the totals.
 100 <p>
 101 <p><dt><strong><strong>-z</strong></strong><dd> Zero the cache statistics.
 102 <p>
 103 <p><dt><strong><strong>-V</strong></strong><dd> Print the ccache version number
 104 <p>
 105 <p><dt><strong><strong>-c</strong></strong><dd> Clean the cache and re-calculate the cache file count and
 106 size totals. Normally the -c option should not be necessary as ccache
 107 keeps the cache below the specified limits at runtime and keeps
 108 statistics up to date on each compile. This option is mostly useful
 109 if you manually modify the cache contents or believe that the cache
 110 size statistics may be inaccurate.
 111 <p>
 112 <p><dt><strong><strong>-C</strong></strong><dd> Clear the entire cache, removing all cached files.
 113 <p>
 114 <p><dt><strong><strong>-F &lt;maxfiles&gt;</strong></strong><dd> This sets the maximum number of files allowed in
 115 the cache. The value is stored inside the cache directory and applies
 116 to all future compiles. Due to the way the value is stored the actual
 117 value used is always rounded down to the nearest multiple of 16.
 118 <p>
 119 <p><dt><strong><strong>-M &lt;maxsize&gt;</strong></strong><dd> This sets the maximum cache size. You can specify
 120 a value in gigabytes, megabytes or kilobytes by appending a G, M or K
 121 to the value. The default is gigabytes. The actual value stored is
 122 rounded down to the nearest multiple of 16 kilobytes.
 123 <p>
 124 </dl>
 125 <p>
 126 <H2><a name="CCache_nn7"></a>16.6 INSTALLATION</H2>
 127
 128
 129 <p>
 130 There are two ways to use ccache. You can either prefix your compile
 131 commands with "ccache-swig" or you can create a symbolic link between
 132 ccache-swig and the names of your compilers. The first method is most
 133 convenient if you just want to try out ccache or wish to use it for
 134 some specific projects. The second method is most useful for when you
 135 wish to use ccache for all your compiles.
 136 <p>
 137 To install for usage by the first method just copy ccache-swig to somewhere
 138 in your path.
 139 <p>
 140 To install for the second method do something like this:
 141 <pre>
 142
 143   cp ccache-swig /usr/local/bin/
 144   ln -s /usr/local/bin/ccache-swig /usr/local/bin/gcc
 145   ln -s /usr/local/bin/ccache-swig /usr/local/bin/g++
 146   ln -s /usr/local/bin/ccache-swig /usr/local/bin/cc
 147   ln -s /usr/local/bin/ccache-swig /usr/local/bin/swig
 148
 149 </pre>
 150
 151 This will work as long as /usr/local/bin comes before the path to gcc
 152 (which is usually in /usr/bin). After installing you may wish to run
 153 "which gcc" to make sure that the correct link is being used.
 154 <p>
 155 Note! Do not use a hard link, use a symbolic link. A hardlink will
 156 cause "interesting" problems.
 157 <p>
 158 <H2><a name="CCache_nn8"></a>16.7 EXTRA OPTIONS</H2>
 159
 160
 161 <p>
 162 When run as a compiler front end ccache usually just takes the same
 163 command line options as the compiler you are using. The only exception
 164 to this is the option '--ccache-skip'. That option can be used to tell
 165 ccache that the next option is definitely not a input filename, and
 166 should be passed along to the compiler as-is.
 167 <p>
 168 The reason this can be important is that ccache does need to parse the
 169 command line and determine what is an input filename and what is a
 170 compiler option, as it needs the input filename to determine the name
 171 of the resulting object file (among other things). The heuristic
 172 ccache uses in this parse is that any string on the command line that
 173 exists as a file is treated as an input file name (usually a C
 174 file). By using --ccache-skip you can force an option to not be
 175 treated as an input file name and instead be passed along to the
 176 compiler as a command line option.
 177 <p>
 178 <H2><a name="CCache_nn9"></a>16.8 ENVIRONMENT VARIABLES</H2>
 179
 180
 181 <p>
 182 ccache uses a number of environment variables to control operation. In
 183 most cases you won't need any of these as the defaults will be fine.
 184 <p>
 185 <dl>
 186 <p>
 187 <p><dt><strong><strong>CCACHE_DIR</strong></strong><dd> the CCACHE_DIR environment variable specifies
 188 where ccache will keep its cached compiler output. The default is
 189 "$HOME/.ccache".
 190 <p>
 191 <p><dt><strong><strong>CCACHE_TEMPDIR</strong></strong><dd> the CCACHE_TEMPDIR environment variable specifies
 192 where ccache will put temporary files. The default is the same as
 193 CCACHE_DIR. Note that the CCACHE_TEMPDIR path must be on the same
 194 filesystem as the CCACHE_DIR path, so that renames of files between
 195 the two directories can work.
 196 <p>
 197 <p><dt><strong><strong>CCACHE_LOGFILE</strong></strong><dd> If you set the CCACHE_LOGFILE environment
 198 variable then ccache will write some log information on cache hits
 199 and misses in that file. This is useful for tracking down problems.
 200 <p>
 201 <p><dt><strong><strong>CCACHE_VERBOSE</strong></strong><dd> If you set the CCACHE_VERBOSE environment
 202 variable then ccache will display on stdout all the compiler invocations
 203 that it makes. This can useful for debugging unexpected problems.
 204 <p>
 205 <p><dt><strong><strong>CCACHE_PATH</strong></strong><dd> You can optionally set CCACHE_PATH to a colon
 206 separated path where ccache will look for the real compilers. If you
 207 don't do this then ccache will look for the first executable matching
 208 the compiler name in the normal PATH that isn't a symbolic link to
 209 ccache itself.
 210 <p>
 211 <p><dt><strong><strong>CCACHE_CC</strong></strong><dd> You can optionally set CCACHE_CC to force the name
 212 of the compiler to use. If you don't do this then ccache works it out
 213 from the command line.
 214 <p>
 215 <p><dt><strong><strong>CCACHE_PREFIX</strong></strong><dd> This option adds a prefix to the command line
 216 that ccache runs when invoking the compiler. Also see the section
 217 below on using ccache with distcc.
 218 <p>
 219 <p><dt><strong><strong>CCACHE_DISABLE</strong></strong><dd> If you set the environment variable
 220 CCACHE_DISABLE then ccache will just call the real compiler,
 221 bypassing the cache completely.
 222 <p>
 223 <p><dt><strong><strong>CCACHE_READONLY</strong></strong><dd> the CCACHE_READONLY environment variable
 224 tells ccache to attempt to use existing cached object files, but not
 225 to try to add anything new to the cache. If you are using this because
 226 your CCACHE_DIR is read-only, then you may find that you also need to
 227 set CCACHE_TEMPDIR as otherwise ccache will fail to create the
 228 temporary files.
 229 <p>
 230 <p><dt><strong><strong>CCACHE_CPP2</strong></strong><dd> If you set the environment variable CCACHE_CPP2
 231 then ccache will not use the optimisation of avoiding the 2nd call to
 232 the pre-processor by compiling the pre-processed output that was used
 233 for finding the hash in the case of a cache miss. This is primarily a
 234 debugging option, although it is possible that some unusual compilers
 235 will have problems with the intermediate filename extensions used in
 236 this optimisation, in which case this option could allow ccache to be
 237 used.
 238 <p>
 239 <p><dt><strong><strong>CCACHE_NOCOMPRESS</strong></strong><dd> If you set the environment variable
 240 CCACHE_NOCOMPRESS then there is no compression used on files that go
 241 into the cache. However, this setting has no effect on how files are
 242 retrieved from the cache, compressed results will still be usable.
 243 <p>
 244 <p><dt><strong><strong>CCACHE_NOSTATS</strong></strong><dd> If you set the environment variable
 245 CCACHE_NOSTATS then ccache will not update the statistics files on
 246 each compile.
 247 <p>
 248 <p><dt><strong><strong>CCACHE_NLEVELS</strong></strong><dd> The environment variable CCACHE_NLEVELS allows
 249 you to choose the number of levels of hash in the cache directory. The
 250 default is 2. The minimum is 1 and the maximum is 8.
 251 <p>
 252 <p><dt><strong><strong>CCACHE_HARDLINK</strong></strong><dd> If you set the environment variable
 253 CCACHE_HARDLINK then ccache will attempt to use hard links from the
 254 cache directory when creating the compiler output rather than using a
 255 file copy. Using hard links is faster, but can confuse programs like
 256 'make' that rely on modification times. Hard links are never made for
 257 compressed cache files.
 258 <p>
 259 <p><dt><strong><strong>CCACHE_RECACHE</strong></strong><dd> This forces ccache to not use any cached
 260 results, even if it finds them. New results are still cached, but
 261 existing cache entries are ignored.
 262 <p>
 263 <p><dt><strong><strong>CCACHE_UMASK</strong></strong><dd> This sets the umask for ccache and all child
 264 processes (such as the compiler). This is mostly useful when you wish
 265 to share your cache with other users. Note that this also affects the
 266 file permissions set on the object files created from your
 267 compilations.
 268 <p>
 269 <p><dt><strong><strong>CCACHE_HASHDIR</strong></strong><dd> This tells ccache to hash the current working
 270 directory when calculating the hash that is used to distinguish two
 271 compiles. This prevents a problem with the storage of the current
 272 working directory in the debug info of a object file, which can lead
 273 ccache to give a cached object file that has the working directory in
 274 the debug info set incorrectly. This option is off by default as the
 275 incorrect setting of this debug info rarely causes problems. If you
 276 strike problems with gdb not using the correct directory then enable
 277 this option.
 278 <p>
 279 <p><dt><strong><strong>CCACHE_UNIFY</strong></strong><dd> If you set the environment variable CCACHE_UNIFY
 280 then ccache will use the C/C++ unifier when hashing the pre-processor
 281 output if -g is not used in the compile. The unifier is slower than a
 282 normal hash, so setting this environment variable loses a little bit
 283 of speed, but it means that ccache can take advantage of not
 284 recompiling when the changes to the source code consist of
 285 reformatting only. Note that using CCACHE_UNIFY changes the hash, so
 286 cached compiles with CCACHE_UNIFY set cannot be used when
 287 CCACHE_UNIFY is not set and vice versa. The reason the unifier is off
 288 by default is that it can give incorrect line number information in
 289 compiler warning messages.
 290 <p>
 291 <p><dt><strong><strong>CCACHE_EXTENSION</strong></strong><dd> Normally ccache tries to automatically
 292 determine the extension to use for intermediate C pre-processor files
 293 based on the type of file being compiled. Unfortunately this sometimes
 294 doesn't work, for example when using the aCC compiler on HP-UX. On
 295 systems like this you can use the CCACHE_EXTENSION option to override
 296 the default. On HP-UX set this environment variable to "i" if you use
 297 the aCC compiler.
 298 <p>
 299 <p><dt><strong><strong>CCACHE_STRIPC</strong></strong><dd> If you set the environment variable
 300 CCACHE_STRIPC then ccache will strip the -c option when invoking
 301 the preprocessor. This option is primarily for the Sun Workshop
 302 C++ compiler as without this option an unwarranted warning is displayed:
 303 CC: Warning: "-E" redefines product from "object" to "source (stdout)"
 304 when -E and -c is used together.
 305 <p>
 306 <p><dt><strong><strong>CCACHE_SWIG</strong></strong><dd> When using SWIG as the compiler and it does not
 307 have 'swig' in the executable name, then the CCACHE_SWIG environment
 308 variable needs to be set in order for ccache to work correctly with
 309 SWIG. The use of CCACHE_CPP2 is also recommended for SWIG due to some
 310 preprocessor quirks, however, use of CCACHE_CPP2 can often be skipped
 311 -- check your generated code with and without this option set. Known
 312 problems are using preprocessor directives within %inline blocks and
 313 the use of '#pragma SWIG'.
 314 <p>
 315 </dl>
 316 <p>
 317 <H2><a name="CCache_nn10"></a>16.9 CACHE SIZE MANAGEMENT</H2>
 318
 319
 320 <p>
 321 By default ccache has a one gigabyte limit on the cache size and no
 322 maximum number of files. You can set a different limit using the
 323 "ccache -M" and "ccache -F" options, which set the size and number of
 324 files limits.
 325 <p>
 326 When these limits are reached ccache will reduce the cache to 20%
 327 below the numbers you specified in order to avoid doing the cache
 328 clean operation too often.
 329 <p>
 330 <H2><a name="CCache_nn11"></a>16.10 CACHE COMPRESSION</H2>
 331
 332
 333 <p>
 334 By default on most platforms ccache will compress all files it puts
 335 into the cache
 336 using the zlib compression. While this involves a negligible
 337 performance slowdown, it significantly increases the number of files
 338 that fit in the cache. You can turn off compression setting the
 339 CCACHE_NOCOMPRESS environment variable.
 340 <p>
 341 <H2><a name="CCache_nn12"></a>16.11 HOW IT WORKS</H2>
 342
 343
 344 <p>
 345 The basic idea is to detect when you are compiling exactly the same
 346 code a 2nd time and use the previously compiled output. You detect
 347 that it is the same code by forming a hash of:
 348 <p>
 349 <ul>
 350   <li> the pre-processor output from running the compiler with -E
 351   <li> the command line options
 352   <li> the real compilers size and modification time
 353   <li> any stderr output generated by the compiler
 354 </ul>
 355 <p>
 356 These are hashed using md4 (a strong hash) and a cache file is formed
 357 based on that hash result. When the same compilation is done a second
 358 time ccache is able to supply the correct compiler output (including
 359 all warnings etc) from the cache.
 360 <p>
 361 ccache has been carefully written to always produce exactly the same
 362 compiler output that you would get without the cache. If you ever
 363 discover a case where ccache changes the output of your compiler then
 364 please let me know.
 365 <p>
 366 <H2><a name="CCache_nn13"></a>16.12 USING CCACHE WITH DISTCC</H2>
 367
 368
 369 <p>
 370 distcc is a very useful program for distributing compilation across a
 371 range of compiler servers. It is often useful to combine distcc with
 372 ccache, so that compiles that are done are sped up by distcc, but that
 373 ccache avoids the compile completely where possible.
 374 <p>
 375 To use distcc with ccache I recommend using the CCACHE_PREFIX
 376 option. You just need to set the environment variable CCACHE_PREFIX to
 377 'distcc' and ccache will prefix the command line used with the
 378 compiler with the command 'distcc'.
 379 <p>
 380 <H2><a name="CCache_nn14"></a>16.13 SHARING A CACHE</H2>
 381
 382
 383 <p>
 384 A group of developers can increase the cache hit rate by sharing a
 385 cache directory.  The hard links however cause unwanted side effects,
 386 as all links to a cached file share the file's modification timestamp.
 387 This results in false dependencies to be triggered by timestamp-based
 388 build systems whenever another user links to an existing
 389 file. Typically, users will see that their libraries and binaries are
 390 relinked without reason.  To share a cache without side effects, the
 391 following conditions need to be met:
 392 <p>
 393 <ul>
 394   <li> Use the same <strong>CCACHE_DIR</strong> environment variable setting
 395   <li> Unset the <strong>CCACHE_HARDLINK</strong> environment variable
 396   <li> Make sure everyone sets the CCACHE_UMASK environment variable
 397   to 002, this ensures that cached files are accessible to everyone in
 398   the group.
 399   <li> Make sure that all users have write permission in the entire
 400   cache directory (and that you trust all users of the shared cache).
 401   <li> Make sure that the setgid bit is set on all directories in the
 402   cache. This tells the filesystem to inherit group ownership for new
 403   directories. The command "chmod g+s `find $CCACHE_DIR -type d`" might
 404   be useful for this.
 405   <li> Set <strong>CCACHE_NOCOMPRESS</strong> for all users, if there are users with
 406   versions of ccache that do not support compression.
 407 </ul>
 408 <p>
 409 <H2><a name="CCache_nn15"></a>16.14 HISTORY</H2>
 410
 411
 412 <p>
 413 ccache was inspired by the compilercache shell script script written
 414 by Erik Thiele and I would like to thank him for an excellent piece of
 415 work. See
 416 <a href="http://www.erikyyy.de/compilercache/">http://www.erikyyy.de/compilercache/</a>
 417 for the Erik's scripts.
 418 ccache-swig is a port of the original ccache with support added for use
 419 with SWIG.
 420 <p>
 421 I wrote ccache because I wanted to get a bit more speed out of a
 422 compiler cache and I wanted to remove some of the limitations of the
 423 shell-script version.
 424 <p>
 425 <H2><a name="CCache_nn16"></a>16.15 DIFFERENCES FROM COMPILERCACHE</H2>
 426
 427
 428 <p>
 429 The biggest differences between Erik's compilercache script and ccache
 430 are:
 431 <ul>
 432 <li> ccache is written in C, which makes it a bit faster (calling out to
 433   external programs is mostly what slowed down the scripts).
 434 <li> ccache can automatically find the real compiler
 435 <li> ccache keeps statistics on hits/misses
 436 <li> ccache can do automatic cache management
 437 <li> ccache can cache compiler output that includes warnings. In many
 438   cases this gives ccache a much higher cache hit rate.
 439 <li> ccache can handle a much wider ranger of compiler options
 440 <li> ccache avoids a double call to cpp on a cache miss
 441 </ul>
 442 <p>
 443 <H2><a name="CCache_nn17"></a>16.16 CREDITS</H2>
 444
 445
 446 <p>
 447 Thanks to the following people for their contributions to ccache
 448 <ul>
 449  <li> Erik Thiele for the original compilercache script
 450  <li> Luciano Rocha for the idea of compiling the pre-processor output
 451  to avoid a 2nd cpp pass
 452  <li> Paul Russell for many suggestions and the debian packaging
 453 </ul>
 454 <p>
 455 <H2><a name="CCache_nn18"></a>16.17 AUTHOR</H2>
 456
 457
 458 <p>
 459 ccache was written by Andrew Tridgell
 460 <a href="http://samba.org/~tridge/">http://samba.org/~tridge/</a>.
 461 ccache was adapted to create ccache-swig for use with SWIG by William Fulton.
 462 <p>
 463 If you wish to report a problem or make a suggestion then please email
 464 the SWIG developers on the swig-devel mailing list, see
 465 <a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a>
 466 <p>
 467 ccache is released under the GNU General Public License version 2 or
 468 later. Please see the file COPYING for license details.
 469 <p>
 470
 471
 472 </body>
 473 </html>
 474
 475