Mercurial > mm7

comparison lib/swig/swigwin-2.0.11/CCache/ccache-swig.1 @ 1899:b3009adc0e2f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Adding swig, gitignore, hgignore
author Nomad
date Mon, 21 Oct 2013 10:42:27 +0200
parents
children
comparison
equal deleted inserted replaced
1867:eb580660bbbb 1899:b3009adc0e2f
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