mm7: lib/swig/swigwin-2.0.11/CCache/ccache.yo comparison

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

Adding swig, gitignore, hgignore

author	Nomad
date	Mon, 21 Oct 2013 10:42:27 +0200
parents
children

comparison

equal deleted inserted replaced

-:eb580660bbbb
+:b3009adc0e2f
+whenman(
+COMMENT(html output not great if included when using html2doc)
+manpage(ccache-swig)(1)()()()
+)
+whenhtml(htmlcommand(
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<title>ccache-swig(1) manpage</title>
+<link rel="stylesheet" type="text/css" href="style.css">
+</head>
+<body bgcolor="#ffffff">
+<H1><a name="CCache"></a>Using SWIG with ccache - ccache-swig(1) manpage</H1>
+<!-- INDEX -->
+<div class="sectiontoc">
+<!-- INDEX -->
+))
+manpagename(ccache-swig)(a fast compiler cache)
+whenhtml(htmlcommand(
+ccache-swig - a fast compiler cache
+))
+manpagesynopsis()
+ccache-swig [OPTION]
+ccache-swig <compiler> [COMPILER OPTIONS]
+<compiler> [COMPILER OPTIONS]
+manpagedescription()
+ccache-swig is a compiler cache. It speeds up re-compilation of C/C++/SWIG code
+by caching previous compiles and detecting when the same compile is
+being done again. ccache-swig is ccache plus support for SWIG. ccache
+and ccache-swig are used interchangeably in this document.
+manpagesection(OPTIONS SUMMARY)
+Here is a summary of the options to ccache-swig.
+verb(
+-s                      show statistics summary
+-z                      zero statistics
+-c                      run a cache cleanup
+-C                      clear the cache completely
+-F <n>                  set maximum files in cache
+-M <n>                  set maximum size of cache (use G, M or K)
+-h                      this help page
+-V                      print version number
+)
+manpageoptions()
+These options only apply when you invoke ccache as "ccache-swig". When
+invoked as a compiler none of these options apply. In that case your
+normal compiler options apply and you should refer to your compilers
+documentation.
+startdit()
+dit(bf(-h)) Print a options summary page
+dit(bf(-s)) Print the current statistics summary for the cache. The
+statistics are stored spread across the subdirectories of the
+cache. Using "ccache-swig -s" adds up the statistics across all
+subdirectories and prints the totals.
+dit(bf(-z)) Zero the cache statistics.
+dit(bf(-V)) Print the ccache version number
+dit(bf(-c)) Clean the cache and re-calculate the cache file count and
+size totals. Normally the -c option should not be necessary as ccache
+keeps the cache below the specified limits at runtime and keeps
+statistics up to date on each compile. This option is mostly useful
+if you manually modify the cache contents or believe that the cache
+size statistics may be inaccurate.
+dit(bf(-C)) Clear the entire cache, removing all cached files.
+dit(bf(-F <maxfiles>)) This sets the maximum number of files allowed in
+the cache. The value is stored inside the cache directory and applies
+to all future compiles. Due to the way the value is stored the actual
+value used is always rounded down to the nearest multiple of 16.
+dit(bf(-M <maxsize>)) This sets the maximum cache size. You can specify
+a value in gigabytes, megabytes or kilobytes by appending a G, M or K
+to the value. The default is gigabytes. The actual value stored is
+rounded down to the nearest multiple of 16 kilobytes.
+enddit()
+manpagesection(INSTALLATION)
+There are two ways to use ccache. You can either prefix your compile
+commands with "ccache-swig" or you can create a symbolic link between
+ccache-swig and the names of your compilers. The first method is most
+convenient if you just want to try out ccache or wish to use it for
+some specific projects. The second method is most useful for when you
+wish to use ccache for all your compiles.
+To install for usage by the first method just copy ccache-swig to somewhere
+in your path.
+To install for the second method do something like this:
+verb(
+cp ccache-swig /usr/local/bin/
+ln -s /usr/local/bin/ccache-swig /usr/local/bin/gcc
+ln -s /usr/local/bin/ccache-swig /usr/local/bin/g++
+ln -s /usr/local/bin/ccache-swig /usr/local/bin/cc
+ln -s /usr/local/bin/ccache-swig /usr/local/bin/swig
+)
+This will work as long as /usr/local/bin comes before the path to gcc
+(which is usually in /usr/bin). After installing you may wish to run
+"which gcc" to make sure that the correct link is being used.
+Note! Do not use a hard link, use a symbolic link. A hardlink will
+cause "interesting" problems.
+manpagesection(EXTRA OPTIONS)
+When run as a compiler front end ccache usually just takes the same
+command line options as the compiler you are using. The only exception
+to this is the option '--ccache-skip'. That option can be used to tell
+ccache that the next option is definitely not a input filename, and
+should be passed along to the compiler as-is.
+The reason this can be important is that ccache does need to parse the
+command line and determine what is an input filename and what is a
+compiler option, as it needs the input filename to determine the name
+of the resulting object file (among other things). The heuristic
+ccache uses in this parse is that any string on the command line that
+exists as a file is treated as an input file name (usually a C
+file). By using --ccache-skip you can force an option to not be
+treated as an input file name and instead be passed along to the
+compiler as a command line option.
+manpagesection(ENVIRONMENT VARIABLES)
+ccache uses a number of environment variables to control operation. In
+most cases you won't need any of these as the defaults will be fine.
+startdit()
+dit(bf(CCACHE_DIR)) the CCACHE_DIR environment variable specifies
+where ccache will keep its cached compiler output. The default is
+"$HOME/.ccache".
+dit(bf(CCACHE_TEMPDIR)) the CCACHE_TEMPDIR environment variable specifies
+where ccache will put temporary files. The default is the same as
+CCACHE_DIR. Note that the CCACHE_TEMPDIR path must be on the same
+filesystem as the CCACHE_DIR path, so that renames of files between
+the two directories can work.
+dit(bf(CCACHE_LOGFILE)) If you set the CCACHE_LOGFILE environment
+variable then ccache will write some log information on cache hits
+and misses in that file. This is useful for tracking down problems.
+dit(bf(CCACHE_VERBOSE)) If you set the CCACHE_VERBOSE environment
+variable then ccache will display on stdout all the compiler invocations
+that it makes. This can useful for debugging unexpected problems.
+dit(bf(CCACHE_PATH)) You can optionally set CCACHE_PATH to a colon
+separated path where ccache will look for the real compilers. If you
+don't do this then ccache will look for the first executable matching
+the compiler name in the normal PATH that isn't a symbolic link to
+ccache itself.
+dit(bf(CCACHE_CC)) You can optionally set CCACHE_CC to force the name
+of the compiler to use. If you don't do this then ccache works it out
+from the command line.
+dit(bf(CCACHE_PREFIX)) This option adds a prefix to the command line
+that ccache runs when invoking the compiler. Also see the section
+below on using ccache with distcc.
+dit(bf(CCACHE_DISABLE)) If you set the environment variable
+CCACHE_DISABLE then ccache will just call the real compiler,
+bypassing the cache completely.
+dit(bf(CCACHE_READONLY)) the CCACHE_READONLY environment variable
+tells ccache to attempt to use existing cached object files, but not
+to try to add anything new to the cache. If you are using this because
+your CCACHE_DIR is read-only, then you may find that you also need to
+set CCACHE_TEMPDIR as otherwise ccache will fail to create the
+temporary files.
+dit(bf(CCACHE_CPP2)) If you set the environment variable CCACHE_CPP2
+then ccache will not use the optimisation of avoiding the 2nd call to
+the pre-processor by compiling the pre-processed output that was used
+for finding the hash in the 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.
+dit(bf(CCACHE_NOCOMPRESS)) If you set the environment variable
+CCACHE_NOCOMPRESS then there is no compression used on files that go
+into the cache. However, this setting has no effect on how files are
+retrieved from the cache, compressed results will still be usable.
+dit(bf(CCACHE_NOSTATS)) If you set the environment variable
+CCACHE_NOSTATS then ccache will not update the statistics files on
+each compile.
+dit(bf(CCACHE_NLEVELS)) The environment variable CCACHE_NLEVELS allows
+you to choose the number of levels of hash in the cache directory. The
+default is 2. The minimum is 1 and the maximum is 8.
+dit(bf(CCACHE_HARDLINK)) If you set the environment variable
+CCACHE_HARDLINK then ccache will attempt to use hard links from the
+cache directory when creating the compiler output rather than using a
+file copy. Using hard links is faster, but can confuse programs like
+'make' that rely on modification times. Hard links are never made for
+compressed cache files.
+dit(bf(CCACHE_RECACHE)) This forces ccache to not use any cached
+results, even if it finds them. New results are still cached, but
+existing cache entries are ignored.
+dit(bf(CCACHE_UMASK)) This sets the umask for ccache and all child
+processes (such as the compiler). This is mostly useful when you wish
+to share your cache with other users. Note that this also affects the
+file permissions set on the object files created from your
+compilations.
+dit(bf(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 problems. If you
+strike problems with gdb not using the correct directory then enable
+this option.
+dit(bf(CCACHE_UNIFY)) If you set the environment variable CCACHE_UNIFY
+then ccache will use the C/C++ unifier when hashing the pre-processor
+output if -g is not used in the compile. The unifier is slower than a
+normal hash, so setting this environment variable loses a little bit
+of speed, but it means that ccache can take advantage of not
+recompiling when the changes to the source code consist of
+reformatting only. Note that using CCACHE_UNIFY changes the hash, so
+cached compiles 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.
+dit(bf(CCACHE_EXTENSION)) Normally ccache tries to automatically
+determine the extension to use for intermediate C pre-processor 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 environment variable to "i" if you use
+the aCC compiler.
+dit(bf(CCACHE_STRIPC)) If you set the environment variable
+CCACHE_STRIPC then ccache will strip the -c option when invoking
+the preprocessor. This option is primarily for the Sun Workshop
+C++ compiler as without this option an unwarranted warning is displayed:
+CC: Warning: "-E" redefines product from "object" to "source (stdout)"
+when -E and -c is used together.
+dit(bf(CCACHE_SWIG)) When using SWIG as the compiler and it does not
+have 'swig' in the executable name, then the CCACHE_SWIG environment
+variable needs to be set in order for ccache to work correctly with
+SWIG. The use of CCACHE_CPP2 is also recommended for SWIG due to some
+preprocessor quirks, however, use of CCACHE_CPP2 can often be skipped
+-- check your generated code with and without this option set. Known
+problems are using preprocessor directives within %inline blocks and
+the use of '#pragma SWIG'.
+enddit()
+manpagesection(CACHE SIZE MANAGEMENT)
+By default ccache has a one gigabyte limit on the cache size and no
+maximum number of files. You can set a different limit using the
+"ccache -M" and "ccache -F" options, which set the size and number of
+files limits.
+When these limits are reached ccache will reduce the cache to 20%
+below the numbers you specified in order to avoid doing the cache
+clean operation too often.
+manpagesection(CACHE COMPRESSION)
+By default on most platforms ccache will compress all files it puts
+into the cache
+using the zlib compression. While this involves a negligible
+performance slowdown, it significantly increases the number of files
+that fit in the cache. You can turn off compression setting the
+CCACHE_NOCOMPRESS environment variable.
+manpagesection(HOW IT WORKS)
+The basic idea is to detect when you are compiling exactly the same
+code a 2nd time and use the previously compiled output. You detect
+that it is the same code by forming a hash of:
+itemization(
+it() the pre-processor output from running the compiler with -E
+it() the command line options
+it() the real compilers size and modification time
+it() any stderr output generated by the compiler
+)
+These are hashed using md4 (a strong hash) and a cache file is formed
+based on that hash result. When the same compilation is done a second
+time ccache is able to supply the correct compiler output (including
+all warnings etc) from the cache.
+ccache has been carefully written to always produce exactly the same
+compiler output that you would get without the cache. If you ever
+discover a case where ccache changes the output of your compiler then
+please let me know.
+manpagesection(USING CCACHE WITH DISTCC)
+distcc is a very useful program for distributing compilation across a
+range of compiler servers. It is often useful to combine distcc with
+ccache, so that compiles that are done are sped up by distcc, but that
+ccache avoids the compile completely where possible.
+To use distcc with ccache I recommend using the CCACHE_PREFIX
+option. You just need to set the environment variable CCACHE_PREFIX to
+'distcc' and ccache will prefix the command line used with the
+compiler with the command 'distcc'.
+manpagesection(SHARING A CACHE)
+A group of developers can increase the cache hit rate by sharing a
+cache directory.  The hard links however cause unwanted side effects,
+as all links to a cached file share the file's modification timestamp.
+This results in false dependencies to be triggered by timestamp-based
+build systems whenever another user links to an existing
+file. Typically, users will see that their libraries and binaries are
+relinked without reason.  To share a cache without side effects, the
+following conditions need to be met:
+itemization(
+it() Use the same bf(CCACHE_DIR) environment variable setting
+it() Unset the bf(CCACHE_HARDLINK) environment variable
+it() Make sure everyone sets the CCACHE_UMASK environment variable
+to 002, this ensures that cached files are accessible to everyone in
+the group.
+it() Make sure that all users have write permission in the entire
+cache directory (and that you trust all users of the shared cache).
+it() Make sure that the setgid bit is set on all directories in the
+cache. This tells the filesystem to inherit group ownership for new
+directories. The command "chmod g+s `find $CCACHE_DIR -type d`" might
+be useful for this.
+it() Set bf(CCACHE_NOCOMPRESS) for all users, if there are users with
+versions of ccache that do not support compression.
+)
+manpagesection(HISTORY)
+ccache was inspired by the compilercache shell script script written
+by Erik Thiele and I would like to thank him for an excellent piece of
+work. See
+url(http://www.erikyyy.de/compilercache/)(http://www.erikyyy.de/compilercache/)
+for the Erik's scripts.
+ccache-swig is a port of the original ccache with support added for use
+with SWIG.
+I wrote ccache because I wanted to get a bit more speed out of a
+compiler cache and I wanted to remove some of the limitations of the
+shell-script version.
+manpagesection(DIFFERENCES FROM COMPILERCACHE)
+The biggest differences between Erik's compilercache script and ccache
+are:
+itemization(
+it() ccache is written in C, which makes it a bit faster (calling out to
+external programs is mostly what slowed down the scripts).
+it() ccache can automatically find the real compiler
+it() ccache keeps statistics on hits/misses
+it() ccache can do automatic cache management
+it() ccache can cache compiler output that includes warnings. In many
+cases this gives ccache a much higher cache hit rate.
+it() ccache can handle a much wider ranger of compiler options
+it() ccache avoids a double call to cpp on a cache miss
+)
+manpagesection(CREDITS)
+Thanks to the following people for their contributions to ccache
+itemization(
+it() Erik Thiele for the original compilercache script
+it() Luciano Rocha for the idea of compiling the pre-processor output
+to avoid a 2nd cpp pass
+it() Paul Russell for many suggestions and the debian packaging
+)
+manpageauthor()
+ccache was written by Andrew Tridgell
+url(http://samba.org/~tridge/)(http://samba.org/~tridge/).
+ccache was adapted to create ccache-swig for use with SWIG by William Fulton.
+If you wish to report a problem or make a suggestion then please email
+the SWIG developers on the swig-devel mailing list, see
+url(http://www.swig.org/mail.html)(http://www.swig.org/mail.html)
+ccache is released under the GNU General Public License version 2 or
+later. Please see the file COPYING for license details.
+whenhtml(htmlcommand(
+</body>
+</html>
+))

Mercurial > mm7

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