/ 
Make-Cache-1.050
/ objcache

NAME

objcache - Cache results of running gcc/ghs on argument list

SYNOPSIS

objcache --read --write g++ <normal_gcc/ghs_command_line>

DESCRIPTION

objcache is called with a full g++ or cxppc command line. It acts as if the compiler is called directly with all arguments.

With --read and --write, objcache returns almost instantly when the same source is recompiled. It does this by caching a hash of the preprocessed gcc source files. If gcc is invoked with the same inputs, the cache returns the object files without needing to invoke the compiler.

DETAILS

GCC is run in preprocessor mode to create a single source file. This source file is then hashed. Likewise any compiler switches are hashed, but with any define related switches (-Dfoo -Dfoo=value -Ufoo) stripped out as they are represented in the preprocessor output. (This increases cache hits when there are many #ifdef controlled compiles going on.)

The source hash is then looked up in the cache. If it hits, the objects are copied from the cache into the local directory, and objcache exits. The files on disk will thus look like the compile finished, but much faster.

If the source hash misses, the compiler is invoked. The output of the compiler is written to the cache. objcache also determines how long the compile took (for informing the user), and may run the compile on another machine.

EXAMPLE MAKEFILE

This example will use the cache, and compile on all machines in the network with the "gcc" class. It's also written to work if the objcache is not installed. This uses the Schedule::Load package to determine what machines have free resources in the network.

  ifeq ($(SLCHOOSED_HOST),)
   export OBJCACHE :=
  else
   export OBJCACHE_HOSTS := $(shell rschedule --class class_gcc hostnames)
   export OBJCACHE_JOBS := -j $(shell objcache --jobs "$(OBJCACHE_HOSTS)")
   export OBJCACHE := @objcache --read --write
  endif

  %.o:	%.cpp
	$(OBJCACHE) ${CXX} ${CPPFLAGS} -c $<

If you are using a submake (where one makefile calls another), you may place the export lines in the top level makefile. Then, spawn the submakes using the number of jobs calculated by objcache --jobs:

top_level_target:
      $(MAKE) $(OBJCACHE_JOBS) top_level_target

ARGUMENTS

--help

Displays this message and program version and exits.

--clean

Remove any files older than one day from the cache.

--completed <seconds>

Print a completion message when a compile completes if the compile took more than the specified number of seconds.

--distcc

Use the distcc program to distribute compile jobs, rather than logging in remotely and executing the compilation command.

--gcc

Ignore the compiler name specified on the command line, and assume the compiler has the same command line options as GCC.

--dump

For debugging, show the state of the cache.

--dumprm

Show the state of the cache, with the command line command needed to flush that entry.

--icecream

Use the icecream program to distribute compile jobs, rather than logging in remotely and executing the compilation command.

--jobs

Return a suggestion for the number of parallel make jobs to be run. This is the contents of the OBJCACHE_JOBS variable, or if not set, a count of the number of hosts listed in the OBJCACHE_HOSTS variable. With a argument, use the argument instead of the OBJCACHE_HOSTS variable.

--link

When a object file hits, create a symlink to the master version, rather than copying. This may result in better performance when there is a single user, though worse performance when builds are local and the repository on a global disk.

--okdir

Specify a directory that should avoid the strange directory warning. Use this with caution, as absolute paths may greatly decrease hit rates between different users.

--read

Read the cache and use cached objects if they exist.

--noruntime

Disable caching the execution time of the compile, nor show the runtime when compling.

--version

Displays program version and exits.

--vmemlimit <gbytes>

Limit the GCC process to the specified number of gigabytes of memory space. Note this will only apply to local compiles, not those sent across distcc or icecream.

--wrapper

Interpret the first program on the command line as a wrapper script, and get the real compiler name from the next non-switch argument. Useful for applications like purify.

--write

Write the cache with compiled objects.

ENVIRONMENT

OBJCACHE_DIR

Specifies the directory containing the cache. Defaults to /usr/local/common/lib/objcache. Under this is a directory based on a hash of the target name. Under that is a directory based on a hash of the source file and compile switches, then finally .digest and .t# directory entries for each hash and target file. You can remove all of the files in this directory to empty the cache.

OBJCACHE_RUNTIME_DIR

Specifies the directory containing the runtime database. Defaults to /usr/local/common/lib/runtime.

OBJCACHE_HOSTS

Specifies a comma separated list of hosts to run compiles on. When a compile needs to be run, objcache will pick a random host from this list, then remote shell to run the compile. This allows a "make -j" run to use many machines in parallel. Defaults to not remote shell.

OBJCACHE_HOSTS_DETERMINANT

Specifies a shell command to run which returns OBJCACHE_HOSTS. This is not used by objcache itself, but by convention in higher level Makefiles.

OBJCACHE_JOBS

Specifies the forced return value for objcache --jobs. If there is a leading -j, it will be stripped.

OBJCACHE_NFS_WAIT

Specifies the number of seconds to wait for a generated file written on one machine to become visible on another machine, before signalling an error. Defaults to 4 seconds, but may need to be increased on slow networks.

OBJCACHE_RSH

Specifies the program name to use for remote shells. Defaults to rsh.

DISTRIBUTION

The latest version is available from CPAN and from http://www.veripool.org/.

Copyright 2000-2009 by Wilson Snyder. This package is free software; you can redistribute it and/or modify it under the terms of either the GNU Lesser General Public License or the Perl Artistic License.

AUTHORS

Wilson Snyder <wsnyder@wsnyder.org>

SEE ALSO

Make::Cache