ccache-swig man page on Scientific

Man page or keyword search:  
man Server   26626 pages
apropos Keyword Search (all sections)
Output format
Scientific logo
[printable version]

ccache-swig(1)							ccache-swig(1)

NAME
       ccache-swig - a fast compiler cache

SYNOPSIS
       ccache-swig [OPTION]

       ccache-swig <compiler> [COMPILER OPTIONS]

       <compiler> [COMPILER OPTIONS]

DESCRIPTION
       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 docu‐
       ment.

OPTIONS SUMMARY
       Here is a summary of the options to ccache-swig.

       -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

OPTIONS
       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.

       -h     Print a options summary page

       -s     Print the current statistics summary for the cache. The  statis‐
	      tics  are	 stored spread across the subdirectories of the cache.
	      Using "ccache-swig -s" adds up the statistics across all	subdi‐
	      rectories and prints the totals.

       -z     Zero the cache statistics.

       -V     Print the ccache version number

       -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.

       -C     Clear the entire cache, removing all cached files.

       -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.

       -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.

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 some‐
       where in your path.

       To install for the second method do something like this:

	 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.

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 com‐
       piler  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.

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.

       CCACHE_DIR
	      the CCACHE_DIR environment variable specifies where ccache  will
	      keep its cached compiler output. The default is "$HOME/.ccache".

       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.

       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.

       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.

       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.

       CCACHE_CC
	      You  can	optionally set CCACHE_CC to force the name of the com‐
	      piler to use. If you don't do this then ccache works it out from
	      the command line.

       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.

       CCACHE_DISABLE
	      If  you  set the environment variable CCACHE_DISABLE then ccache
	      will just call the  real	compiler,  bypassing  the  cache  com‐
	      pletely.

       CCACHE_READONLY
	      the CCACHE_READONLY environment variable tells ccache to attempt
	      to use existing cached object files, but not to try to add  any‐
	      thing  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.

       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 pri‐
	      marily a debugging option, although it  is  possible  that  some
	      unusual compilers will have problems with the intermediate file‐
	      name extensions used in this optimisation, in  which  case  this
	      option could allow ccache to be used.

       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.

       CCACHE_NOSTATS
	      If you set the environment variable CCACHE_NOSTATS  then	ccache
	      will not update the statistics files on each compile.

       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.

       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.

       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.

       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 compila‐
	      tions.

       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	direc‐
	      tory  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_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 uni‐
	      fier is off by default is that it can give incorrect line number
	      information in compiler warning messages.

       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 sys‐
	      tems like this you can use the CCACHE_EXTENSION option to	 over‐
	      ride  the default. On HP-UX set this environment variable to "i"
	      if you use the aCC compiler.

       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.

       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'.

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 oper‐
       ation too often.

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 negli‐
       gible  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.

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:

       o      the pre-processor output from running the compiler with -E

       o      the command line options

       o      the real compilers size and modification time

       o      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 dis‐
       cover a case where ccache changes the  output  of  your	compiler  then
       please let me know.

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'.

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. Typi‐
       cally, 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:

       o      Use the same CCACHE_DIR environment variable setting

       o      Unset the CCACHE_HARDLINK environment variable

       o      Make sure everyone sets the CCACHE_UMASK environment variable to
	      002,  this  ensures that cached files are accessible to everyone
	      in the group.

       o      Make sure that all users have write  permission  in  the	entire
	      cache  directory	(and  that  you	 trust all users of the shared
	      cache).

       o      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.

       o      Set  CCACHE_NOCOMPRESS  for  all	users, if there are users with
	      versions of ccache that do not support compression.

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 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  com‐
       piler  cache  and  I  wanted  to	 remove some of the limitations of the
       shell-script version.

DIFFERENCES FROM COMPILERCACHE
       The biggest differences between Erik's compilercache script and	ccache
       are:

       o      ccache is written in C, which makes it a bit faster (calling out
	      to external programs is mostly what slowed down the scripts).

       o      ccache can automatically find the real compiler

       o      ccache keeps statistics on hits/misses

       o      ccache can do automatic cache management

       o      ccache can cache compiler output that includes warnings. In many
	      cases this gives ccache a much higher cache hit rate.

       o      ccache can handle a much wider ranger of compiler options

       o      ccache avoids a double call to cpp on a cache miss

CREDITS
       Thanks to the following people for their contributions to ccache

       o      Erik Thiele for the original compilercache script

       o      Luciano Rocha for the idea of compiling the pre-processor output
	      to avoid a 2nd cpp pass

       o      Paul Russell for many suggestions and the debian packaging

AUTHOR
       ccache  was  written  by	 Andrew	 Tridgell   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
       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.

								ccache-swig(1)
[top]

List of man pages available for Scientific

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net