1ccache-swig(1)                                                  ccache-swig(1)
2
3
4

NAME

6       ccache-swig - a fast compiler cache
7

SYNOPSIS

9       ccache-swig [OPTION]
10
11       ccache-swig <compiler> [COMPILER OPTIONS]
12
13       <compiler> [COMPILER OPTIONS]
14

DESCRIPTION

16       ccache-swig  is  a  compiler  cache.  It  speeds  up  re-compilation of
17       C/C++/SWIG code by caching previous compiles  and  detecting  when  the
18       same  compile  is  being done again. ccache-swig is ccache plus support
19       for SWIG. ccache and ccache-swig are used interchangeably in this docu‐
20       ment.
21

OPTIONS SUMMARY

23       Here is a summary of the options to ccache-swig.
24
25       -s                      show statistics summary
26       -z                      zero statistics
27       -c                      run a cache cleanup
28       -C                      clear the cache completely
29       -F <n>                  set maximum files in cache
30       -M <n>                  set maximum size of cache (use G, M or K)
31       -h                      this help page
32       -V                      print version number
33
34
35

OPTIONS

37       These  options only apply when you invoke ccache as "ccache-swig". When
38       invoked as a compiler none of these options apply. In  that  case  your
39       normal  compiler  options  apply and you should refer to your compilers
40       documentation.
41
42       -h     Print a options summary page
43
44       -s     Print the current statistics summary for the cache. The  statis‐
45              tics  are  stored spread across the subdirectories of the cache.
46              Using "ccache-swig -s" adds up the statistics across all  subdi‐
47              rectories and prints the totals.
48
49       -z     Zero the cache statistics.
50
51       -V     Print the ccache version number
52
53       -c     Clean  the  cache and re-calculate the cache file count and size
54              totals. Normally the -c option should not be necessary as ccache
55              keeps  the cache below the specified limits at runtime and keeps
56              statistics up to date on each compile.  This  option  is  mostly
57              useful if you manually modify the cache contents or believe that
58              the cache size statistics may be inaccurate.
59
60       -C     Clear the entire cache, removing all cached files.
61
62       -F <maxfiles>
63              This sets the maximum number of files allowed in the cache.  The
64              value  is  stored  inside the cache directory and applies to all
65              future compiles. Due to the way the value is stored  the  actual
66              value used is always rounded down to the nearest multiple of 16.
67
68       -M <maxsize>
69              This  sets  the  maximum  cache size. You can specify a value in
70              gigabytes, megabytes or kilobytes by appending a G, M  or  K  to
71              the  value. The default is gigabytes. The actual value stored is
72              rounded down to the nearest multiple of 16 kilobytes.
73

INSTALLATION

75       There are two ways to use ccache. You can either  prefix  your  compile
76       commands  with  "ccache-swig" or you can create a symbolic link between
77       ccache-swig and the names of your compilers. The first method  is  most
78       convenient  if  you  just  want to try out ccache or wish to use it for
79       some specific projects. The second method is most useful for  when  you
80       wish to use ccache for all your compiles.
81
82       To install for usage by the first method just copy ccache-swig to some‐
83       where in your path.
84
85       To install for the second method do something like this:
86
87         cp ccache-swig /usr/local/bin/
88         ln -s /usr/local/bin/ccache-swig /usr/local/bin/gcc
89         ln -s /usr/local/bin/ccache-swig /usr/local/bin/g++
90         ln -s /usr/local/bin/ccache-swig /usr/local/bin/cc
91         ln -s /usr/local/bin/ccache-swig /usr/local/bin/swig
92
93       This will work as long as /usr/local/bin comes before the path  to  gcc
94       (which  is  usually  in /usr/bin). After installing you may wish to run
95       "which gcc" to make sure that the correct link is being used.
96
97       Note! Do not use a hard link, use a  symbolic  link.  A  hardlink  will
98       cause "interesting" problems.
99

EXTRA OPTIONS

101       When  run  as  a  compiler front end ccache usually just takes the same
102       command line options as the compiler you are using. The only  exception
103       to  this is the option '--ccache-skip'. That option can be used to tell
104       ccache that the next option is definitely not  a  input  filename,  and
105       should be passed along to the compiler as-is.
106
107       The  reason this can be important is that ccache does need to parse the
108       command line and determine what is an input filename and what is a com‐
109       piler  option,  as it needs the input filename to determine the name of
110       the resulting object file (among other things).  The  heuristic  ccache
111       uses  in  this parse is that any string on the command line that exists
112       as a file is treated as an input file name (usually a C file). By using
113       --ccache-skip  you  can  force  an option to not be treated as an input
114       file name and instead be passed along to the compiler as a command line
115       option.
116

ENVIRONMENT VARIABLES

118       ccache  uses a number of environment variables to control operation. In
119       most cases you won't need any of these as the defaults will be fine.
120
121       CCACHE_DIR
122              the CCACHE_DIR environment variable specifies where ccache  will
123              keep its cached compiler output. The default is "$HOME/.ccache".
124
125       CCACHE_TEMPDIR
126              the  CCACHE_TEMPDIR  environment variable specifies where ccache
127              will put temporary files. The default is the same as CCACHE_DIR.
128              Note that the CCACHE_TEMPDIR path must be on the same filesystem
129              as the CCACHE_DIR path, so that renames of files between the two
130              directories can work.
131
132       CCACHE_LOGFILE
133              If  you  set the CCACHE_LOGFILE environment variable then ccache
134              will write some log information on cache hits and misses in that
135              file. This is useful for tracking down problems.
136
137       CCACHE_VERBOSE
138              If  you  set the CCACHE_VERBOSE environment variable then ccache
139              will display on stdout all  the  compiler  invocations  that  it
140              makes. This can useful for debugging unexpected problems.
141
142       CCACHE_PATH
143              You  can  optionally  set  CCACHE_PATH to a colon separated path
144              where ccache will look for the real compilers. If you  don't  do
145              this then ccache will look for the first executable matching the
146              compiler name in the normal PATH that isn't a symbolic  link  to
147              ccache itself.
148
149       CCACHE_CC
150              You  can  optionally set CCACHE_CC to force the name of the com‐
151              piler to use. If you don't do this then ccache works it out from
152              the command line.
153
154       CCACHE_PREFIX
155              This  option  adds a prefix to the command line that ccache runs
156              when invoking the compiler. Also see the section below on  using
157              ccache with distcc.
158
159       CCACHE_DISABLE
160              If  you  set the environment variable CCACHE_DISABLE then ccache
161              will just call the  real  compiler,  bypassing  the  cache  com‐
162              pletely.
163
164       CCACHE_READONLY
165              the CCACHE_READONLY environment variable tells ccache to attempt
166              to use existing cached object files, but not to try to add  any‐
167              thing  new  to  the  cache.  If  you are using this because your
168              CCACHE_DIR is read-only, then you may find that you also need to
169              set  CCACHE_TEMPDIR  as otherwise ccache will fail to create the
170              temporary files.
171
172       CCACHE_CPP2
173              If you set the environment variable CCACHE_CPP2 then ccache will
174              not  use  the  optimisation of avoiding the 2nd call to the pre-
175              processor by compiling the pre-processed output  that  was  used
176              for  finding  the hash in the case of a cache miss. This is pri‐
177              marily a debugging option, although it  is  possible  that  some
178              unusual compilers will have problems with the intermediate file‐
179              name extensions used in this optimisation, in  which  case  this
180              option could allow ccache to be used.
181
182       CCACHE_NOCOMPRESS
183              If you set the environment variable CCACHE_NOCOMPRESS then there
184              is no compression used on files that go into the cache. However,
185              this  setting  has no effect on how files are retrieved from the
186              cache, compressed results will still be usable.
187
188       CCACHE_NOSTATS
189              If you set the environment variable CCACHE_NOSTATS  then  ccache
190              will not update the statistics files on each compile.
191
192       CCACHE_NLEVELS
193              The environment variable CCACHE_NLEVELS allows you to choose the
194              number of levels of hash in the cache directory. The default  is
195              2. The minimum is 1 and the maximum is 8.
196
197       CCACHE_HARDLINK
198              If  you set the environment variable CCACHE_HARDLINK then ccache
199              will attempt to use hard links from  the  cache  directory  when
200              creating  the  compiler  output  rather  than using a file copy.
201              Using hard links is faster, but can confuse programs like 'make'
202              that  rely  on modification times. Hard links are never made for
203              compressed cache files.
204
205       CCACHE_RECACHE
206              This forces ccache to not use any cached  results,  even  if  it
207              finds  them.  New  results  are still cached, but existing cache
208              entries are ignored.
209
210       CCACHE_UMASK
211              This sets the umask for ccache and all child processes (such  as
212              the compiler). This is mostly useful when you wish to share your
213              cache with other users. Note that this  also  affects  the  file
214              permissions  set  on the object files created from your compila‐
215              tions.
216
217       CCACHE_HASHDIR
218              This tells ccache to hash the  current  working  directory  when
219              calculating  the  hash that is used to distinguish two compiles.
220              This prevents a problem with the storage of the current  working
221              directory  in  the  debug  info of a object file, which can lead
222              ccache to give a cached object file that has the working  direc‐
223              tory  in  the  debug info set incorrectly. This option is off by
224              default as the incorrect  setting  of  this  debug  info  rarely
225              causes  problems.  If you strike problems with gdb not using the
226              correct directory then enable this option.
227
228       CCACHE_UNIFY
229              If you set the environment  variable  CCACHE_UNIFY  then  ccache
230              will use the C/C++ unifier when hashing the pre-processor output
231              if -g is not used in the compile. The unifier is slower  than  a
232              normal hash, so setting this environment variable loses a little
233              bit of speed, but it means that ccache can take advantage of not
234              recompiling  when  the  changes  to  the  source code consist of
235              reformatting only. Note  that  using  CCACHE_UNIFY  changes  the
236              hash,  so  cached  compiles with CCACHE_UNIFY set cannot be used
237              when CCACHE_UNIFY is not set and vice versa. The reason the uni‐
238              fier is off by default is that it can give incorrect line number
239              information in compiler warning messages.
240
241       CCACHE_EXTENSION
242              Normally ccache tries to automatically determine  the  extension
243              to  use for intermediate C pre-processor files based on the type
244              of file being compiled.  Unfortunately  this  sometimes  doesn't
245              work,  for example when using the aCC compiler on HP-UX. On sys‐
246              tems like this you can use the CCACHE_EXTENSION option to  over‐
247              ride  the default. On HP-UX set this environment variable to "i"
248              if you use the aCC compiler.
249
250       CCACHE_STRIPC
251              If you set the environment variable  CCACHE_STRIPC  then  ccache
252              will  strip  the  -c option when invoking the preprocessor. This
253              option is primarily for the Sun Workshop C++ compiler as without
254              this  option  an  unwarranted warning is displayed: CC: Warning:
255              "-E" redefines product from "object" to "source  (stdout)"  when
256              -E and -c is used together.
257
258       CCACHE_SWIG
259              When  using  SWIG as the compiler and it does not have 'swig' in
260              the executable name, then the CCACHE_SWIG  environment  variable
261              needs to be set in order for ccache to work correctly with SWIG.
262              The use of CCACHE_CPP2 is also recommended for SWIG due to  some
263              preprocessor  quirks,  however,  use of CCACHE_CPP2 can often be
264              skipped -- check your  generated  code  with  and  without  this
265              option  set.  Known  problems  are using preprocessor directives
266              within %inline blocks and the use of '#pragma SWIG'.
267

CACHE SIZE MANAGEMENT

269       By default ccache has a one gigabyte limit on the  cache  size  and  no
270       maximum  number  of  files.  You  can  set  a different limit using the
271       "ccache -M" and "ccache -F" options, which set the size and  number  of
272       files limits.
273
274       When these limits are reached ccache will reduce the cache to 20% below
275       the numbers you specified in order to avoid doing the cache clean oper‐
276       ation too often.
277

CACHE COMPRESSION

279       By  default  on  most  platforms ccache will compress all files it puts
280       into the cache using the zlib compression. While this involves a negli‐
281       gible  performance  slowdown,  it significantly increases the number of
282       files that fit in the cache. You can turn off compression  setting  the
283       CCACHE_NOCOMPRESS environment variable.
284

HOW IT WORKS

286       The  basic  idea  is  to detect when you are compiling exactly the same
287       code a 2nd time and use the previously compiled output. You detect that
288       it is the same code by forming a hash of:
289
290       o      the pre-processor output from running the compiler with -E
291
292       o      the command line options
293
294       o      the real compilers size and modification time
295
296       o      any stderr output generated by the compiler
297
298
299       These  are  hashed using md4 (a strong hash) and a cache file is formed
300       based on that hash result. When the same compilation is done  a  second
301       time  ccache  is  able to supply the correct compiler output (including
302       all warnings etc) from the cache.
303
304       ccache has been carefully written to always produce  exactly  the  same
305       compiler  output that you would get without the cache. If you ever dis‐
306       cover a case where ccache changes the  output  of  your  compiler  then
307       please let me know.
308

USING CCACHE WITH DISTCC

310       distcc  is  a very useful program for distributing compilation across a
311       range of compiler servers. It is often useful to  combine  distcc  with
312       ccache,  so that compiles that are done are sped up by distcc, but that
313       ccache avoids the compile completely where possible.
314
315       To use distcc with ccache I recommend using the  CCACHE_PREFIX  option.
316       You just need to set the environment variable CCACHE_PREFIX to 'distcc'
317       and ccache will prefix the command line used with the compiler with the
318       command 'distcc'.
319

SHARING A CACHE

321       A  group  of  developers  can  increase the cache hit rate by sharing a
322       cache directory.  The hard links however cause unwanted  side  effects,
323       as  all links to a cached file share the file's modification timestamp.
324       This results in false dependencies to be triggered  by  timestamp-based
325       build  systems  whenever  another user links to an existing file. Typi‐
326       cally, users will see that their libraries and  binaries  are  relinked
327       without  reason.   To share a cache without side effects, the following
328       conditions need to be met:
329
330       o      Use the same CCACHE_DIR environment variable setting
331
332       o      Unset the CCACHE_HARDLINK environment variable
333
334       o      Make sure everyone sets the CCACHE_UMASK environment variable to
335              002,  this  ensures that cached files are accessible to everyone
336              in the group.
337
338       o      Make sure that all users have write  permission  in  the  entire
339              cache  directory  (and  that  you  trust all users of the shared
340              cache).
341
342       o      Make sure that the setgid bit is set on all directories  in  the
343              cache.  This tells the filesystem to inherit group ownership for
344              new directories. The command "chmod g+s `find $CCACHE_DIR  -type
345              d`" might be useful for this.
346
347       o      Set  CCACHE_NOCOMPRESS  for  all  users, if there are users with
348              versions of ccache that do not support compression.
349
350

HISTORY

352       ccache was inspired by the compilercache shell script script written by
353       Erik  Thiele  and  I  would like to thank him for an excellent piece of
354       work. See http://www.erikyyy.de/compilercache/ for the Erik's  scripts.
355       ccache-swig is a port of the original ccache with support added for use
356       with SWIG.
357
358       I wrote ccache because I wanted to get a bit more speed out of  a  com‐
359       piler  cache  and  I  wanted  to  remove some of the limitations of the
360       shell-script version.
361

DIFFERENCES FROM COMPILERCACHE

363       The biggest differences between Erik's compilercache script and  ccache
364       are:
365
366       o      ccache is written in C, which makes it a bit faster (calling out
367              to external programs is mostly what slowed down the scripts).
368
369       o      ccache can automatically find the real compiler
370
371       o      ccache keeps statistics on hits/misses
372
373       o      ccache can do automatic cache management
374
375       o      ccache can cache compiler output that includes warnings. In many
376              cases this gives ccache a much higher cache hit rate.
377
378       o      ccache can handle a much wider ranger of compiler options
379
380       o      ccache avoids a double call to cpp on a cache miss
381
382

CREDITS

384       Thanks to the following people for their contributions to ccache
385
386       o      Erik Thiele for the original compilercache script
387
388       o      Luciano Rocha for the idea of compiling the pre-processor output
389              to avoid a 2nd cpp pass
390
391       o      Paul Russell for many suggestions and the debian packaging
392
393

AUTHOR

395       ccache  was  written  by  Andrew  Tridgell   http://samba.org/~tridge/.
396       ccache  was  adapted to create ccache-swig for use with SWIG by William
397       Fulton.
398
399       If you wish to report a problem or make a suggestion then please  email
400       the   SWIG   developers   on   the   swig-devel   mailing   list,   see
401       http://www.swig.org/mail.html
402
403       ccache is released under the GNU General Public License  version  2  or
404       later. Please see the file COPYING for license details.
405
406                                                                ccache-swig(1)
Impressum