distcc

Compile a source file using a compiler like gcc

$ distcc [gcc] -c [path/to/source.c] -o [path/to/output.o]

$ export DISTCC_HOSTS="localhost [ip1 ip2 ...]"

$ make [[-j|--jobs]] [parallel_jobs] CC="distcc [gcc]"

$ distcc --show-hosts

$ distcc --help

$ distcc --version

distcc [OPTION...] [command [arguments...]]

-h, --help
    Show a summary of command-line options and exit.

-v, --version
    Display the distcc version and exit.

-j jobs, --jobs jobs
    Specify the maximum number of concurrent jobs to run across all distcc hosts. This can limit local and remote compilation parallelism.

--show-hosts
    Print the current list of hosts that distcc will use for compilation.

--drop-hosts
    When using host randomization, this option forces distcc to drop hosts from the list that have failed recently.

--scan-hosts
    Scan the current host list to determine their availability and compiler compatibility.

--verbose
    Enable verbose logging, showing more information about distcc's operations, including host selection and file transfers.

--debug
    Enable debug logging, providing even more detailed output for troubleshooting.

--profile
    Enable profiling of distcc's internal operations for performance analysis.

--no-fallback
    Disable falling back to local compilation if a remote host fails or is unavailable. distcc will report an error instead.

--distcc-pump
    Enable 'pump mode,' which sends preprocessed source and header files to remote hosts, potentially speeding up compilation further by reducing local preprocessing.

--no-link
    When acting as a wrapper, ensures that distcc only attempts to compile source files and never to link them remotely.

distcc is a program designed to speed up compilation of C, C++, and Objective-C code by distributing the compilation workload across multiple machines on a network. It acts as a wrapper around your local C/C++ compiler (like gcc or g++). When a build system invokes a compiler, distcc intercepts the call. If the compilation command doesn't require local preprocessing or complex linking, distcc sends the source file to a distccd daemon running on a remote host. The distccd daemon compiles the file on the remote machine and sends the resulting object file back to the original machine. This parallelization significantly reduces build times for large software projects by utilizing idle CPU cycles across a cluster of machines. It requires the distccd daemon to be running on all participating remote hosts and compatible compiler versions across all machines.

Compiler Compatibility: All participating machines must have compilers of the same version and architecture for consistent results.
Network Overhead: For very small source files, the overhead of network transfer can outweigh the benefits of distributed compilation.
Debugging Challenges: Debugging compilation issues can be more complex as the actual compilation happens on a remote machine.
Security: The distccd daemon, by default, listens on the network and can execute arbitrary code (though typically restricted to compilation commands). It should only be used in trusted environments or with proper firewall rules and access control.
Preprocessing: By default, distcc performs preprocessing locally before sending the source code, which can still be a bottleneck. "Pump mode" (--distcc-pump) can mitigate this.
Linking/Archiving: distcc does not distribute linking or archiving operations; these always happen on the local machine.

distcc relies heavily on environment variables for configuration. The most critical is
DISTCC_HOSTS, which specifies a space-separated list of remote hosts (and optional ports or connection types like lzo for compression) that distcc should use. For example:

export DISTCC_HOSTS="localhost remote1.example.com remote2:3632"

Other important variables include
DISTCC_DIR (directory for cache and logs),
DISTCC_JOBS (overrides --jobs), and
DISTCC_VERBOSE (enables verbose output).

To use distcc, you typically prepend its directory to your system's
PATH environment variable, so that when a build system (like
make) invokes
gcc or
g++, it finds distcc first.

export PATH="/usr/lib/distcc/bin:$PATH"

Alternatively, you can configure your build system to explicitly use
distcc gcc as the compiler.

distcc was originally developed by Martin Pool in the early 2000s, with initial versions appearing around 2002. It was created to address the growing need for faster build times in large software projects, leveraging the idle CPU cycles of other machines on a local network. Its design, acting as a simple wrapper around existing compilers, made it easy to integrate into existing build systems without significant modifications. Over the years, it has become a widely adopted tool in open-source development and various Linux environments for accelerating software compilation.

distccd(1), gcc(1), g++(1), make(1), ccache(1)