Distcc

Requirements across all hosts[edit | edit source]

In order to use distcc, all of the computers on the network need to have the same GCC versions. For example, mixing 3.3.x (where the x varies) is okay, but mixing 3.3.x with 3.2.x may result in compilation errors or runtime errors.

Verify that all systems use the same version of binutils (eselect binutils list) or many packages will fail linking with various errors like text relocation.

USE flags[edit | edit source]

Emerge[edit | edit source]

Distcc ships with a graphical monitor to monitor tasks that a computer is sending away for compilation. This monitor is enabled when the gtk USE flag is set.

After configuring the USE setting, install the sys-devel/distcc package:

Service[edit | edit source]

In order to have distccd started automatically follow the next set of instructions.

DISTCCD_OPTS="--port 3632 --log-level notice --log-file /var/log/distccd.log -N 15 --allow 192.168.0.4 --allow 192.168.0.5"

Environment="ALLOWED_SERVERS=192.168.1.0/24"

Specifying participating hosts[edit | edit source]

Use the distcc-config command to set the list of hosts.

The following is an example list of host definitions. In most cases, variants of lines 1 and 2 suffice. The latter uses the /limit syntax to inform distcc about the maximum amount of jobs to be launched on this node. More information about the syntax used in lines 3 and 4 can be found in the distcc manual page.

192.168.0.1          192.168.0.2                       192.168.0.3
192.168.0.1/2        192.168.0.2                       192.168.0.3/10
192.168.0.1:4000/2   192.168.0.2/1                     192.168.0.3:3632/4
@192.168.0.1         @192.168.0.2:/usr/bin/distccd     192.168.0.3

There are also several other methods of setting up hosts. See the distcc man page (man distcc) for more details.

If compilations should also occur on the local machine, put localhost in the hosts list. Conversely if the local machine is not to be used to compile, omit it from the hosts list. On a slow machine using localhost may actually slow things down. Make sure to test the settings for performance.

Let's configure distcc to use the hosts mentioned on the first line in the example:

Distcc also supports a pump mode, by invoking the pump command. This may significantly reduce build time when multiple files are compiled in parallel. It caches preprocessed headers on the server side and, as a result, gets rid of repeated uploading and preprocessing of these header files.

To configure a host for pump mode, add the ,cpp,lzo suffix to the hosts definitions. Pump mode requires both cpp and lzo flags (regardless of the files being C or C++).

Hosts also need to be in:

192.168.0.1
192.168.0.2
192.168.0.3

With Portage[edit | edit source]

Setting up Portage to use distcc is easy. It is a matter of enabling the distcc feature, and setting a decent value for the number of simultaneous build jobs (as distcc increases the amount of build resources).

Set the MAKEOPTS variable and FEATURES variable as shown below.

A common strategy is to

• set the value of N to twice the number of total (local + remote) CPU cores + 1, and
• set the value of M to the number of local CPU cores

The use of -lM in the MAKEOPTS variable will prevent spawning too many tasks when some of the distcc cluster hosts are unavailable (increasing the amount of simultaneous jobs on the other systems) or when an ebuild is configured to disallow remote builds (such as with gcc). This is accomplished by refusing to start additional jobs when the system load is at or above the value of M.

# Replace N and M with the right value as calculated previously
MAKEOPTS="-jN -lM"
FEATURES="distcc"

For instance, when there are two quad-core host PCs running distccd and the local PC has a dual core CPU, then the MAKEOPTS variable could look like this:

# 2 remote hosts with 4 cores each = 8 cores remote
# 1 local host with 2 cores = 2 cores local
# total number of cores is 10, so N = 2*10+1 and M=2
MAKEOPTS="-j21 -l2"

# Minimal list of flags is generated with:
#   $ diff -U0 <(LANG=C gcc -Q -O2 -march=sandybridge --help=target) <(LANG=C gcc -Q -O2 -march=native --help=target)
COMMON_FLAGS="-march=sandybridge -mtune=sandybridge -maes" # don't use -march=native!
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"

With automake[edit | edit source]

This is, in some cases, easier than the Portage setup. All that is needed is to update the PATH variable to include /usr/lib/distcc/bin/ in front of the directory that contains gcc (/usr/bin/). However, there is a caveat. If ccache is used, then put the distcc location after the ccache one:

Put this in the user's ~/.bashrc or equivalent file to have the PATH set every time the user logs in, or set it globally through an /etc/env.d/ file.

Instead of calling make alone, add in -jN (where N is an integer). The value of N depends on the network and the types of computers that are used to compile. A heuristic approach to the right value is given earlier in this article.

With ccache[edit | edit source]

To make Ccache work with distcc, some prerequisites must be fulfilled:

• Ccache is successfully set up locally
• is successfully set up on the desired hosts

The following setup will work as follows:

[client]                                                      [remote]
ccache <miss?> → compile it and save cache files,
<hit?>           also distribute other source code → distcc → ccache <miss?> → compile it, save cache files, return cache file to client
  ↓                                                           <hit?>
use the local cache file                                        ↓
                                                 return local cache file to client

PATH="/usr/lib/ccache/bin:${PATH}"
CCACHE_PREFIX="distcc"

CCACHE_DIR="/var/cache/ccache"
DISTCC_DIR="/var/tmp/portage/.distcc"

>>> Regenerating /etc/ld.so.cache...

[...]
FEATURES="distcc ccache"
CCACHE_DIR="/var/cache/ccache"

[...]
DISTCCD_OPTS="${DISTCCD_OPTS} --log-level debug"
[...]

[...]
distcc[29466] (dcc_cleanup_tempfiles_inner) skip cleanup of /tmp/distcc_9c42f0a6.i
distcc[29466] (dcc_cleanup_tempfiles_inner) skip cleanup of /tmp/distcc_server_stderr_9cc0f0a6.txt
[...]

[...]
distcc[29466] compile main.c on 192.168.0.4 completed ok
[...]

[...]
distccd[13296] (dcc_check_compiler_masq) /usr/lib/ccache/bin/gcc is a safe symlink to /usr/bin/ccache
[...]
distccd[13296] (dcc_job_summary) client: 192.168.0.4:33880 COMPILE_OK exit:0 sig:0 core:0 ret:0 time:20ms gcc main.c

PATH="/usr/lib/ccache/bin:${PATH}"
CCACHE_DIR="/var/cache/ccache"
DISTCC_DIR="/var/tmp/portage/.distcc"

To bootstrap[edit | edit source]

Using distcc to bootstrap (i.e. build a working toolchain before installing the remainder of the system) requires some additional steps to take.

FEATURES="distcc"
MAKEOPTS="-jN"

!!! Problem resolving dependencies for sys-devel/distcc

!!! The ebuild selected to satisfy "sys-devel/distcc" has unmet requirements.
- sys-devel/distcc-3.2_rc1-r4::gentoo USE="-crossdev -gnome -gssapi -gtk -hardened -ipv6 (-selinux) -xinetd -zeroconf" ABI_X86="(64)" PYTHON_TARGETS="-python2_7"

  The following REQUIRED_USE flag constraints are unsatisfied:
    python_targets_python2_7

Extras[edit | edit source]

The distcc application has additional features and applications to support working in a distcc environment.

Monitoring utilities[edit | edit source]

Distcc ships with two monitoring utilities. The text-based monitoring utility is always built and is called distccmon-text. Running it for the first time can be a bit confusing, but it is really quite easy to use. If the program is run with no parameter it will run just once. However, if it is passed a number it will update every N seconds, where N is the argument that was passed.

The other monitoring utility is only enabled when the gtk USE flag is set. This one is GTK based, runs in an X environment, and it is quite lovely. For Gentoo, the GUI monitor has been renamed to distccmon-gui to make it less confusing (it is originally called distccmon-gnome).

To monitor Portage's distcc usage:

A trick is to set DISTCC_DIR in environment variables:

Now update the environment:

Finally, start the GUI application:

SSH for communication[edit | edit source]

Setting up distcc via SSH includes some pitfalls. First, generate an SSH key pair without password setup. Be aware that portage compiles programs as the Portage user (or as root if FEATURES="userpriv" is not set). The home folder of the Portage user is /var/tmp/portage/, which means the keys need to be stored in /var/tmp/portage/.ssh/

Second, create a section for each host in the SSH configuration file:

Host test1
    HostName 123.456.789.1
    Port 1234
    User UserName
 
Host test2
    HostName 123.456.789.2
    Port 1234
    User UserName

Send the public key to each compilation node:

Also make sure that each host is available in the known_hosts file:

Fix the file ownership as follows:

To set up the hosts test1 and test2, run:

Please note the @ (@ sign), which specifies ssh hosts for distcc.

Finally, tell distcc which SSH binary to use:

DISTCC_SSH="ssh"

It is not necessary to run the distccd initscript on the hosts when distcc communicates via SSH.

Testing[edit | edit source]

To test distcc, write a simple Hello distcc program and run distcc in verbose mode to see if it communicates properly.

#include <stdio.h>
 
int main() {
    printf("Hello distcc!\n");
    return 0;
}

Next, turn on verbose mode, compile the program using distcc and link the generated object file into an executable:

There should be a bunch of output about distcc finding its configuration, selecting the host to connect to, starting to connect to it, and ultimately compile main.c. If the output does not list the desired distcc hosts, check the configuration.

Finally, ensure the compiled program works properly. To test each host, enumerate each compile host in the hosts file.

Hello distcc!

ERROR: failed to open /var/log/distccd.log[edit | edit source]

As of January 22nd, 2015 emerging fails to create the proper distccd.log file in /var/log/. This apparently only effects version 3.1-r8 of distcc. This bug is in the process of being corrected (see bug #477630). It is possible to work around this by manually creating the log file, giving it proper ownership, and restarting the distccd daemon:

Next update the /var/log path of the distccd configuration file in /etc/conf.d/distccd to the distcc directory created in the step before:

DISTCCD_OPTS="--port 3632 --log-level notice --log-file /var/log/distcc/distccd.log -N 15

Finally, restart the distccd service:

Some packages do not use distcc[edit | edit source]

As various packages are installed, users will notice that some of them aren't being distributed (and aren't being built in parallel). This may happen because the package' Makefile doesn't support parallel operations, or the maintainer of the ebuild has explicitly disabled parallel operations due to a known problem.

Sometimes distcc might cause a package to fail to compile. If this happens, please report it.

Mixed GCC versions[edit | edit source]

If the environment hosts different GCC versions, there will likely be very weird problems. The solution is to make certain all hosts have the same GCC version.

Recent Portage updates have made Portage use ${CHOST}-gcc (minus gcc) instead of gcc. This means that if i686 machines are mixed with other types (i386, i586) then the builds will run into troubles. A workaround for this may be to run:

It is also possible to set the CC and CXX variables in /etc/portage/make.conf to the values list in the command above.

-march=native[edit | edit source]

Starting with GCC 4.3.0, the compiler supports the -march=native option which turns on CPU auto-detection and optimizations that are worth being enabled on the processor on which GCC is running. This creates a problem when using distcc because it allows the mixing of code optimized for different processors. For example, running distcc with -march=native on a system that has an AMD Athlon processor and doing the same on another system that has an Intel Pentium processor will mix code compiled on both processors together.

Heed the following warning:

See the CFLAGS and CXXFLAGS section and Inlining -march=native for distcc for more information.

Network is unreachable[edit | edit source]

Due to network restrictions introduced by the feature network-sandbox, you may run into this issue. Since distcc contradicts with this security feature, you have to disable it:

FEATURES="${FEATURES} -network-sandbox"

Get more output from emerge logs[edit | edit source]

It is possible to obtain more logging by enabling verbose mode. This is accomplished by adding DISTCC_VERBOSE to /etc/portage/bashrc:

export DISTCC_VERBOSE=1

The verbose logging can then be found in /var/tmp/portage/$CATEGORY/$PF/temp/build.log.

Keep in mind that the first distcc invocation visible in build.log isn’t necessary the first distcc call during a build process. For example a build server can get a one-minute backoff period during the configuration stage when some checks are performed using a compiler (distcc sets a backoff period when compilation on a remote server failed, it doesn’t matter whether it failed on local machine or not).

Dig into the /var/tmp/portage/$CATEGORY/$PF/work/ directory to investigate such situations. Find other logs, or call make explicitly from within the working directory.

Another interesting variable to use is DISTCC_SAVE_TEMPS. When set, it saves the standard output/error from a remote compiler which, for Portage builds, results in files in the /var/tmp/portage/$CATEGORY/$PF/temp/ directory.

export DISTCC_SAVE_TEMPS=1