From: Joel Rosdahl Date: Thu, 22 Apr 2010 20:08:33 +0000 (+0200) Subject: Convert man page from yodl to asciidoc format X-Git-Tag: v3.0pre1~80 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=46e577edb75c109d8349574e962c312cd5e4bc0d;p=thirdparty%2Fccache.git Convert man page from yodl to asciidoc format --- diff --git a/Makefile.in b/Makefile.in index 0e0788839..fbeec6a45 100644 --- a/Makefile.in +++ b/Makefile.in @@ -14,6 +14,10 @@ CPPFLAGS = @CPPFLAGS@ -I. LDFLAGS = @LDFLAGS@ EXEEXT = @EXEEXT@ +ASCIIDOC = asciidoc +XSLTPROC = xsltproc +MANPAGE_XSL = /etc/asciidoc/docbook-xsl/manpage.xsl + libs = @LIBS@ -lm sources = \ @@ -39,8 +43,11 @@ docs: ccache.1 ccache$(EXEEXT): $(objs) $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $(objs) $(libs) -ccache.1: ccache.yo - yodl2man -o ccache.1 $(srcdir)/ccache.yo +ccache.xml: ccache.txt + $(ASCIIDOC) -d manpage -b docbook $< + +ccache.1: ccache.xml + $(XSLTPROC) --nonet $(MANPAGE_XSL) $< .PHONY: install install: all diff --git a/ccache.txt b/ccache.txt new file mode 100644 index 000000000..506cd03dd --- /dev/null +++ b/ccache.txt @@ -0,0 +1,461 @@ +CCACHE(1) +========= + + +NAME +---- + +ccache - a fast C/C++ compiler cache + + +SYNOPSIS +-------- + +[verse] +*ccache* ['options'] +*ccache* 'compiler' ['compiler options'] +'compiler' ['compiler options'] (via symbolic link) + + +DESCRIPTION +----------- + +ccache is a compiler cache. It speeds up recompilation of C/C++ code by caching +the result of previous compilations and detecting when the same compilation is +being done again. + +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 us know. + + +Features +~~~~~~~~ + +* Keeps statistics on hits/misses. +* Automatic cache size management. +* Can cache compilations that generate warnings. +* Easy installation. +* Low overhead. +* Optionally uses hard links where possible to avoid copies. + + +Limitations +~~~~~~~~~~~ + +* Only knows how to cache the compilation of a single C/C++ file. Other types + of compilations (multi-file compilation, linking, etc) will silently fall + back to running the real compiler. +* Only works with GCC and compilers that behave similar enough. +* Some compiler flags are not supported. If such a flag is detected, ccache + will silently fall back to running the real compiler. + + +RUN MODES +--------- + +There are two ways to use ccache. You can either prefix your compilation +commands with *ccache* or you can create a symbolic link (named as your +compiler) to ccache. 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 compilations. + +To install for usage by the first method just make sure *ccache* is in your path. + +To install for the second method, do something like this: + + ln -s /usr/local/bin/ccache /usr/local/bin/gcc + ln -s /usr/local/bin/ccache /usr/local/bin/g++ + ln -s /usr/local/bin/ccache /usr/local/bin/cc + ln -s /usr/local/bin/ccache /usr/local/bin/c++ + +And so forth. This will work as long as +/usr/local/bin+ comes before the path +to the compiler (which is usually in +/usr/bin+). After installing you may wish +to run ``which gcc'' to make sure that the correct link is being used. + +NOTE: Do not use a hard link, use a symbolic link. A hard link will cause +``interesting'' problems. + + +OPTIONS +------- + +These options only apply when you invoke ccache as ``ccache''. When invoked as +a compiler (via a symlink as described in the previous section), none of these +options apply. In that case your normal compiler options apply and you should +refer to the compiler's documentation. + +*-c, --cleanup*:: + + Clean the cache and recalculate 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. + + +*-C, --clear*:: + + Clear the entire cache, removing all cached files. + +*-F, --max-files*='N':: + + Set the maximum number of object files allowed in the cache. The value is + stored inside the cache directory and applies to all future compilations. + Due to the way the value is stored the actual value used is always rounded + down to the nearest multiple of 16. + +*-h, --help*:: + + Print an options summary page. + +*-M, --max-size*='SIZE':: + + Set the maximum size of the object files stored in the cache. 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. + +*-s, --show-stats*:: + + Print the current statistics summary for the cache. + +*-V, --version*:: + + Print version and copyright information. + +*-z, --zero-stats*:: + + Zero the cache statistics (but not the configured limits). + + +EXTRA OPTIONS +------------- + +When run as a compiler, ccache usually just takes the same command line options +as the compiler you are using. The only exception to this is the option +*--ccache-skip*. 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. + +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 when parsing the command line +is that any argument that exists as a file is treated as an input file name +(usually a C/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. + + +ENVIRONMENT VARIABLES +--------------------- + +ccache uses a number of environment variables to control operation. In most +cases you won't need any of these as the defaults will be fine. + +*CCACHE_BASEDIR*:: + + When hashing the output from the preprocessor, absolute paths are rewritten + to relative paths, but only for paths under the directory specified by + *CCACHE_BASEDIR*. Paths specified by *-I* and similar options get the same + treatment. This is done to get cache hits even when compiling with *-g* and + when using absolute include directory paths. The default value of + *CCACHE_BASEDIR* is the current working directory. To disable the + rewriting, set *CCACHE_BASEDIR* to the empty string. + +*CCACHE_CC*:: + + You can optionally set *CCACHE_CC* to force the name of the compiler to + use. If you don't do this then ccache works it out from the command line. + +*CCACHE_COMPILERCHECK*:: + + By default, ccache includes the modification time (mtime) and size of the + compiler in the hash to ensure that results retrieved from the cache are + accurate. The *CCACHE_COMPILERCHECK* environment variable can be used to + select another strategy. Possible values are: *none* (don't hash anything), + *mtime* (hash the compiler's mtime and size) and *content* (hash the + content of the compiler binary). Setting the variable to *content* makes + ccache very slightly slower, but makes it cope better with compiler + upgrades during a build bootstrapping process. The *none* setting may be + good for situations where you can safely use the cached results even though + the compiler's mtime or size has changed (e.g. if the compiler is built as + part of your build system and the compiler's source has not changed, or if + the compiler only has changes that don't affect code generation). You + should only set the variable to *none* if you know what you are doing. + +*CCACHE_CPP2*:: + + If you set the environment variable *CCACHE_CPP2* then ccache will not use + the optimisation of avoiding the second call to the preprocessor by + compiling the preprocessed 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. + +*CCACHE_DIR*:: + + The *CCACHE_DIR* environment variable specifies where ccache will keep its + cached compiler output. The default is *$HOME/.ccache*. + +*CCACHE_DISABLE*:: + + If you set the environment variable *CCACHE_DISABLE* then ccache will just + call the real compiler, bypassing the cache completely. + +*CCACHE_EXTENSION*:: + + Normally ccache tries to automatically determine the extension to use for + intermediate C preprocessor files based on the type of file being compiled. + Unfortunately this sometimes doesn'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 *i* if you use the ``aCC'' compiler. + +*CCACHE_HARDLINK*:: + + 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 ``make'' that rely on modification times. + Hard links are never made for compressed cache files. This means that you + typically also should set the *CCACHE_NOCOMPRESS* variable if you want to + use hard links. + +*CCACHE_HASHDIR*:: + + 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. + +*CCACHE_LOGFILE*:: + + If you set the *CCACHE_LOGFILE* environment variable then ccache will write + some log information on cache hits and misses to that file. This is useful + for tracking down problems. + +*CCACHE_NLEVELS*:: + + 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. + +*CCACHE_NOCOMPRESS*:: + + If you set the environment variable *CCACHE_NOCOMPRESS* then no compression + is used for 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. + +*CCACHE_NODIRECT*:: + + If you set the environment variable *CCACHE_NODIRECT* then ccache will not + use the direct mode. + +*CCACHE_NOSTATS*:: + + If you set the environment variable *CCACHE_NOSTATS* then ccache will not + update the statistics files on each compilation. + +*CCACHE_PATH*:: + + You can optionally set *CCACHE_PATH* to a colon-separated path where ccache + will look for the real compilers. If you don't do this then ccache will + look for the first executable matching the compiler name in the normal + *PATH* that isn't a symbolic link to ccache itself. + +*CCACHE_PREFIX*:: + + 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''. + +*CCACHE_READONLY*:: + + 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 temporary files. + +*CCACHE_RECACHE*:: + + 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. + +*CCACHE_TEMPDIR*:: + + The *CCACHE_TEMPDIR* environment variable specifies where ccache will put + temporary files. The default is *$CCACHE_DIR/tmp*. 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. + +*CCACHE_UMASK*:: + + 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. + +*CCACHE_UNIFY*:: + + If you set the environment variable *CCACHE_UNIFY* then ccache will use a + C/C++ unifier when hashing the preprocessor output if the *-g* option is + not used. 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 compilations 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. Enabling the unifier implies turning off the direct mode. + +*CCACHE_VERBOSE*:: + + If you set the environment variable *CCACHE_VERBOSE*, ccache prints (to the + standard output) the executed command lines when running the preprocessor + and the compiler. + + +CACHE SIZE MANAGEMENT +--------------------- + +By default ccache has a one gigabyte limit on the total size of object files in +the cache and no maximum number of object files. You can set different limits +using the *-M*/*--max-size* and *-F*/*--max-files* options. Use *ccache -s* to +see the cache size and the currently configured limits (in addition to other +various statistics). + + +CACHE COMPRESSION +----------------- + +By default, ccache will compress all files it puts into the cache using the +compression library zlib. While this involves a negligible performance +slowdown, it significantly increases the number of files that fit in the cache. +You can turn off compression by setting the *CCACHE_NOCOMPRESS* environment +variable. + + +HOW IT WORKS +------------ + +The basic idea is to detect when you are compiling exactly the same code a +second time and reuse the previously produced output. The detection is done by +hashing different kinds of information that should be unique for the +compilation and then using the hash sum to identify the cached output. ccache +uses MD4, a very fast cryptographic hash algorithm, for the hashing. (MD4 is +nowadays too weak to be useful in cryptographic contexts, but it should be safe +enough to be used to identify recompilations.) On a cache hit, ccache is able +to supply all of the correct compiler outputs (including all warnings, +dependency file, etc) from the cache. + +ccache has two ways of doing the detection: + +* The *direct mode* (hashes the source code and include files directly) +* The *prepreprocessor mode* (hashes output from the preprocessor) + + +The direct mode +~~~~~~~~~~~~~~~ + +In the direct mode, a hash is formed of: + +* The input source file +* The command line options +* The real compiler's size and modification time (unless *CCACHE_COMPILERCHECK* + says something else) + +Based on the hash, a data structure called ``manifest'' is looked up in the +cache. The manifest contains paths to include files (previously read by the +preprocessor), their hash sums and references to associated files produced by +the compiler. The current contents of the include files are then hashed and +compared to the information in the manifest. If there is a match, ccache knows +the result of the compilation. If there is no match (or if the direct mode is +disabled), ccache falls back to the preprocessor mode. + +The direct mode will be disabled if any of the following holds: + +* The environment variable CCACHE_NODIRECT is set +* A modification time of one of the include files is too new (needed to avoid a + race condition) +* The unifier is enabled (the environment variable *CCACHE_UNIFY* is set) +* A compiler option unsupported by the direct mode is used + + +The preprocessor mode +~~~~~~~~~~~~~~~~~~~~~ + +In the preprocessor mode, a hash is formed of: + +* The preprocessor output from running the compiler with *-E* +* The command line options except options that affect include files (*-I*, + *-include*, *-D*, etc; the theory is that these options will change the + preprocessor output if they have any effect at all) +* The real compiler's size and modification time (unless + *CCACHE_COMPILERCHECK* says something else) +* Any stderr output generated by the preprocessor + + +USING CCACHE WITH DISTCC +------------------------ + +``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 +compilations that are done are sped up by distcc, but ccache avoids the +compilation completely where possible. + +The recommended way of combining distcc and ccache is by using the +*CCACHE_PREFIX* option. You just need to set the environment variable +*CCACHE_PREFIX* to *distcc* and ccache will prefix the command line used with +the compiler with the command ``distcc''. + + +SHARING A CACHE +--------------- + +A group of developers can increase the cache hit rate by sharing a cache +directory. To share a cache without unpleasant side effects, the following +conditions should to be met: + +* Use the same *CCACHE_DIR* environment variable setting. +* Unset the *CCACHE_HARDLINK* environment variable. +* Make sure everyone sets the *CCACHE_UMASK* environment variable to 002. This + ensure that cached files are accessible to everyone in the group. +* Make sure that all users have write permission in the entire cache directory + (and that you trust all users of the shared cache). +* 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 ``find $CCACHE_DIR -type d | xargs chmod g+s'' might be useful for + this. + +The reason to avoid the hard link mode is that the hard links cause unwanted +side effects, as all links to a cached file share the file'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. + + +MORE INFORMATION +---------------- + +Credits, mailing list information, bug reporting instructions, source code, +etc, can be found on ccache's web site: + +http://ccache.samba.org + + +AUTHOR +------ + +ccache was originally written by Andrew Tridgell and is currently maintained by +Joel Rosdahl. See http://ccache.samba.org/credits.html for a list of +contributors. diff --git a/ccache.yo b/ccache.yo deleted file mode 100644 index 62051cf33..000000000 --- a/ccache.yo +++ /dev/null @@ -1,454 +0,0 @@ -mailto(bugs@ccache.samba.org) -manpage(ccache)(1)(April 2002)()() -manpagename(ccache)(a fast compiler cache) -manpagesynopsis() - -ccache [options] - -ccache compiler [compiler options] - -compiler [compiler options] (via symbolic link) - -manpagedescription() - -ccache is a compiler cache. It speeds up re-compilation of C/C++ code -by caching previous compiles and detecting when the same compile is -being done again. - -manpagesection(OPTIONS SUMMARY) - -Here is a summary of the options to ccache: - -verb( --c, --cleanup run a cache cleanup --C, --clear clear the cache completely --F, --max-files=N set maximum number of files in cache to N (use 0 for - no limit) --M, --max-size=SIZE set maximum size of cache to SIZE (use 0 for no - limit; available suffixes: G, M and K; default - suffix: G) --s, --show-stats show statistics summary --z, --zero-stats zero statistics counters - --h, --help print this help text --V, --version print version and copyright information -) - -manpageoptions() - -These options only apply when you invoke ccache as "ccache". 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. - -Some of the command line options have two variants (one short and one long). -These are shown below, separated by commas. Some options only have a long -variant. The '=' for options that take a parameter is optional; whitespace can -be used instead. If there is an argument to the option, it must be given to the -short option variant as well. - -startdit() -dit(bf(-c, --cleanup)) Clean the cache and recalculate 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. - -dit(bf(-C, --clear)) Clear the entire cache, removing all cached -files. - -dit(bf(-F, --max-files=N)) This sets the maximum -number of object 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. - -dit(bf(-M, --max-size=SIZE)) This sets the maximum size -of the object files stored in the cache. 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. - -dit(bf(-s, --show-stats)) Print the current statistics summary for the -cache. The statistics are stored spread across the subdirectories of -the cache. Using "ccache -s" adds up the statistics across all -subdirectories and prints the totals. - -dit(bf(-z, --zero-stats)) Zero the cache statistics. - -dit(bf(-h, --help)) Print a options summary page. - -dit(bf(-V, --version)) Print version and copyright information. - -enddit() - -manpagesection(INSTALLATION) - -There are two ways to use ccache. You can either prefix your compile -commands with "ccache" or you can create a symbolic link between -ccache 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. - -To install for usage by the first method just copy ccache to somewhere -in your path. - -To install for the second method do something like this: -verb( - cp ccache /usr/local/bin/ - ln -s /usr/local/bin/ccache /usr/local/bin/gcc - ln -s /usr/local/bin/ccache /usr/local/bin/g++ - ln -s /usr/local/bin/ccache /usr/local/bin/cc -) -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 -"which gcc" to make sure that the correct link is being used. - -Note! Do not use a hard link, use a symbolic link. A hardlink will -cause "interesting" problems. - -manpagesection(EXTRA OPTIONS) - -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 '--ccache-skip'. 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. - -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. - -manpagesection(ENVIRONMENT VARIABLES) - -ccache uses a number of environment variables to control operation. In -most cases you won't need any of these as the defaults will be fine. - -startdit() - -dit(bf(CCACHE_BASEDIR)) When hashing the output from the preprocessor, -absolute paths are rewritten to relative paths, but only for paths -under the directory specified by CCACHE_BASEDIR. Paths specified by -I -and similar options get the same treatment. This is done to get cache -hits even when compiling with -g and when using absolute include -directory paths. The default value of CCACHE_BASEDIR is the current -working directory. To disable the rewriting, set CCACHE_BASEDIR to the -empty string. - -dit(bf(CCACHE_CC)) You can optionally set CCACHE_CC to force the name -of the compiler to use. If you don't do this then ccache works it out -from the command line. - -dit(bf(CCACHE_COMPILERCHECK)) By default, ccache includes the -modification time (mtime) and size of the compiler in the hash to -ensure that results retrieved from the cache are accurate. The -CCACHE_COMPILERCHECK environment variable can be used to select -another strategy. Possible values are: bf(none) (don't hash anything), -bf(mtime) (hash the compiler's mtime and size) and bf(content) (hash -the content of the compiler binary). Setting the variable to -bf(content) makes ccache very slightly slower, but makes it cope -better with compiler upgrades during a build bootstrapping process. -The bf(none) setting may be good for situations where you can safely -use the cached results even though the compiler's mtime or size has -changed (e.g. if the compiler is built as part of your build system -and the compiler's source has not changed, or if the compiler only has -changes that don't affect code generation). You should only set the -variable to bf(none) if you know what you are doing. - -dit(bf(CCACHE_CPP2)) If you set the environment variable CCACHE_CPP2 -then ccache will not use the optimisation of avoiding the 2nd call to -the preprocessor by compiling the preprocessed 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. - -dit(bf(CCACHE_DIR)) the CCACHE_DIR environment variable specifies -where ccache will keep its cached compiler output. The default is -"$HOME/.ccache". - -dit(bf(CCACHE_DISABLE)) If you set the environment variable -CCACHE_DISABLE then ccache will just call the real compiler, -bypassing the cache completely. - -dit(bf(CCACHE_EXTENSION)) Normally ccache tries to automatically -determine the extension to use for intermediate C preprocessor files -based on the type of file being compiled. Unfortunately this sometimes -doesn'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 "i" if you use -the aCC compiler. - -dit(bf(CCACHE_HARDLINK)) 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 -'make' that rely on modification times. Hard links are never made for -compressed cache files. This means that you typically also should set -the CCACHE_NOCOMPRESS variable if you want to use hard links. - -dit(bf(CCACHE_HASHDIR)) 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. - -dit(bf(CCACHE_LOGFILE)) 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. - -dit(bf(CCACHE_NLEVELS)) 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. - -dit(bf(CCACHE_NOCOMPRESS)) 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. - -dit(bf(CCACHE_NODIRECT)) If you set the environment variable -CCACHE_NODIRECT then ccache will not use the direct mode. - -dit(bf(CCACHE_NOSTATS)) If you set the environment variable -CCACHE_NOSTATS then ccache will not update the statistics files on -each compile. - -dit(bf(CCACHE_PATH)) You can optionally set CCACHE_PATH to a colon -separated path where ccache will look for the real compilers. If you -don't do this then ccache will look for the first executable matching -the compiler name in the normal PATH that isn't a symbolic link to -ccache itself. - -dit(bf(CCACHE_PREFIX)) 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. - -dit(bf(CCACHE_READONLY)) 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. - -dit(bf(CCACHE_RECACHE)) 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. - -dit(bf(CCACHE_TEMPDIR)) the CCACHE_TEMPDIR environment variable specifies -where ccache will put temporary files. The default is -CCACHE_DIR/tmp. 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. - -dit(bf(CCACHE_UMASK)) 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. - -dit(bf(CCACHE_UNIFY)) If you set the environment variable CCACHE_UNIFY -then ccache will use the C/C++ unifier when hashing the preprocessor -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. Enabling the unifier implies turning off -the direct mode. - -dit(bf(CCACHE_VERBOSE)) If you set the environment variable CCACHE_VERBOSE, -ccache prints (to the standard output) the executed command lines when running -the preprocessor and the compiler. - -enddit() - -manpagesection(CACHE SIZE MANAGEMENT) - -By default ccache has a one gigabyte limit on the total size of object -files in the cache and no maximum number of object files. You can set -a different limit using the "ccache -M" and "ccache -F" options, which -set the size and number of files limits. - -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. - -manpagesection(CACHE COMPRESSION) - -By default 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. - -manpagesection(HOW IT WORKS) - -The basic idea is to detect when you are compiling exactly the same -code a second time and use the previously compiled output. The -detection is done by hashing different kinds of information that -should be unique for the compilation and then using the hash sum to -find the cached compilation output. ccache uses MD4, a very fast -cryptographic hash algorithm, for the hashing. (MD4 is nowadays too -weak to be useful in cryptographic contexts, but it should be safe -enough to be used to identify recompilations.) When the same -compilation is done a second time, ccache is able to supply the -correct compiler output (including all warnings, dependency file, etc) -from the cache. - -ccache has two ways of doing the detection: - -itemization( - it() the direct mode (hashes the source code and include files directly) - it() the pre-preprocessor mode (hashes output from the preprocessor) -) - -In the direct mode, a hash is formed of: - -itemization( - it() the input source file - it() the command line options - it() the real compiler's size and modification time (unless - bf(CCACHE_COMPILERCHECK) says something else) -) - -Based on the hash, a data structure called "manifest" is looked up in -the cache. The manifest contains paths to include files (previously -read by the preprocessor), their hash sums and references to -associated files produced by the compiler. The current contents of the -include files are then hashed and compared to the information in the -manifest. If there is a match, ccache knows the result of the -compilation. If there is no match (or if the direct mode is disabled), -ccache falls back to the preprocessor mode. - -The direct mode will be disabled if any of the following holds: - -itemization( - it() the environment variable bf(CCACHE_NODIRECT) is set - it() a modification time of any of the include files is too new - (needed to avoid a race condition) - it() the unifier is enabled (the environment variable - bf(CCACHE_UNIFY) is set) - it() a compiler option unsupported by the direct mode is used -) - -In the preprocessor mode, a hash is formed of: - -itemization( - it() the preprocessor output from running the compiler with bf(-E) - it() the command line options except options that affect include - files (bf(-I), bf(-include), bf(-D), etc; the theory is that - these options will change the preprocessor output if they have - any effect at all) - it() the real compilers size and modification time (unless - bf(CCACHE_COMPILERCHECK) says something else) - it() any stderr output generated by the preprocessor -) - -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 us know. - -manpagesection(USING CCACHE WITH DISTCC) - -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. - -To use distcc with ccache I recommend using the CCACHE_PREFIX -option. You just need to set the environment variable CCACHE_PREFIX to -'distcc' and ccache will prefix the command line used with the -compiler with the command 'distcc'. - -manpagesection(SHARING A CACHE) - -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'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: - -itemization( - it() Use the same bf(CCACHE_DIR) environment variable setting - it() Unset the bf(CCACHE_HARDLINK) environment variable - it() Make sure everyone sets the CCACHE_UMASK environment variable - to 002, this ensures that cached files are accessible to everyone in - the group. - it() Make sure that all users have write permission in the entire - cache directory (and that you trust all users of the shared cache). - it() 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 "chmod g+s `find $CCACHE_DIR -type d`" might - be useful for this. - it() Set bf(CCACHE_NOCOMPRESS) for all users, if there are users with - versions of ccache that do not support compression. -) - -manpagesection(HISTORY) - -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 -url(http://www.erikyyy.de/compilercache/)(http://www.erikyyy.de/compilercache/) -for the Erik's scripts. - -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. - -manpagesection(DIFFERENCES FROM COMPILERCACHE) - -The biggest differences between Erik's compilercache script and ccache -are: -itemization( -it() ccache is written in C, which makes it a bit faster (calling out to - external programs is mostly what slowed down the scripts). -it() ccache can automatically find the real compiler -it() ccache keeps statistics on hits/misses -it() ccache can do automatic cache management -it() ccache can cache compiler output that includes warnings. In many - cases this gives ccache a much higher cache hit rate. -it() ccache can handle a much wider ranger of compiler options -it() ccache avoids a double call to cpp on a cache miss -) - -manpagesection(CREDITS) - -Thanks to the following people for their contributions to ccache -itemization( - it() Erik Thiele for the original compilercache script - it() Luciano Rocha for the idea of compiling the preprocessor output - to avoid a 2nd cpp pass - it() Paul Russell for many suggestions and the debian packaging -) - -manpageauthor() - -ccache was written by Andrew Tridgell -url(http://samba.org/~tridge/)(http://samba.org/~tridge/) - -If you wish to report a problem or make a suggestion then please email -bugs@ccache.samba.org - -ccache is released under the GNU General Public License version 2 or -later. Please see the file COPYING for license details.