1ccache-swig(1) ccache-swig(1)
2
6 ccache-swig - a fast compiler cache
7
9 ccache-swig [OPTION]
10 ccache-swig <compiler> [COMPILER OPTIONS]
12 <compiler> [COMPILER OPTIONS]
14
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
23 Here is a summary of the options to ccache-swig.
24 -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
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 -h Print a options summary page
43 -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 -z Zero the cache statistics.
50 -V Print the ccache version number
52 -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 -C Clear the entire cache, removing all cached files.
61 -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 -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
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 To install for usage by the first method just copy ccache-swig to some‐
83 where in your path.
84 To install for the second method do something like this:
86 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 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 Note! Do not use a hard link, use a symbolic link. A hardlink will
98 cause "interesting" problems.
99
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 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
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 CCACHE_DIR
122 the CCACHE_DIR environment variable specifies where ccache will
123 keep its cached compiler output. The default is "$HOME/.ccache".
124 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 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 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 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 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 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 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 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 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 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 CCACHE_NOSTATS
189 If you set the environment variable CCACHE_NOSTATS then ccache
190 will not update the statistics files on each compile.
191 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 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 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 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 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 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 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 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 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
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 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
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
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 o the pre-processor output from running the compiler with -E
291 o the command line options
293 o the real compilers size and modification time
295 o any stderr output generated by the compiler
297 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 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
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 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
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 o Use the same CCACHE_DIR environment variable setting
331 o Unset the CCACHE_HARDLINK environment variable
333 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 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 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 o Set CCACHE_NOCOMPRESS for all users, if there are users with
348 versions of ccache that do not support compression.
349
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 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
363 The biggest differences between Erik's compilercache script and ccache
364 are:
365 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 o ccache can automatically find the real compiler
370 o ccache keeps statistics on hits/misses
372 o ccache can do automatic cache management
374 o ccache can cache compiler output that includes warnings. In many
376 cases this gives ccache a much higher cache hit rate.
377 o ccache can handle a much wider ranger of compiler options
379 o ccache avoids a double call to cpp on a cache miss
381
384 Thanks to the following people for their contributions to ccache
385 o Erik Thiele for the original compilercache script
387 o Luciano Rocha for the idea of compiling the pre-processor output
389 to avoid a 2nd cpp pass
390 o Paul Russell for many suggestions and the debian packaging
392
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 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 ccache is released under the GNU General Public License version 2 or
404 later. Please see the file COPYING for license details.
405 ccache-swig(1)