/ 
Make-Cache-1.040
/ 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 then one day from the cache.

--distcc

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

--icecream

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

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

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

--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_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.com/.

Copyright 2000-2006 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