1899
|
1 .TH "ccache\-swig" "1" "" "" ""
|
|
2
|
|
3 .PP
|
|
4 .SH "NAME"
|
|
5 ccache\-swig \- a fast compiler cache
|
|
6 .PP
|
|
7 .SH "SYNOPSIS"
|
|
8
|
|
9 .PP
|
|
10 ccache\-swig [OPTION]
|
|
11 .PP
|
|
12 ccache\-swig <compiler> [COMPILER OPTIONS]
|
|
13 .PP
|
|
14 <compiler> [COMPILER OPTIONS]
|
|
15 .PP
|
|
16 .SH "DESCRIPTION"
|
|
17
|
|
18 .PP
|
|
19 ccache\-swig is a compiler cache\&. It speeds up re\-compilation of C/C++/SWIG code
|
|
20 by caching previous compiles and detecting when the same compile is
|
|
21 being done again\&. ccache\-swig is ccache plus support for SWIG\&. ccache
|
|
22 and ccache\-swig are used interchangeably in this document\&.
|
|
23 .PP
|
|
24 .SH "OPTIONS SUMMARY"
|
|
25
|
|
26 .PP
|
|
27 Here is a summary of the options to ccache\-swig\&.
|
|
28 .PP
|
|
29 .nf
|
|
30
|
|
31 \-s show statistics summary
|
|
32 \-z zero statistics
|
|
33 \-c run a cache cleanup
|
|
34 \-C clear the cache completely
|
|
35 \-F <n> set maximum files in cache
|
|
36 \-M <n> set maximum size of cache (use G, M or K)
|
|
37 \-h this help page
|
|
38 \-V print version number
|
|
39
|
|
40 .fi
|
|
41
|
|
42 .PP
|
|
43 .SH "OPTIONS"
|
|
44
|
|
45 .PP
|
|
46 These options only apply when you invoke ccache as \(dq\&ccache\-swig\(dq\&\&. When
|
|
47 invoked as a compiler none of these options apply\&. In that case your
|
|
48 normal compiler options apply and you should refer to your compilers
|
|
49 documentation\&.
|
|
50 .PP
|
|
51 .IP "\fB\-h\fP"
|
|
52 Print a options summary page
|
|
53 .IP
|
|
54 .IP "\fB\-s\fP"
|
|
55 Print the current statistics summary for the cache\&. The
|
|
56 statistics are stored spread across the subdirectories of the
|
|
57 cache\&. Using \(dq\&ccache\-swig \-s\(dq\& adds up the statistics across all
|
|
58 subdirectories and prints the totals\&.
|
|
59 .IP
|
|
60 .IP "\fB\-z\fP"
|
|
61 Zero the cache statistics\&.
|
|
62 .IP
|
|
63 .IP "\fB\-V\fP"
|
|
64 Print the ccache version number
|
|
65 .IP
|
|
66 .IP "\fB\-c\fP"
|
|
67 Clean the cache and re\-calculate the cache file count and
|
|
68 size totals\&. Normally the \-c option should not be necessary as ccache
|
|
69 keeps the cache below the specified limits at runtime and keeps
|
|
70 statistics up to date on each compile\&. This option is mostly useful
|
|
71 if you manually modify the cache contents or believe that the cache
|
|
72 size statistics may be inaccurate\&.
|
|
73 .IP
|
|
74 .IP "\fB\-C\fP"
|
|
75 Clear the entire cache, removing all cached files\&.
|
|
76 .IP
|
|
77 .IP "\fB\-F <maxfiles>\fP"
|
|
78 This sets the maximum number of files allowed in
|
|
79 the cache\&. The value is stored inside the cache directory and applies
|
|
80 to all future compiles\&. Due to the way the value is stored the actual
|
|
81 value used is always rounded down to the nearest multiple of 16\&.
|
|
82 .IP
|
|
83 .IP "\fB\-M <maxsize>\fP"
|
|
84 This sets the maximum cache size\&. You can specify
|
|
85 a value in gigabytes, megabytes or kilobytes by appending a G, M or K
|
|
86 to the value\&. The default is gigabytes\&. The actual value stored is
|
|
87 rounded down to the nearest multiple of 16 kilobytes\&.
|
|
88 .IP
|
|
89 .SH "INSTALLATION"
|
|
90
|
|
91 .PP
|
|
92 There are two ways to use ccache\&. You can either prefix your compile
|
|
93 commands with \(dq\&ccache\-swig\(dq\& or you can create a symbolic link between
|
|
94 ccache\-swig and the names of your compilers\&. The first method is most
|
|
95 convenient if you just want to try out ccache or wish to use it for
|
|
96 some specific projects\&. The second method is most useful for when you
|
|
97 wish to use ccache for all your compiles\&.
|
|
98 .PP
|
|
99 To install for usage by the first method just copy ccache\-swig to somewhere
|
|
100 in your path\&.
|
|
101 .PP
|
|
102 To install for the second method do something like this:
|
|
103 .nf
|
|
104
|
|
105 cp ccache\-swig /usr/local/bin/
|
|
106 ln \-s /usr/local/bin/ccache\-swig /usr/local/bin/gcc
|
|
107 ln \-s /usr/local/bin/ccache\-swig /usr/local/bin/g++
|
|
108 ln \-s /usr/local/bin/ccache\-swig /usr/local/bin/cc
|
|
109 ln \-s /usr/local/bin/ccache\-swig /usr/local/bin/swig
|
|
110
|
|
111 .fi
|
|
112 This will work as long as /usr/local/bin comes before the path to gcc
|
|
113 (which is usually in /usr/bin)\&. After installing you may wish to run
|
|
114 \(dq\&which gcc\(dq\& to make sure that the correct link is being used\&.
|
|
115 .PP
|
|
116 Note! Do not use a hard link, use a symbolic link\&. A hardlink will
|
|
117 cause \(dq\&interesting\(dq\& problems\&.
|
|
118 .PP
|
|
119 .SH "EXTRA OPTIONS"
|
|
120
|
|
121 .PP
|
|
122 When run as a compiler front end ccache usually just takes the same
|
|
123 command line options as the compiler you are using\&. The only exception
|
|
124 to this is the option \(cq\&\-\-ccache\-skip\(cq\&\&. That option can be used to tell
|
|
125 ccache that the next option is definitely not a input filename, and
|
|
126 should be passed along to the compiler as\-is\&.
|
|
127 .PP
|
|
128 The reason this can be important is that ccache does need to parse the
|
|
129 command line and determine what is an input filename and what is a
|
|
130 compiler option, as it needs the input filename to determine the name
|
|
131 of the resulting object file (among other things)\&. The heuristic
|
|
132 ccache uses in this parse is that any string on the command line that
|
|
133 exists as a file is treated as an input file name (usually a C
|
|
134 file)\&. By using \-\-ccache\-skip you can force an option to not be
|
|
135 treated as an input file name and instead be passed along to the
|
|
136 compiler as a command line option\&.
|
|
137 .PP
|
|
138 .SH "ENVIRONMENT VARIABLES"
|
|
139
|
|
140 .PP
|
|
141 ccache uses a number of environment variables to control operation\&. In
|
|
142 most cases you won\(cq\&t need any of these as the defaults will be fine\&.
|
|
143 .PP
|
|
144 .IP "\fBCCACHE_DIR\fP"
|
|
145 the CCACHE_DIR environment variable specifies
|
|
146 where ccache will keep its cached compiler output\&. The default is
|
|
147 \(dq\&$HOME/\&.ccache\(dq\&\&.
|
|
148 .IP
|
|
149 .IP "\fBCCACHE_TEMPDIR\fP"
|
|
150 the CCACHE_TEMPDIR environment variable specifies
|
|
151 where ccache will put temporary files\&. The default is the same as
|
|
152 CCACHE_DIR\&. Note that the CCACHE_TEMPDIR path must be on the same
|
|
153 filesystem as the CCACHE_DIR path, so that renames of files between
|
|
154 the two directories can work\&.
|
|
155 .IP
|
|
156 .IP "\fBCCACHE_LOGFILE\fP"
|
|
157 If you set the CCACHE_LOGFILE environment
|
|
158 variable then ccache will write some log information on cache hits
|
|
159 and misses in that file\&. This is useful for tracking down problems\&.
|
|
160 .IP
|
|
161 .IP "\fBCCACHE_VERBOSE\fP"
|
|
162 If you set the CCACHE_VERBOSE environment
|
|
163 variable then ccache will display on stdout all the compiler invocations
|
|
164 that it makes\&. This can useful for debugging unexpected problems\&.
|
|
165 .IP
|
|
166 .IP "\fBCCACHE_PATH\fP"
|
|
167 You can optionally set CCACHE_PATH to a colon
|
|
168 separated path where ccache will look for the real compilers\&. If you
|
|
169 don\(cq\&t do this then ccache will look for the first executable matching
|
|
170 the compiler name in the normal PATH that isn\(cq\&t a symbolic link to
|
|
171 ccache itself\&.
|
|
172 .IP
|
|
173 .IP "\fBCCACHE_CC\fP"
|
|
174 You can optionally set CCACHE_CC to force the name
|
|
175 of the compiler to use\&. If you don\(cq\&t do this then ccache works it out
|
|
176 from the command line\&.
|
|
177 .IP
|
|
178 .IP "\fBCCACHE_PREFIX\fP"
|
|
179 This option adds a prefix to the command line
|
|
180 that ccache runs when invoking the compiler\&. Also see the section
|
|
181 below on using ccache with distcc\&.
|
|
182 .IP
|
|
183 .IP "\fBCCACHE_DISABLE\fP"
|
|
184 If you set the environment variable
|
|
185 CCACHE_DISABLE then ccache will just call the real compiler,
|
|
186 bypassing the cache completely\&.
|
|
187 .IP
|
|
188 .IP "\fBCCACHE_READONLY\fP"
|
|
189 the CCACHE_READONLY environment variable
|
|
190 tells ccache to attempt to use existing cached object files, but not
|
|
191 to try to add anything new to the cache\&. If you are using this because
|
|
192 your CCACHE_DIR is read\-only, then you may find that you also need to
|
|
193 set CCACHE_TEMPDIR as otherwise ccache will fail to create the
|
|
194 temporary files\&.
|
|
195 .IP
|
|
196 .IP "\fBCCACHE_CPP2\fP"
|
|
197 If you set the environment variable CCACHE_CPP2
|
|
198 then ccache will not use the optimisation of avoiding the 2nd call to
|
|
199 the pre\-processor by compiling the pre\-processed output that was used
|
|
200 for finding the hash in the case of a cache miss\&. This is primarily a
|
|
201 debugging option, although it is possible that some unusual compilers
|
|
202 will have problems with the intermediate filename extensions used in
|
|
203 this optimisation, in which case this option could allow ccache to be
|
|
204 used\&.
|
|
205 .IP
|
|
206 .IP "\fBCCACHE_NOCOMPRESS\fP"
|
|
207 If you set the environment variable
|
|
208 CCACHE_NOCOMPRESS then there is no compression used on files that go
|
|
209 into the cache\&. However, this setting has no effect on how files are
|
|
210 retrieved from the cache, compressed results will still be usable\&.
|
|
211 .IP
|
|
212 .IP "\fBCCACHE_NOSTATS\fP"
|
|
213 If you set the environment variable
|
|
214 CCACHE_NOSTATS then ccache will not update the statistics files on
|
|
215 each compile\&.
|
|
216 .IP
|
|
217 .IP "\fBCCACHE_NLEVELS\fP"
|
|
218 The environment variable CCACHE_NLEVELS allows
|
|
219 you to choose the number of levels of hash in the cache directory\&. The
|
|
220 default is 2\&. The minimum is 1 and the maximum is 8\&.
|
|
221 .IP
|
|
222 .IP "\fBCCACHE_HARDLINK\fP"
|
|
223 If you set the environment variable
|
|
224 CCACHE_HARDLINK then ccache will attempt to use hard links from the
|
|
225 cache directory when creating the compiler output rather than using a
|
|
226 file copy\&. Using hard links is faster, but can confuse programs like
|
|
227 \(cq\&make\(cq\& that rely on modification times\&. Hard links are never made for
|
|
228 compressed cache files\&.
|
|
229 .IP
|
|
230 .IP "\fBCCACHE_RECACHE\fP"
|
|
231 This forces ccache to not use any cached
|
|
232 results, even if it finds them\&. New results are still cached, but
|
|
233 existing cache entries are ignored\&.
|
|
234 .IP
|
|
235 .IP "\fBCCACHE_UMASK\fP"
|
|
236 This sets the umask for ccache and all child
|
|
237 processes (such as the compiler)\&. This is mostly useful when you wish
|
|
238 to share your cache with other users\&. Note that this also affects the
|
|
239 file permissions set on the object files created from your
|
|
240 compilations\&.
|
|
241 .IP
|
|
242 .IP "\fBCCACHE_HASHDIR\fP"
|
|
243 This tells ccache to hash the current working
|
|
244 directory when calculating the hash that is used to distinguish two
|
|
245 compiles\&. This prevents a problem with the storage of the current
|
|
246 working directory in the debug info of a object file, which can lead
|
|
247 ccache to give a cached object file that has the working directory in
|
|
248 the debug info set incorrectly\&. This option is off by default as the
|
|
249 incorrect setting of this debug info rarely causes problems\&. If you
|
|
250 strike problems with gdb not using the correct directory then enable
|
|
251 this option\&.
|
|
252 .IP
|
|
253 .IP "\fBCCACHE_UNIFY\fP"
|
|
254 If you set the environment variable CCACHE_UNIFY
|
|
255 then ccache will use the C/C++ unifier when hashing the pre\-processor
|
|
256 output if \-g is not used in the compile\&. The unifier is slower than a
|
|
257 normal hash, so setting this environment variable loses a little bit
|
|
258 of speed, but it means that ccache can take advantage of not
|
|
259 recompiling when the changes to the source code consist of
|
|
260 reformatting only\&. Note that using CCACHE_UNIFY changes the hash, so
|
|
261 cached compiles with CCACHE_UNIFY set cannot be used when
|
|
262 CCACHE_UNIFY is not set and vice versa\&. The reason the unifier is off
|
|
263 by default is that it can give incorrect line number information in
|
|
264 compiler warning messages\&.
|
|
265 .IP
|
|
266 .IP "\fBCCACHE_EXTENSION\fP"
|
|
267 Normally ccache tries to automatically
|
|
268 determine the extension to use for intermediate C pre\-processor files
|
|
269 based on the type of file being compiled\&. Unfortunately this sometimes
|
|
270 doesn\(cq\&t work, for example when using the aCC compiler on HP\-UX\&. On
|
|
271 systems like this you can use the CCACHE_EXTENSION option to override
|
|
272 the default\&. On HP\-UX set this environment variable to \(dq\&i\(dq\& if you use
|
|
273 the aCC compiler\&.
|
|
274 .IP
|
|
275 .IP "\fBCCACHE_STRIPC\fP"
|
|
276 If you set the environment variable
|
|
277 CCACHE_STRIPC then ccache will strip the \-c option when invoking
|
|
278 the preprocessor\&. This option is primarily for the Sun Workshop
|
|
279 C++ compiler as without this option an unwarranted warning is displayed:
|
|
280 CC: Warning: \(dq\&\-E\(dq\& redefines product from \(dq\&object\(dq\& to \(dq\&source (stdout)\(dq\&
|
|
281 when \-E and \-c is used together\&.
|
|
282 .IP
|
|
283 .IP "\fBCCACHE_SWIG\fP"
|
|
284 When using SWIG as the compiler and it does not
|
|
285 have \(cq\&swig\(cq\& in the executable name, then the CCACHE_SWIG environment
|
|
286 variable needs to be set in order for ccache to work correctly with
|
|
287 SWIG\&. The use of CCACHE_CPP2 is also recommended for SWIG due to some
|
|
288 preprocessor quirks, however, use of CCACHE_CPP2 can often be skipped
|
|
289 \-\- check your generated code with and without this option set\&. Known
|
|
290 problems are using preprocessor directives within %inline blocks and
|
|
291 the use of \(cq\&#pragma SWIG\(cq\&\&.
|
|
292 .IP
|
|
293 .SH "CACHE SIZE MANAGEMENT"
|
|
294
|
|
295 .PP
|
|
296 By default ccache has a one gigabyte limit on the cache size and no
|
|
297 maximum number of files\&. You can set a different limit using the
|
|
298 \(dq\&ccache \-M\(dq\& and \(dq\&ccache \-F\(dq\& options, which set the size and number of
|
|
299 files limits\&.
|
|
300 .PP
|
|
301 When these limits are reached ccache will reduce the cache to 20%
|
|
302 below the numbers you specified in order to avoid doing the cache
|
|
303 clean operation too often\&.
|
|
304 .PP
|
|
305 .SH "CACHE COMPRESSION"
|
|
306
|
|
307 .PP
|
|
308 By default on most platforms ccache will compress all files it puts
|
|
309 into the cache
|
|
310 using the zlib compression\&. While this involves a negligible
|
|
311 performance slowdown, it significantly increases the number of files
|
|
312 that fit in the cache\&. You can turn off compression setting the
|
|
313 CCACHE_NOCOMPRESS environment variable\&.
|
|
314 .PP
|
|
315 .SH "HOW IT WORKS"
|
|
316
|
|
317 .PP
|
|
318 The basic idea is to detect when you are compiling exactly the same
|
|
319 code a 2nd time and use the previously compiled output\&. You detect
|
|
320 that it is the same code by forming a hash of:
|
|
321 .PP
|
|
322 .IP o
|
|
323 the pre\-processor output from running the compiler with \-E
|
|
324 .IP o
|
|
325 the command line options
|
|
326 .IP o
|
|
327 the real compilers size and modification time
|
|
328 .IP o
|
|
329 any stderr output generated by the compiler
|
|
330
|
|
331 .PP
|
|
332 These are hashed using md4 (a strong hash) and a cache file is formed
|
|
333 based on that hash result\&. When the same compilation is done a second
|
|
334 time ccache is able to supply the correct compiler output (including
|
|
335 all warnings etc) from the cache\&.
|
|
336 .PP
|
|
337 ccache has been carefully written to always produce exactly the same
|
|
338 compiler output that you would get without the cache\&. If you ever
|
|
339 discover a case where ccache changes the output of your compiler then
|
|
340 please let me know\&.
|
|
341 .PP
|
|
342 .SH "USING CCACHE WITH DISTCC"
|
|
343
|
|
344 .PP
|
|
345 distcc is a very useful program for distributing compilation across a
|
|
346 range of compiler servers\&. It is often useful to combine distcc with
|
|
347 ccache, so that compiles that are done are sped up by distcc, but that
|
|
348 ccache avoids the compile completely where possible\&.
|
|
349 .PP
|
|
350 To use distcc with ccache I recommend using the CCACHE_PREFIX
|
|
351 option\&. You just need to set the environment variable CCACHE_PREFIX to
|
|
352 \(cq\&distcc\(cq\& and ccache will prefix the command line used with the
|
|
353 compiler with the command \(cq\&distcc\(cq\&\&.
|
|
354 .PP
|
|
355 .SH "SHARING A CACHE"
|
|
356
|
|
357 .PP
|
|
358 A group of developers can increase the cache hit rate by sharing a
|
|
359 cache directory\&. The hard links however cause unwanted side effects,
|
|
360 as all links to a cached file share the file\(cq\&s modification timestamp\&.
|
|
361 This results in false dependencies to be triggered by timestamp\-based
|
|
362 build systems whenever another user links to an existing
|
|
363 file\&. Typically, users will see that their libraries and binaries are
|
|
364 relinked without reason\&. To share a cache without side effects, the
|
|
365 following conditions need to be met:
|
|
366 .PP
|
|
367 .IP o
|
|
368 Use the same \fBCCACHE_DIR\fP environment variable setting
|
|
369 .IP o
|
|
370 Unset the \fBCCACHE_HARDLINK\fP environment variable
|
|
371 .IP o
|
|
372 Make sure everyone sets the CCACHE_UMASK environment variable
|
|
373 to 002, this ensures that cached files are accessible to everyone in
|
|
374 the group\&.
|
|
375 .IP o
|
|
376 Make sure that all users have write permission in the entire
|
|
377 cache directory (and that you trust all users of the shared cache)\&.
|
|
378 .IP o
|
|
379 Make sure that the setgid bit is set on all directories in the
|
|
380 cache\&. This tells the filesystem to inherit group ownership for new
|
|
381 directories\&. The command \(dq\&chmod g+s `find $CCACHE_DIR \-type d`\(dq\& might
|
|
382 be useful for this\&.
|
|
383 .IP o
|
|
384 Set \fBCCACHE_NOCOMPRESS\fP for all users, if there are users with
|
|
385 versions of ccache that do not support compression\&.
|
|
386
|
|
387 .PP
|
|
388 .SH "HISTORY"
|
|
389
|
|
390 .PP
|
|
391 ccache was inspired by the compilercache shell script script written
|
|
392 by Erik Thiele and I would like to thank him for an excellent piece of
|
|
393 work\&. See
|
|
394 http://www\&.erikyyy\&.de/compilercache/
|
|
395 for the Erik\(cq\&s scripts\&.
|
|
396 ccache\-swig is a port of the original ccache with support added for use
|
|
397 with SWIG\&.
|
|
398 .PP
|
|
399 I wrote ccache because I wanted to get a bit more speed out of a
|
|
400 compiler cache and I wanted to remove some of the limitations of the
|
|
401 shell\-script version\&.
|
|
402 .PP
|
|
403 .SH "DIFFERENCES FROM COMPILERCACHE"
|
|
404
|
|
405 .PP
|
|
406 The biggest differences between Erik\(cq\&s compilercache script and ccache
|
|
407 are:
|
|
408 .IP o
|
|
409 ccache is written in C, which makes it a bit faster (calling out to
|
|
410 external programs is mostly what slowed down the scripts)\&.
|
|
411 .IP o
|
|
412 ccache can automatically find the real compiler
|
|
413 .IP o
|
|
414 ccache keeps statistics on hits/misses
|
|
415 .IP o
|
|
416 ccache can do automatic cache management
|
|
417 .IP o
|
|
418 ccache can cache compiler output that includes warnings\&. In many
|
|
419 cases this gives ccache a much higher cache hit rate\&.
|
|
420 .IP o
|
|
421 ccache can handle a much wider ranger of compiler options
|
|
422 .IP o
|
|
423 ccache avoids a double call to cpp on a cache miss
|
|
424
|
|
425 .PP
|
|
426 .SH "CREDITS"
|
|
427
|
|
428 .PP
|
|
429 Thanks to the following people for their contributions to ccache
|
|
430 .IP o
|
|
431 Erik Thiele for the original compilercache script
|
|
432 .IP o
|
|
433 Luciano Rocha for the idea of compiling the pre\-processor output
|
|
434 to avoid a 2nd cpp pass
|
|
435 .IP o
|
|
436 Paul Russell for many suggestions and the debian packaging
|
|
437
|
|
438 .PP
|
|
439 .SH "AUTHOR"
|
|
440
|
|
441 .PP
|
|
442 ccache was written by Andrew Tridgell
|
|
443 http://samba\&.org/~tridge/\&.
|
|
444 ccache was adapted to create ccache\-swig for use with SWIG by William Fulton\&.
|
|
445 .PP
|
|
446 If you wish to report a problem or make a suggestion then please email
|
|
447 the SWIG developers on the swig\-devel mailing list, see
|
|
448 http://www\&.swig\&.org/mail\&.html
|
|
449 .PP
|
|
450 ccache is released under the GNU General Public License version 2 or
|
|
451 later\&. Please see the file COPYING for license details\&.
|
|
452 .PP
|
|
453
|