Distcc

Hosts also need to be in:

Optionally, to set the maximum number of threads used by a host, add a forward slash "/" after each host:

192.168.0.1/8
192.168.0.2/4
192.168.0.3/16

The same applies to the distcc-config command. If the maximum threads number is not specified, it will default to 4.

While editing the make.conf file, make sure that it does not have -march=native in the CFLAGS or CXXFLAGS variables. distccd will not distribute work to other machines if march is set to native . Instead it should list exact platform and a few extra flags as necessary for the CPU. Something like:

See Inlining -march=native for distcc for more information.

As an alternative, install app-misc/resolve-march-native to determine what -march=native would resolve into.

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

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

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

The following setup will work as follows:

Configure distccd

In order to let the daemon distccd use ccache , it must masquerade the path /usr/bin with /usr/lib/ccache/bin . Furthermore, when it uses ccache , ccache should use the prefix distcc :

Additionally distccd must be aware of the environment variables DISTCC_DIR and CCACHE_DIR :

Next, update the environment variables:

Finally, restart the daemon distccd to adapt all changes:

Configure ccache

First, prepare the cache directories:

The second command ( mkdir ) will create the first level directories from a to z , 0 to 9 and tmp . The following for loop will then look for the first level directories ( find . -maxdepth 1 -type d ), excluding the current directory . and tmp ( -not -name "." -and -not -name "tmp" ). It then descends into each of them ( pushd ), creates the second level directories from a to z and 0 to 9 ( mkdir ) and goes back to the previous directory ( popd ), which is /var/cache/ccache/ .

When the preparation is done, every directory - including the directory ccache itself - must be owned by the user distcc :

Configure portage

To use emerge with distcc and ccache , make sure, that both features are enabled and that CCACHE_DIR is set in /etc/portage/make.conf :

It might be redundant to set CCACHE_DIR here, since it is already defined in /etc/env.d/03distcc_ccache , mentioned here . But to make absolutely sure, configure it like that.

Testing distcc with ccache manually

Remote

First enable verbose logging by setting --log-level to debug in /etc/conf.d/distccd :

After that, restart the daemon to adapt the changes:

Also check, if there are directories in /var/cache/ccache - including the directory ccache itself - which are not owned by the user distcc and correct their owner permissions:

Client

Make sure, that the following environment variables are present in the current shell:

After that, navigate to a temporary directory within /tmp/ and compile the example mentioned below:

This will provide a verbose output, while also keeping temporary files receiving from the remote site in /tmp/ by default:

Any occuring error from the remote site are saved in /tmp/distcc_server_stderr_*.txt .

If the compilation was successful, the following line will be shown:

On the remote site, it will look like this:

The important part here, is, that any symlink of /usr/lib/ccache/bin/ is a save symlink to /usr/bin/ccache .

Also, on the remote site, there should be the cached file 2beaa22dc2a2873d6869d69411840c-17229.o in /var/cache/ccache/c/0/ , assuming, the example with its filename was copied from this wiki article. Generally, one can monitor the ccache size using watch "ccache --show-stats" , while compiling.

Testing distcc with ccache using emerge

Check, if necessary environment variables are present for the current shell, see here and that /etc/portage/make.conf was configured properly, see here .

To produce some cached files on the remote site, one can compile small packages like htop and bzip2 on the client:

Future usage

Make sure, that the following environment variables are always set in the desired shell:

TODO: Todo:

• Check this section for outdated information. Notably "USE='-*'" and "--nodeps" may no longer be advised. See Discussion page for more informaiton.

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

Update the PATH variable in the installation session as well:

Extras

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

Monitoring utilities

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

Send the public key to each compilation node:

Fix the file ownership as follows:

To set up the hosts test1 and test2 , run:

Finally, tell distcc which SSH binary to use:

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

Reverse SSH

As an alternative to distcc's built-in SSH solution, a compiling server can connect to the distcc client via SSH, redirecting the client's distcc TCP port to the compiling server. There is no need for password-less SSH keys on the client:

Note that distcc uses localhost as a literal keyword for special purpose so that 127.0.0.1 has to be used instead. For multiple compiling servers each needs its own port redirection on the client (e.g. 127.0.0.1:4000, 127.0.0.1:4001 etc). Assert that IP addresses and ports are listed in /etc/distcc/hosts on the client.

Testing

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

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.

If a problem occurs while using distcc , then this section might help in resolving the problem.

ERROR: failed to open /var/log/distccd.log

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:

Finally, restart the distccd service:

Rust package is known to cause excessive IO utilization as --local-load is ignored and --jobs is usually too high for local build resources. A package.env needs to be provisioned with non-distcc MAKEOPTS values to workaround this behavior.

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

Heed the following warning:

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

Network is unreachable

Due to network restrictions introduced by the feature network-sandbox , this issue may be encountered. Since distcc contradicts with this security feature, it must be disabled:

Get more output from emerge logs

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

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.

Failed to create directory /dev/null/.cache/ccache/tmp: Not a directory

This error can be discovered from the standard error output file in the server if DISTCC_SAVE_TEMPS is set. It only occurs when using distccd with ccache .

Likely, it is because CCACHE_DIR is not properly set, or not passed correctly to distccd . ccache will then default to $HOME/.cache/ccache as its cache folder. However, ccache is run by distccd under user distcc , which is a non-login account. See systemd section and With ccache section for setting CCACHE_DIR .

Portage build failing with errors that are apparently not connected with distcc at all

When builds are failing with errors that do not seem to be connected to distcc, but the build works with FEATURES="-distcc", it has been reported that builds sometimes fail because of DISTCC_VERBOSE=1. Try the build with DISTCC_VERBOSE=0.

• Distcc/Cross-Compiling — shows the reader how to set up distcc for cross-compiling across different processor architectures.

External resources

• Inlining -march=native for distcc
• Distcc on Github
• Distcc homepage