| .TH "ccache\-swig" "1" "" "" "" |
| |
| .PP |
| .SH "NAME" |
| ccache\-swig \- a fast compiler cache |
| .PP |
| .SH "SYNOPSIS" |
| |
| .PP |
| ccache\-swig [OPTION] |
| .PP |
| ccache\-swig <compiler> [COMPILER OPTIONS] |
| .PP |
| <compiler> [COMPILER OPTIONS] |
| .PP |
| .SH "DESCRIPTION" |
| |
| .PP |
| ccache\-swig is a compiler cache\&. It speeds up re\-compilation of C/C++/SWIG code |
| by caching previous compiles and detecting when the same compile is |
| being done again\&. ccache\-swig is ccache plus support for SWIG\&. ccache |
| and ccache\-swig are used interchangeably in this document\&. |
| .PP |
| .SH "OPTIONS SUMMARY" |
| |
| .PP |
| Here is a summary of the options to ccache\-swig\&. |
| .PP |
| .nf |
| |
| \-s show statistics summary |
| \-z zero statistics |
| \-c run a cache cleanup |
| \-C clear the cache completely |
| \-F <n> set maximum files in cache |
| \-M <n> set maximum size of cache (use G, M or K) |
| \-h this help page |
| \-V print version number |
| |
| .fi |
| |
| .PP |
| .SH "OPTIONS" |
| |
| .PP |
| These options only apply when you invoke ccache as \(dq\&ccache\-swig\(dq\&\&. When |
| invoked as a compiler none of these options apply\&. In that case your |
| normal compiler options apply and you should refer to your compilers |
| documentation\&. |
| .PP |
| .IP "\fB\-h\fP" |
| Print a options summary page |
| .IP |
| .IP "\fB\-s\fP" |
| Print the current statistics summary for the cache\&. The |
| statistics are stored spread across the subdirectories of the |
| cache\&. Using \(dq\&ccache\-swig \-s\(dq\& adds up the statistics across all |
| subdirectories and prints the totals\&. |
| .IP |
| .IP "\fB\-z\fP" |
| Zero the cache statistics\&. |
| .IP |
| .IP "\fB\-V\fP" |
| Print the ccache version number |
| .IP |
| .IP "\fB\-c\fP" |
| Clean the cache and re\-calculate the cache file count and |
| size totals\&. Normally the \-c option should not be necessary as ccache |
| keeps the cache below the specified limits at runtime and keeps |
| statistics up to date on each compile\&. This option is mostly useful |
| if you manually modify the cache contents or believe that the cache |
| size statistics may be inaccurate\&. |
| .IP |
| .IP "\fB\-C\fP" |
| Clear the entire cache, removing all cached files\&. |
| .IP |
| .IP "\fB\-F <maxfiles>\fP" |
| This sets the maximum number of files allowed in |
| the cache\&. The value is stored inside the cache directory and applies |
| to all future compiles\&. Due to the way the value is stored the actual |
| value used is always rounded down to the nearest multiple of 16\&. |
| .IP |
| .IP "\fB\-M <maxsize>\fP" |
| This sets the maximum cache size\&. You can specify |
| a value in gigabytes, megabytes or kilobytes by appending a G, M or K |
| to the value\&. The default is gigabytes\&. The actual value stored is |
| rounded down to the nearest multiple of 16 kilobytes\&. |
| .IP |
| .SH "INSTALLATION" |
| |
| .PP |
| There are two ways to use ccache\&. You can either prefix your compile |
| commands with \(dq\&ccache\-swig\(dq\& or you can create a symbolic link between |
| ccache\-swig and the names of your compilers\&. The first method is most |
| convenient if you just want to try out ccache or wish to use it for |
| some specific projects\&. The second method is most useful for when you |
| wish to use ccache for all your compiles\&. |
| .PP |
| To install for usage by the first method just copy ccache\-swig to somewhere |
| in your path\&. |
| .PP |
| To install for the second method do something like this: |
| .nf |
| |
| cp ccache\-swig /usr/local/bin/ |
| ln \-s /usr/local/bin/ccache\-swig /usr/local/bin/gcc |
| ln \-s /usr/local/bin/ccache\-swig /usr/local/bin/g++ |
| ln \-s /usr/local/bin/ccache\-swig /usr/local/bin/cc |
| ln \-s /usr/local/bin/ccache\-swig /usr/local/bin/swig |
| |
| .fi |
| This will work as long as /usr/local/bin comes before the path to gcc |
| (which is usually in /usr/bin)\&. After installing you may wish to run |
| \(dq\&which gcc\(dq\& to make sure that the correct link is being used\&. |
| .PP |
| Note! Do not use a hard link, use a symbolic link\&. A hardlink will |
| cause \(dq\&interesting\(dq\& problems\&. |
| .PP |
| .SH "EXTRA OPTIONS" |
| |
| .PP |
| When run as a compiler front end ccache usually just takes the same |
| command line options as the compiler you are using\&. The only exception |
| to this is the option \(cq\&\-\-ccache\-skip\(cq\&\&. That option can be used to tell |
| ccache that the next option is definitely not a input filename, and |
| should be passed along to the compiler as\-is\&. |
| .PP |
| The reason this can be important is that ccache does need to parse the |
| command line and determine what is an input filename and what is a |
| compiler option, as it needs the input filename to determine the name |
| of the resulting object file (among other things)\&. The heuristic |
| ccache uses in this parse is that any string on the command line that |
| exists as a file is treated as an input file name (usually a C |
| file)\&. By using \-\-ccache\-skip you can force an option to not be |
| treated as an input file name and instead be passed along to the |
| compiler as a command line option\&. |
| .PP |
| .SH "ENVIRONMENT VARIABLES" |
| |
| .PP |
| ccache uses a number of environment variables to control operation\&. In |
| most cases you won\(cq\&t need any of these as the defaults will be fine\&. |
| .PP |
| .IP "\fBCCACHE_DIR\fP" |
| the CCACHE_DIR environment variable specifies |
| where ccache will keep its cached compiler output\&. The default is |
| \(dq\&$HOME/\&.ccache\(dq\&\&. |
| .IP |
| .IP "\fBCCACHE_TEMPDIR\fP" |
| the CCACHE_TEMPDIR environment variable specifies |
| where ccache will put temporary files\&. The default is the same as |
| CCACHE_DIR\&. Note that the CCACHE_TEMPDIR path must be on the same |
| filesystem as the CCACHE_DIR path, so that renames of files between |
| the two directories can work\&. |
| .IP |
| .IP "\fBCCACHE_LOGFILE\fP" |
| If you set the CCACHE_LOGFILE environment |
| variable then ccache will write some log information on cache hits |
| and misses in that file\&. This is useful for tracking down problems\&. |
| .IP |
| .IP "\fBCCACHE_VERBOSE\fP" |
| If you set the CCACHE_VERBOSE environment |
| variable then ccache will display on stdout all the compiler invocations |
| that it makes\&. This can useful for debugging unexpected problems\&. |
| .IP |
| .IP "\fBCCACHE_PATH\fP" |
| You can optionally set CCACHE_PATH to a colon |
| separated path where ccache will look for the real compilers\&. If you |
| don\(cq\&t do this then ccache will look for the first executable matching |
| the compiler name in the normal PATH that isn\(cq\&t a symbolic link to |
| ccache itself\&. |
| .IP |
| .IP "\fBCCACHE_CC\fP" |
| You can optionally set CCACHE_CC to force the name |
| of the compiler to use\&. If you don\(cq\&t do this then ccache works it out |
| from the command line\&. |
| .IP |
| .IP "\fBCCACHE_PREFIX\fP" |
| This option adds a prefix to the command line |
| that ccache runs when invoking the compiler\&. Also see the section |
| below on using ccache with distcc\&. |
| .IP |
| .IP "\fBCCACHE_DISABLE\fP" |
| If you set the environment variable |
| CCACHE_DISABLE then ccache will just call the real compiler, |
| bypassing the cache completely\&. |
| .IP |
| .IP "\fBCCACHE_READONLY\fP" |
| the CCACHE_READONLY environment variable |
| tells ccache to attempt to use existing cached object files, but not |
| to try to add anything new to the cache\&. If you are using this because |
| your CCACHE_DIR is read\-only, then you may find that you also need to |
| set CCACHE_TEMPDIR as otherwise ccache will fail to create the |
| temporary files\&. |
| .IP |
| .IP "\fBCCACHE_CPP2\fP" |
| If you set the environment variable CCACHE_CPP2 |
| then ccache will not use the optimisation of avoiding the 2nd call to |
| the pre\-processor by compiling the pre\-processed output that was used |
| for finding the hash in the case of a cache miss\&. This is primarily a |
| debugging option, although it is possible that some unusual compilers |
| will have problems with the intermediate filename extensions used in |
| this optimisation, in which case this option could allow ccache to be |
| used\&. |
| .IP |
| .IP "\fBCCACHE_NOCOMPRESS\fP" |
| If you set the environment variable |
| CCACHE_NOCOMPRESS then there is no compression used on files that go |
| into the cache\&. However, this setting has no effect on how files are |
| retrieved from the cache, compressed results will still be usable\&. |
| .IP |
| .IP "\fBCCACHE_NOSTATS\fP" |
| If you set the environment variable |
| CCACHE_NOSTATS then ccache will not update the statistics files on |
| each compile\&. |
| .IP |
| .IP "\fBCCACHE_NLEVELS\fP" |
| The environment variable CCACHE_NLEVELS allows |
| you to choose the number of levels of hash in the cache directory\&. The |
| default is 2\&. The minimum is 1 and the maximum is 8\&. |
| .IP |
| .IP "\fBCCACHE_HARDLINK\fP" |
| If you set the environment variable |
| CCACHE_HARDLINK then ccache will attempt to use hard links from the |
| cache directory when creating the compiler output rather than using a |
| file copy\&. Using hard links is faster, but can confuse programs like |
| \(cq\&make\(cq\& that rely on modification times\&. Hard links are never made for |
| compressed cache files\&. |
| .IP |
| .IP "\fBCCACHE_RECACHE\fP" |
| This forces ccache to not use any cached |
| results, even if it finds them\&. New results are still cached, but |
| existing cache entries are ignored\&. |
| .IP |
| .IP "\fBCCACHE_UMASK\fP" |
| This sets the umask for ccache and all child |
| processes (such as the compiler)\&. This is mostly useful when you wish |
| to share your cache with other users\&. Note that this also affects the |
| file permissions set on the object files created from your |
| compilations\&. |
| .IP |
| .IP "\fBCCACHE_HASHDIR\fP" |
| This tells ccache to hash the current working |
| directory when calculating the hash that is used to distinguish two |
| compiles\&. This prevents a problem with the storage of the current |
| working directory in the debug info of a object file, which can lead |
| ccache to give a cached object file that has the working directory in |
| the debug info set incorrectly\&. This option is off by default as the |
| incorrect setting of this debug info rarely causes problems\&. If you |
| strike problems with gdb not using the correct directory then enable |
| this option\&. |
| .IP |
| .IP "\fBCCACHE_UNIFY\fP" |
| If you set the environment variable CCACHE_UNIFY |
| then ccache will use the C/C++ unifier when hashing the pre\-processor |
| output if \-g is not used in the compile\&. The unifier is slower than a |
| normal hash, so setting this environment variable loses a little bit |
| of speed, but it means that ccache can take advantage of not |
| recompiling when the changes to the source code consist of |
| reformatting only\&. Note that using CCACHE_UNIFY changes the hash, so |
| cached compiles with CCACHE_UNIFY set cannot be used when |
| CCACHE_UNIFY is not set and vice versa\&. The reason the unifier is off |
| by default is that it can give incorrect line number information in |
| compiler warning messages\&. |
| .IP |
| .IP "\fBCCACHE_EXTENSION\fP" |
| Normally ccache tries to automatically |
| determine the extension to use for intermediate C pre\-processor files |
| based on the type of file being compiled\&. Unfortunately this sometimes |
| doesn\(cq\&t work, for example when using the aCC compiler on HP\-UX\&. On |
| systems like this you can use the CCACHE_EXTENSION option to override |
| the default\&. On HP\-UX set this environment variable to \(dq\&i\(dq\& if you use |
| the aCC compiler\&. |
| .IP |
| .IP "\fBCCACHE_STRIPC\fP" |
| If you set the environment variable |
| CCACHE_STRIPC then ccache will strip the \-c option when invoking |
| the preprocessor\&. This option is primarily for the Sun Workshop |
| C++ compiler as without this option an unwarranted warning is displayed: |
| CC: Warning: \(dq\&\-E\(dq\& redefines product from \(dq\&object\(dq\& to \(dq\&source (stdout)\(dq\& |
| when \-E and \-c is used together\&. |
| .IP |
| .IP "\fBCCACHE_SWIG\fP" |
| When using SWIG as the compiler and it does not |
| have \(cq\&swig\(cq\& in the executable name, then the CCACHE_SWIG environment |
| variable needs to be set in order for ccache to work correctly with |
| SWIG\&. The use of CCACHE_CPP2 is also recommended for SWIG due to some |
| preprocessor quirks, however, use of CCACHE_CPP2 can often be skipped |
| \-\- check your generated code with and without this option set\&. Known |
| problems are using preprocessor directives within %inline blocks and |
| the use of \(cq\&#pragma SWIG\(cq\&\&. |
| .IP |
| .SH "CACHE SIZE MANAGEMENT" |
| |
| .PP |
| By default ccache has a one gigabyte limit on the cache size and no |
| maximum number of files\&. You can set a different limit using the |
| \(dq\&ccache \-M\(dq\& and \(dq\&ccache \-F\(dq\& options, which set the size and number of |
| files limits\&. |
| .PP |
| When these limits are reached ccache will reduce the cache to 20% |
| below the numbers you specified in order to avoid doing the cache |
| clean operation too often\&. |
| .PP |
| .SH "CACHE COMPRESSION" |
| |
| .PP |
| By default on most platforms ccache will compress all files it puts |
| into the cache |
| using the zlib compression\&. While this involves a negligible |
| performance slowdown, it significantly increases the number of files |
| that fit in the cache\&. You can turn off compression setting the |
| CCACHE_NOCOMPRESS environment variable\&. |
| .PP |
| .SH "HOW IT WORKS" |
| |
| .PP |
| The basic idea is to detect when you are compiling exactly the same |
| code a 2nd time and use the previously compiled output\&. You detect |
| that it is the same code by forming a hash of: |
| .PP |
| .IP o |
| the pre\-processor output from running the compiler with \-E |
| .IP o |
| the command line options |
| .IP o |
| the real compilers size and modification time |
| .IP o |
| any stderr output generated by the compiler |
| |
| .PP |
| These are hashed using md4 (a strong hash) and a cache file is formed |
| based on that hash result\&. When the same compilation is done a second |
| time ccache is able to supply the correct compiler output (including |
| all warnings etc) from the cache\&. |
| .PP |
| ccache has been carefully written to always produce exactly the same |
| compiler output that you would get without the cache\&. If you ever |
| discover a case where ccache changes the output of your compiler then |
| please let me know\&. |
| .PP |
| .SH "USING CCACHE WITH DISTCC" |
| |
| .PP |
| distcc is a very useful program for distributing compilation across a |
| range of compiler servers\&. It is often useful to combine distcc with |
| ccache, so that compiles that are done are sped up by distcc, but that |
| ccache avoids the compile completely where possible\&. |
| .PP |
| To use distcc with ccache I recommend using the CCACHE_PREFIX |
| option\&. You just need to set the environment variable CCACHE_PREFIX to |
| \(cq\&distcc\(cq\& and ccache will prefix the command line used with the |
| compiler with the command \(cq\&distcc\(cq\&\&. |
| .PP |
| .SH "SHARING A CACHE" |
| |
| .PP |
| A group of developers can increase the cache hit rate by sharing a |
| cache directory\&. The hard links however cause unwanted side effects, |
| as all links to a cached file share the file\(cq\&s modification timestamp\&. |
| This results in false dependencies to be triggered by timestamp\-based |
| build systems whenever another user links to an existing |
| file\&. Typically, users will see that their libraries and binaries are |
| relinked without reason\&. To share a cache without side effects, the |
| following conditions need to be met: |
| .PP |
| .IP o |
| Use the same \fBCCACHE_DIR\fP environment variable setting |
| .IP o |
| Unset the \fBCCACHE_HARDLINK\fP environment variable |
| .IP o |
| Make sure everyone sets the CCACHE_UMASK environment variable |
| to 002, this ensures that cached files are accessible to everyone in |
| the group\&. |
| .IP o |
| Make sure that all users have write permission in the entire |
| cache directory (and that you trust all users of the shared cache)\&. |
| .IP o |
| Make sure that the setgid bit is set on all directories in the |
| cache\&. This tells the filesystem to inherit group ownership for new |
| directories\&. The command \(dq\&chmod g+s `find $CCACHE_DIR \-type d`\(dq\& might |
| be useful for this\&. |
| .IP o |
| Set \fBCCACHE_NOCOMPRESS\fP for all users, if there are users with |
| versions of ccache that do not support compression\&. |
| |
| .PP |
| .SH "HISTORY" |
| |
| .PP |
| ccache was inspired by the compilercache shell script script written |
| by Erik Thiele and I would like to thank him for an excellent piece of |
| work\&. See |
| http://www\&.erikyyy\&.de/compilercache/ |
| for the Erik\(cq\&s scripts\&. |
| ccache\-swig is a port of the original ccache with support added for use |
| with SWIG\&. |
| .PP |
| I wrote ccache because I wanted to get a bit more speed out of a |
| compiler cache and I wanted to remove some of the limitations of the |
| shell\-script version\&. |
| .PP |
| .SH "DIFFERENCES FROM COMPILERCACHE" |
| |
| .PP |
| The biggest differences between Erik\(cq\&s compilercache script and ccache |
| are: |
| .IP o |
| ccache is written in C, which makes it a bit faster (calling out to |
| external programs is mostly what slowed down the scripts)\&. |
| .IP o |
| ccache can automatically find the real compiler |
| .IP o |
| ccache keeps statistics on hits/misses |
| .IP o |
| ccache can do automatic cache management |
| .IP o |
| ccache can cache compiler output that includes warnings\&. In many |
| cases this gives ccache a much higher cache hit rate\&. |
| .IP o |
| ccache can handle a much wider ranger of compiler options |
| .IP o |
| ccache avoids a double call to cpp on a cache miss |
| |
| .PP |
| .SH "CREDITS" |
| |
| .PP |
| Thanks to the following people for their contributions to ccache |
| .IP o |
| Erik Thiele for the original compilercache script |
| .IP o |
| Luciano Rocha for the idea of compiling the pre\-processor output |
| to avoid a 2nd cpp pass |
| .IP o |
| Paul Russell for many suggestions and the debian packaging |
| |
| .PP |
| .SH "AUTHOR" |
| |
| .PP |
| ccache was written by Andrew Tridgell |
| http://samba\&.org/~tridge/\&. |
| ccache was adapted to create ccache\-swig for use with SWIG by William Fulton\&. |
| .PP |
| If you wish to report a problem or make a suggestion then please email |
| the SWIG developers on the swig\-devel mailing list, see |
| http://www\&.swig\&.org/mail\&.html |
| .PP |
| ccache is released under the GNU General Public License version 2 or |
| later\&. Please see the file COPYING for license details\&. |
| .PP |
| |