From: Joel Rosdahl Date: Tue, 15 Jun 2010 20:32:24 +0000 (+0200) Subject: Various minor improvements of the manual X-Git-Tag: v3.0~17 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=f35a13cdcda4724017f6518255047ad9bee5f4cd;p=thirdparty%2Fccache.git Various minor improvements of the manual --- diff --git a/manual.txt b/manual.txt index f8a5fed3d..52cd144a6 100644 --- a/manual.txt +++ b/manual.txt @@ -87,9 +87,8 @@ OPTIONS ------- These options only apply when you invoke ccache as ``ccache''. When invoked as -a compiler (via a symlink as described in the previous section), none of these -options apply. In that case your normal compiler options apply and you should -refer to the compiler's documentation. +a compiler (via a symlink as described in the previous section), the normal +compiler options apply and you should refer to the compiler's documentation. *-c, --cleanup*:: @@ -205,7 +204,7 @@ cases you won't need any of these as the defaults will be fine. case of a cache miss. This is primarily a debugging option, although it is possible that some unusual compilers will have problems with the intermediate filename extensions used in this optimisation, in which case - this option could allow ccache to be used. + this option could allow ccache to be used anyway. *CCACHE_DIR*:: @@ -219,8 +218,8 @@ cases you won't need any of these as the defaults will be fine. *CCACHE_EXTENSION*:: - Normally ccache tries to automatically determine the extension to use for - intermediate C preprocessor files based on the type of file being compiled. + ccache tries to automatically determine the extension to use for + intermediate preprocessor files based on the type of file being compiled. Unfortunately this sometimes doesn't work, for example when using the ``aCC'' compiler on HP-UX. On systems like this you can use the *CCACHE_EXTENSION* option to override the default. On HP-UX set this @@ -238,25 +237,27 @@ cases you won't need any of these as the defaults will be fine. attempt to use hard links from the cache directory when creating the compiler output rather than using a file copy. Using hard links may be slightly faster in some situations, but can confuse programs like ``make'' - that rely on modification times. Hard links are never made for compressed - cache files. This means that you should not set the *CCACHE_COMPRESS* - variable if you want to use hard links. + that rely on modification times. Another thing to keep in mind is that if + the resulting object file is modified in any way, this corrupts the cached + object file as well. Hard links are never made for compressed cache files. + This means that you should not set the *CCACHE_COMPRESS* variable if you + want to use hard links. *CCACHE_HASHDIR*:: This tells ccache to hash the current working directory when calculating - the hash that is used to distinguish two compiles. This prevents a problem - with the storage of the current working directory in the debug info of a - object file, which can lead ccache to give a cached object file that has - the working directory in the debug info set incorrectly. This option is off - by default as the incorrect setting of this debug info rarely causes + the hash that is used to distinguish two compilations. This prevents a + problem with the storage of the current working directory in the debug info + of a object file, which can lead ccache to give a cached object file that + has the working directory in the debug info set incorrectly. This option is + off by default as the incorrect setting of this debug info rarely causes problems. If you strike problems with GDB not using the correct directory then enable this option. *CCACHE_LOGFILE*:: If you set the *CCACHE_LOGFILE* environment variable then ccache will write - some information on what it is doing to the log. This is useful for + information on what it is doing to the specified file. This is useful for tracking down problems. *CCACHE_NLEVELS*:: @@ -317,7 +318,7 @@ cases you won't need any of these as the defaults will be fine. *CCACHE_TEMPDIR*:: The *CCACHE_TEMPDIR* environment variable specifies where ccache will put - temporary files. The default is *$CCACHE_DIR/tmp*. (Note: In previous + temporary files. The default is *$CCACHE_DIR/tmp*. (*Note*: In previous versions of ccache, *CCACHE_TEMPDIR* had to be on the same filesystem as the *CCACHE_DIR* path, but this requirement has been relaxed.) @@ -339,7 +340,8 @@ cases you won't need any of these as the defaults will be fine. hash, so cached compilations with *CCACHE_UNIFY* set cannot be used when *CCACHE_UNIFY* is not set and vice versa. The reason the unifier is off by default is that it can give incorrect line number information in compiler - warning messages. Enabling the unifier implies turning off the direct mode. + warning messages. *Note*: Enabling the unifier implies turning off the + direct mode. CACHE SIZE MANAGEMENT @@ -347,9 +349,9 @@ CACHE SIZE MANAGEMENT By default ccache has a one gigabyte limit on the total size of files in the cache and no maximum number of files. You can set different limits using the -*-M*/*--max-size* and *-F*/*--max-files* options. Use *ccache -s* to see the -cache size and the currently configured limits (in addition to other various -statistics). +*-M*/*--max-size* and *-F*/*--max-files* options. Use *ccache -s/--show-stats* +to see the cache size and the currently configured limits (in addition to other +various statistics). CACHE COMPRESSION @@ -362,8 +364,8 @@ You can turn on compression by setting the *CCACHE_COMPRESS* environment variable. -HOW IT WORKS ------------- +HOW CCACHE WORKS +---------------- The basic idea is to detect when you are compiling exactly the same code a second time and reuse the previously produced output. The detection is done by @@ -488,7 +490,7 @@ conditions should to be met: * Use the same *CCACHE_DIR* environment variable setting. * Unset the *CCACHE_HARDLINK* environment variable. * Make sure everyone sets the *CCACHE_UMASK* environment variable to 002. This - ensure that cached files are accessible to everyone in the group. + ensures that cached files are accessible to everyone in the group. * Make sure that all users have write permission in the entire cache directory (and that you trust all users of the shared cache). * Make sure that the setgid bit is set on all directories in the cache. This @@ -517,7 +519,7 @@ filesystems), but keep in mind that: benchmarking to see if it's worth it. * ccache hasn't been tested very thoroughly on NFS. -A tip is to set CCACHE_TEMPDIR to a directory on the local host to avoid NFS +A tip is to set *CCACHE_TEMPDIR* to a directory on the local host to avoid NFS traffic for temporary files. @@ -538,12 +540,12 @@ the compiler with the command ``distcc''. BUGS ---- -ccache doesn't handle the GNU Assembler's *.incbin* directive correctly. This -directive can be embedded in the source code inside an *__asm__* statement in -order to include a file verbatim in the object file. If the included file is -changed, ccache doesn't pick up the change since the inclusion isn't done by -the preprocessor. A workaround of this problem is to set *CCACHE_EXTRAFILES* to -the path of the included file. +* ccache doesn't handle the GNU Assembler's *.incbin* directive correctly. This + directive can be embedded in the source code inside an *__asm__* statement in + order to include a file verbatim in the object file. If the included file is + modified, ccache doesn't pick up the change since the inclusion isn't done by + the preprocessor. A workaround of this problem is to set *CCACHE_EXTRAFILES* + to the path of the included file. @@ -568,7 +570,7 @@ improve performance. Since ccache works best when I/O is fast, put the cache directory on a fast storage device if possible. Having lots of free memory so that files in the -cache directory stay in the disk cache is also a good idea. +cache directory stay in the disk cache is also preferrable. A good way of monitoring how well ccache works is to run *ccache -s* before and after your build and then compare the statistics counters. Here are some common @@ -619,13 +621,13 @@ problems and what may be done to increase the hit rate: used in practise, or don't care if ccache produces objects where *\_\_FILE__* is expanded to the wrong path, you can set *CCACHE_SLOPPINESS* to *file_macro*. -* If ``cache miss'' has been incremented even though this wasn't the first - compilation of the same source code, ccache has either detected that - something has changed anyway or a cleanup has been performed (either - explicitly or implicitly when a cache limit has been reached). Some perhaps - unobvious things that may result in a cache miss are usage of *\_\_TIME\__* - or *\_\_DATE__* macros, or use of automatically generated code that contains - a timestamp, build counter or other volatile information. +* If ``cache miss'' has been incremented even though the same code has been + compiled and cached before, ccache has either detected that something has + changed anyway or a cleanup has been performed (either explicitly or + implicitly when a cache limit has been reached). Some perhaps unobvious + things that may result in a cache miss are usage of *\_\_TIME\__* or + *\_\_DATE__* macros, or use of automatically generated code that contains a + timestamp, build counter or other volatile information. * If ``multiple source files'' has been incremented, it's an indication that the compiler has been invoked on several source code files at once. ccache doesn't support that. Compile the source code files separately if possible. @@ -639,9 +641,9 @@ ERRORS WHEN COMPILING WITH CCACHE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If compilation doesn't work with ccache, but it works without it, one possible -reason is that the compiler can't compile the output from the preprocessor -correctly. A workaround that may work is to set *CCACHE_CPP2*. This will make -cache misses slower, though, so it is better to find and fix the root cause. +reason is that the compiler can't compile preprocessed output correctly. A +workaround that may work is to set *CCACHE_CPP2*. This will make cache misses +slower, though, so it is better to find and fix the root cause. CORRUPT OBJECT FILES