1. Introduction

"Speed, it seems to me, provides the one genuinely modern pleasure." --- Aldous Huxley

1.1 Overview

distcc is a program to distribute compilation of C or C++ code across several machines on a network. distcc 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 does not require all machines to share a filesystem, have synchronized clocks, or to have the same libraries or header files installed.

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 compiler and assembler as required. The volunteer machines run the distccd daemon which listens on a network socket for requests.

distcc sends the complete preprocessed source code across the network for each job, so all it requires of the volunteer machines is that they be running the distccd daemon, and that they have an appropriate compiler installed.

distcc is designed to be used with GNU make's parallel-build feature (-j). Shipping files across the network takes time, but few cycles on the client machine. Any files that can be built remotely are essentially "for free" in terms of client CPU.

distcc was written by Martin Pool.

distcc was inspired by Andrew Tridgell's ccache program.

If you find distcc useful, please try to complete the survey form in the distribution, or just send an email.

1.2 Licence

distcc and the distcc User Manual are copyright (C) 2002, 2003 by Martin Pool.

distcc is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Permission is granted to copy, distribute and/or modify the distcc User Manual under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

distcc is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License and GNU Free Documentation License along with distcc. If not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA, or see http://www.gnu.org/licenses/.

The author understands the GNU GPL to apply to distcc in the following way: you are allowed to use distcc to compile a non-free program, or to call it from a non-free Make, or to call a non-free compiler. However, you may not distribute a modified version of distcc unless you comply with the terms of the GPL: in particular, giving your users access to the source code and the right to redistribute it, and clearly identifying your changes.

1.3 Security Considerations

distcc's native protocol has no access control or authentication mechanisms, and allows execution of arbitrary commands on the server. It is important that unauthorized people cannot connect to the server.

There are two ways to acheive this: either run distcc only a secure network, or run distcc over SSH.

When distcc is run as a daemon, the --listen and --allow options can be used to restrict access. These controls are only effective if the network prevents address spoofing. A prudent administrator will reinforce the access control options with firewalling rules.

Execution over SSH is somewhat slower, because of the overhead of authentication and encryption. When using distcc over SSH, the distcc daemon should not be run.

1.4 Getting Started

Four straightforward steps are required to install and use distcc:

1. Compile and install the distcc package on the client and volunteer machines.
2. Start the distccd daemon on all volunteer machines.
3. On the client, set the DISTCC_HOSTS environment variable to indicate which volunteer machines to use. For example:

   DISTCC_HOSTS='angry toey:4202 localhost'
   

4. Set the CC variable or edit Makefiles to prefix distcc to calls to the C/C++ compiler. For example:

   distcc gcc -o hello.o -c hello.c
   

1.5 Reporting Bugs

If you think you have found a bug, please check the manual and the TODO file to see if it is a known restriction. If not, please send a clear and detailed report to the mailing list distcc@lists.samba.org. (For a clear and detailed description of "clear and detailed", see Simon Tatham's advice on reporting bugs, http://www.chiark.greenend.org.uk/~sgtatham/bugs.html.)

A good bug report for distcc should include:

1. What you're trying to do. For example: "compile KDE", "use gcc's -MD option".
2. What actually happens. For example: "distcc fails with error 104", "the compilation never completes", "I get error message XXX".
3. The version of distcc you're using (the output of --version on both client and server. If you got it from a distribution rather than building it yourself, then mention that.
4. What other software you're using, in particular the operating system and compiler. For the operating system it's normally enough to give the overall version (FreeBSD CURRENT, RedHat Linux 7.2, ...). For the compiler, use "gcc -version".
5. The exact command you're using to run the compilation. If you're using make, then include the line from its output that runs the compiler.
6. The debug logs from the client and server. On the client, you should set DISTCC_VERBOSE and DISTCC_LOG. On the server, use --verbose and --log-file. If you can, trim the log files to just the invocation that causes trouble. Grepping for a process id can help with this. If the problem is intermittent, then please leave logging running until it recurs and then pull out a smaller section of logs to send.

Please do not obfuscate your logs. The name of a single source file or machine is probably not confidential information, but the confusion introduced by editing logs can be significant.

Please send a problem description to the distcc mailing list, on lists.samba.org. Please don't send mail direct to the author: if you use the list, other people may be able to help you, and the answers are publicly archived.

1.6 Test Suite

distcc has a test suite written in Python using the ComfyChair framework. It does not yet exercise all functionality, but is improving.

To run the test suite, run make check from the distcc source directoy.