/ 
Make-Cache-1.000
/ obj_cache

NAME

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

SYNOPSIS

obj_cache --read --write g++ normal_gcc/ghs_command_line

DESCRIPTION

obj_cache 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, obj_cache returns almost instantly when the same source is recompled. 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 obj_cache 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. Obj_cache 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 obj_cache is not installed. This uses the Schedule::Load package to determine what machines have free resources in the network.

  ifeq ($(SLCHOOSED_HOST),)
   OBJCACHE := 
  else
   OBJCACHE := @obj_cache --read --write
   OBJ_CACHE_HOSTS := $(shell rschedule --class class_gcc hostnames)
   export OBJ_CACHE_HOSTS
  endif

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

ARGUMENTS

--help

Displays this message and program version and exits.

--clean

Remove any files older then one day from the cache.

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

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

OBJ_CACHE_DIR

Specifies the directory containing the cache. Defaults to /usr/local/common/lib/obj_cache. 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.

OBJ_CACHE_HOSTS

Specifies a comma seperated list of hosts to run compiles on. When a compile needs to be run, obj_cache 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.

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

SEE ALSO

Make::Cache::Gcc

AUTHORS

Wilson Snyder <wsnyder@wsnyder.org>