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