distcc(1)

NAME
distcc - distributed C compiler

SYNOPSIS
distcc gcc [OPTIONS] -o OBJECT-c SOURCE

DESCRIPTION
distcc allows compilation of C code to be distributed across several machines on a network. ccache should always generate the same results as a local compile, is simple to install and use, and is often significantly faster than a local compile.

Unlike other distributed build systems, distcc distcc does not require all machines to share a filesystem, or to have the same libraries or header files installed. distcc sends the complete preprocessed source code across the network for each job.

Compilation is centrally controlled by a client machine, which is typically the developer's workstation or laptop. The distcc client runs on this machine, as does make, the preprocessor, the linker, and other stages of the build process. Any number of volunteer machines help the client to build the program, by running the C compiler and assembler as required. The volunteer machines run the distccd daemon which listens on a network socket for connections.

Four straightforward steps are required to install distcc:

1.  Compile and install the distcc package on all machines.

2.  Start the distccd(1) daemon on all volunteer machines.

3.  On the client, set the DISTCC_HOSTS environment variable to indicate which volunteer machines to use.

4.  Set the $CC variable or edit Makefiles to prefix distcc to calls to the C compiler.

distcc is prefixed to C compiler command lines and acts as a wrapper to invoke the compiler either on the local client machine, or on a remote volunteer host.

Standard Makefiles, including those using the GNU autoconf/automake system use the variable as the name of the compiler to run. In most cases, it is sufficient to just override this variable, either from the command line, or perhaps from your login script if you wish to use distcc for all compilation. For example:

    make CC='distcc gcc' all

NOTE: You cannot just set CC=distcc, because distcc needs to know the name of the real compiler.

distcc works well with the ccache(1) tool for caching compilation results. To use the two of them together, simply set

    CC='ccache distcc gcc'

distcc never transmits file times across the network or modifies them, and so should not care whether the clocks on the client and volunteer machines are synchronized or not. When an object file is received onto the client, its modification time will be the current time on the client machine.

OPTIONS
distcc takes no options of its own. All arguments are interpreted as a compiler command line, of which the first element should be the name of the compiler. If invoked with no arguments, distcc prints a summary usage message.

ENVIRONMENT VARIABLES
NOTE: Some versions of make(1) do not export Make variables as environment variables by default, and also that assignments to variables within the Makefile may override their definitions in the environment. The most reliable method seems to be to set DISTCC_ variables in the environment of Make, and to set CC on the right-hand-side of the Make command line. For example:

   $ DISTCC_HOSTS='localhost wistful toey'
   $ export DISTCC_HOSTS
   $ make CC='distcc gcc' all

DISTCC_HOSTS
    Space-separated list of compile volunteers.

DISTCC_VERBOSE
    If set, distcc produces explanatory messages on the standard error stream. This can be helpful in debugging problems. Bug reports should include verbose output.

FILES
distcc stores working files in a subdirectory of /tmp. These include synchronization files, and compiler input/output temporary files. Temporary files should normally be cleaned up when the program exits. If distcc misbehaves, these files may be useful in tracking down the cause. Any that remain can be removed by the system's temporary file reaper.

HOW IT WORKS

DIAGNOSTICS
distcc prints a message when it runs a command locally or remotely. For more information, set $DISTCC_VERBOSE and look at the server's log file.

By default, distcc prints diagnostic messages to stderr. Sometimes these are too intrusive into the output of the regular compiler, and so they may be selectively redirected by setting the $DISTCC_LOG environment variable to a filename.

The exit code of distcc is normally that of the compiler: zero for successful compilation and non-zero otherwise. Error messages from local or remote compilers are passed through to diagnostic output on the client.

If distcc is unable to contact the selected volunteer machine, it will try to run the compiler locally on the client. If that fails, distcc will return exit code 1.

BUGS

There are no known cases where distcc will produce incorrect code, but they may exist.

Jobs are distributed randomly, which is adequate but not very clever.

distcc waits for too long on unreachable hosts.

There is no way to specify a non-default TCP port.

Attackers can cause arbitrary damage if they can connect to the volunteer's port, or impersonate a volunteer. distcc should therefore only be used on trusted networks. Running over ssh(1) or some other security mechanism might be possible, but would be slow.

4200 is not a registered port; I just picked it out of my hat.

distcc probably has portability bugs on systems other than GNU/Linux, but they should be accidental, not fundamental.

If a Makefile contains race conditions that make it unsafe for parallel execution then distcc will lose in the same way as a local compiler. Limitations of the Make language mark it hard to write some parallel rules correctly.

If the Makefile hardcodes the name of the compiler rather than using $(CC) then it may have to be updated.

distcc could easily handle C++ programs, but it does not yet recognize their file extensions.

There are probably some valid compiler command lines that distcc will fail to understand, and which will therefore be run locally rather than distributed.

CREDITS
distcc was inspired by Andrew Tridgell's ccache program.

AUTHOR
distcc was written by Martin Pool <http://sourcefrog.net/mbp/>

LICENCE
You are free to use distcc. It may be copied, modified or distributed only under the terms of the GNU General Public Licence version 2 or later. A copy of the GPL is included in the file COPYING.

SEE ALSO
distccd(1), ccache(1), gcc(1), make(1) http://ccache.samba.org/ http://distcc.samba.org/