mirror of
https://github.com/reactos/ccache.git
synced 2025-02-04 02:26:07 +00:00
266 lines
9.0 KiB
Groff
266 lines
9.0 KiB
Groff
.TH "ccache" "1" "April 2002" "" ""
|
|
.SH "NAME"
|
|
ccache \- a fast compiler cache
|
|
.SH "SYNOPSIS"
|
|
.PP
|
|
ccache [OPTION]
|
|
.PP
|
|
ccache <compiler> [COMPILER OPTIONS]
|
|
.PP
|
|
<compiler> [COMPILER OPTIONS]
|
|
.PP
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
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\&.
|
|
.PP
|
|
.SH "OPTIONS SUMMARY"
|
|
.PP
|
|
Here is a summary of the options to ccache\&.
|
|
.PP
|
|
|
|
.nf
|
|
|
|
|
|
-s show statistics summary
|
|
-z zero statistics
|
|
-c run a cache cleanup
|
|
-F <maxfiles> set maximum files in cache
|
|
-M <maxsize> 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 "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\&.
|
|
.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 "ccache -s" 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-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
|
|
.PP
|
|
.SH "INSTALLATION"
|
|
.PP
|
|
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\&.
|
|
.PP
|
|
To install for usage by the first method just copy ccache to somewhere
|
|
in your path\&.
|
|
.PP
|
|
To install for the second method do something like this:
|
|
|
|
.nf
|
|
|
|
|
|
cp ccache /usr/local/bin/
|
|
ln -s /usr/local/bin/ccache /usr/local/bin/gcc
|
|
ln -s /usr/local/bin/ccache /usr/local/bin/cc
|
|
|
|
.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
|
|
"which gcc" to make sure that the correct link is being used\&.
|
|
.PP
|
|
.SH "ENVIRONMENT VARIABLES"
|
|
.PP
|
|
ccache used a number of environment variables to control operation\&. In
|
|
most cases you won\&'t need any of these as the defaults will be fine\&.
|
|
.PP
|
|
.IP
|
|
.IP "\fBCCACHE_DIR\fP"
|
|
the CCACHE_DIR environment variable specifies
|
|
where ccache will keep its cached compiler output\&. The default is
|
|
"$HOME/\&.ccache"\&.
|
|
.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_PATH\fP"
|
|
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\&.
|
|
.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_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_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_NOLINK\fP"
|
|
If you set the environment variable
|
|
CCACHE_NOLINK then ccache will not use hard links from the cache
|
|
directory when creating the compiler output and will do a file copy
|
|
instead\&. The main reason for setting this option is to avoid the
|
|
update of the modification time on object files that are the result of
|
|
the same compilation in a different directory\&.
|
|
.IP
|
|
.IP "\fBCCACHE_NOUNIFY\fP"
|
|
If you set the environment variable
|
|
CCACHE_NOUNIFY then ccache will not use the C/C++ unifier when hashing
|
|
the pre-processor output\&. The unifier is slower than a normal hash, so
|
|
setting this environment variable gains a little bit of speed, but it
|
|
means that ccache can\&'t take advantage of not recompiling when the
|
|
changes to the source code consist of reformatting only\&. Note that
|
|
using CCACHE_NOUNIFY changes the hash, so cached compiles with
|
|
CCACHE_NOUNIFY set cannot be used when CCACHE_NOUNIFY is not set and
|
|
vice versa\&.
|
|
.IP
|
|
.PP
|
|
.SH "CACHE SIZE MANAGEMENT"
|
|
.PP
|
|
By default ccache has no limit on the cache size\&. You can set a limit
|
|
using the "ccache -M" and "ccache -F" 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 "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 "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\&'s scripts\&.
|
|
.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\&'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/
|
|
.PP
|
|
If you wish to report a problem or make a suggestion then please email
|
|
bugs@ccache\&.samba\&.org
|
|
.PP
|
|
ccache is released under the GNU General Public License version 2 or
|
|
later\&. Please see the file COPYING for license details\&.
|