Man Linux: Main Page and Category List


       ccache - a fast compiler cache


       ccache [OPTION]

       ccache <compiler> [COMPILER OPTIONS]

       <compiler> [COMPILER OPTIONS]


       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.


       Here is a summary of the options to ccache.

       -s, --show-stats        show statistics summary
       -z, --zero-stats        zero statistics
       -c, --cleanup           run a cache cleanup
       -C, --clear             clear the cache completely
       -F <n>, --max-files=<n> set maximum files in cache
       -M <n>, --max-size=<n>  set maximum size of cache (use G, M or K)
       -h, --help              this help page
       -V, --version           print version number


       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

       -h, --help
              Print a options summary page

       -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.

       -z, --zero-stats
              Zero the cache statistics.

       -V, --version
              Print the ccache version number

       -c, --cleanup
              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.

       -C, --clear
              Clear the entire cache, removing all cached files.

       -F <maxfiles>, --max-files=<maxfiles>
              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.

       -M <maxsize>, --max-size=<maxsize>
              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.


       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:

         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.


       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


       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.

              the  CCACHE_DIR environment variable specifies where ccache will
              keep its cached compiler output. The default is "$HOME/.ccache".

              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.

              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.

              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.

              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.

              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.

              If  you  set the environment variable CCACHE_DISABLE then ccache
              will  just  call  the  real  compiler,   bypassing   the   cache

              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.

              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.

              If  you  set the environment variable CCACHE_NOSTATS then ccache
              will not update the statistics files on each compile.

              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.

              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  forces  ccache  to  not use any cached results, even if it
              finds them. New results are still  cached,  but  existing  cache
              entries are ignored.

              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

              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.

              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.

              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’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.

              If you set the environment variable CCACHE_NOCOMPRESS then there
              is no compression used on files that go into the cache.


       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
       "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.


       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.


       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:

       o      the pre-processor output from running the compiler with -E

       o      the command line options

       o      the real compilers size and modification time

       o      any stderr output generated by the compiler

       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.

       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.


       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’.


       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:

       o      Use the same CCACHE_DIR environment variable setting

       o      Unset the CCACHE_HARDLINK environment variable

       o      Make sure everyone sets the CCACHE_UMASK environment variable to
              002,  this  ensures that cached files are accessible to everyone
              in the group.

       o      Make sure that all users have write  permission  in  the  entire
              cache  directory  (and  that  you  trust all users of the shared

       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 "chmod g+s ‘find $CCACHE_DIR  -type
              d‘" might be useful for this.


       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 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.


       The biggest differences between Erik’s compilercache script and  ccache

       o      ccache is written in C, which makes it a bit faster (calling out
              to external programs is mostly what slowed down the scripts).

       o      ccache can automatically find the real compiler

       o      ccache keeps statistics on hits/misses

       o      ccache can do automatic cache management

       o      ccache can cache compiler output that includes warnings. In many
              cases this gives ccache a much higher cache hit rate.

       o      ccache can handle a much wider ranger of compiler options

       o      ccache avoids a double call to cpp on a cache miss


       Thanks to the following people for their contributions to ccache

       o      Erik Thiele for the original compilercache script

       o      Luciano Rocha for the idea of compiling the pre-processor output
              to avoid a 2nd cpp pass

       o      Paul Russell for many suggestions and the debian packaging


       ccache was written by Andrew Tridgell

       If you wish to report a problem or make a suggestion then please  email

       ccache  is  released  under the GNU General Public License version 2 or
       later. Please see the file COPYING for license details.

                                  April 2002                         ccache(1)