Distcc

Some of the information in this article may have drifted out of sync with current practices. Please help out by checking over the content (how to get started).

Resources

Home

Wikipedia

Distcc è un programma progettato per distribuire processi di compilazione agli host partecipanti attraverso una rete. È composto da un server, distccd e da un client, distcc. Distcc funziona in maniera trasparente con ccache, Portage e Automake con poco lavoro per la configurazione.

Distcc comprises a server, distccd, and a client program, distcc. Distcc can work transparently with ccache, Portage, and Automake with a small amount of setup.

Se si intende usare distcc per facilitare il bootstrap dell'installazione di Gentoo, assicurarsi di leggere la sezione Uso di Distcc per il Bootstrap.

If using hosts to run distcc that are of a different architecture, or run a different toolchain, see Distcc/Cross-Compiling.

Nota
Distcc can introduce compile-time issues, like bug bug #691544, so the first troubleshooting step when encountering such issues should be to disable distcc to see if it solves it.

Suggerimento
Using a second, faster, machine to build binary packages and setting up a binary package host can advantageously replace some use cases of distcc. It may be easier to set up and will cover all compilers and build systems.

Installazione

Prima di configurare distcc, diamo un'occhiata all'installazione del pacchetto sys-devel/distcc su tutti gli host.

Requisiti per tutti gli host

Per poter usare distcc, tutti i computer sulla rete devono avere la stessa versione di GCC. Ad esempio, mischiare GCC 3.3.x (dove la x è variabile) non è un problema, ma mischiare 3.3.x e 3.2.x potrebbe generare errori in fase di compilazione o di esecuzione.

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.

Opzioni USE

USE flags for sys-devel/distcc Distribute compilation of C code across several machines on a network

gssapi	Enable support for net-libs/libgssglue
gtk	Add support for x11-libs/gtk+ (The GIMP Toolkit)
hardened	Activate default security enhancements for toolchain (gcc, glibc, binutils)
ipv6	Add support for IP version 6
selinux	!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
xinetd	Add support for the xinetd super-server
zeroconf	Support for DNS Service Discovery (DNS-SD)

Data provided by the Gentoo Package Database · Last update: 2024-01-15 15:58 More information about USE flags

Distcc viene distribuito con un monitor grafico per controllare le attività che un computer destina alla compilazione. Questo monitor viene abilitato quando si usa l'opzione USE gtk.

Emerge

Dopo aver configurato le opzioni USE, si installi il pacchetto sys-devel/distcc:

root #emerge --ask sys-devel/distcc

Importante
Assicurarsi di aver installato sys-devel/distcc su tutte le macchine che partecipano alla compilazione.

Configurazione

Servizi

Affinché distccd venga avviato automaticamente, si osservino le seguenti istruzioni.

OpenRC

Modificare /etc/conf.d/distccd ed assicurarsi di aver impostato la direttiva --allow di modo da accettare solo host fidati. Per aumentare la sicurezza, si può usare la direttiva --listen per indicare al demone distccd quale IP ascoltare (per sistemi multi-homed). Per ulteriori informazioni su distcc, consultare la pagina rigurdante le note sulla sicurezza di Distcc.

Attenzione
Anyone who can connect to the distcc server port can run arbitrary commands on that machine as the distccd user.

Il seguente esempio permette ai client distcc con indirizzo IP 192.168.0.4 e 192.168.0.5 di connettersi al server distccd in esecuzione sulla macchina locale:

FILE /etc/conf.d/distccdPermettere a client specifici di connettersi a distccd

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"

When logging to a file in /var/log, create the log and give appropriate permissions:

root #touch /var/log/distccd.log

root #chown distcc:root /var/log/distccd.log

Importante
È importante usare --allow e --listen. Per ulteriori informazioni si prega di consultare la pagina del manuale di distcc o la sezione sulla sicurezza qui sopra.

A questo punto, lanciare il demone di distccd su tutti i computer partecipanti:

root #rc-update add distccd default

root #rc-service distccd start

systemd

Modificare il file /etc/systemd/system/distccd.service.d/00gentoo.conf per aggiungere i client permessi in formato CIDR. Se si usa l'esempio, verranno aggiunti tutti gli indirizzi IP nell'intervallo 192.168.1.xxx:

FILE /etc/systemd/system/distccd.service.d/00gentoo.confConfigurazione di ALLOWED_SERVERS

Environment="ALLOWED_SERVERS=192.168.1.0/24"

Or an example with multiple clients and a manually specified log-level:

FILE /etc/systemd/system/distccd.service.d/00gentoo.confSetting ALLOWED_SERVERS

Environment="ALLOWED_SERVERS=127.0.0.1 --allow 192.168.1.0/24 --allow 10.1.1.1/24 --log-level error"

Nota
Il nome "ALLOWED_SERVERS" qui è piuttosto ambiguo, in quanto si riferisce ai client a cui è permesso connettersi al server distccd locale. In ogni caso, è questa variabile che viene usata dal servizio distccd come valore per l'opzione --allow - vedere il file /usr/lib/systemd/system/distccd.service per ulteriori informazioni.

Importante
In contrast to OpenRC, environment variables put in /etc/env.d/* will not take effect for systemd users even after running env-update and restarting the distccd service. This is because /etc/environment.d generated by env-update is only sourced by systemd user instance. Whereas, distccd is spawned by systemd system instance.

To set the proper environment variables for distccd, place them into /etc/systemd/system/distccd.service.d/00gentoo.conf, for example:

FILE /etc/systemd/system/distccd.service.d/00gentoo.conf

[Service]
Environment="ALLOWED_SERVERS=192.168.121.0/24"
Environment="DISTCC_VERBOSE=1"
Environment="DISTCC_SAVE_TEMPS=1"
Environment="CCACHE_DIR=/var/cache/ccache"

Attenzione
The Environment= directive in /etc/systemd/system/distccd.service.d/00gentoo.conf file does not support variable expansion. Environment="PATH=/usr/lib/ccache/bin:$PATH" will be treated as is, therefore will not work as intended.

For workaround, edit distccd.service by running the following command:

root #systemctl edit --full distccd.service

This will open up an editor. Change the line with ExecStart= directive to:

CODE Workaround for appending to PATH

ExecStart=/bin/bash -c "PATH=/usr/lib/ccache/bin:$PATH exec /usr/bin/distccd --no-detach --daemon --port 3632 -N 15 --allow $ALLOWED_SERVERS --log-level debug"

Alternatively, it is possible to write a shell script wrapper for /usr/bin/distccd.

Ricaricare i file unit dopo aver apportato tali cambiamenti:

root #systemctl daemon-reload

Abilitare l'avvio automatico di distccd e poi avviare il servizio:

root #systemctl enable distccd

root #systemctl start distccd

Specificare gli Host Partecipanti

Utilizzare il comando distcc-config per configurare la lista degli host.

Il seguente è un esempio di lista per la definizione degli host. Nella maggior parte dei casi, sono sufficienti varianti delle linee 1 e 2. Quest'ultima usa la sintassi /limit per informare distcc circa il numero massimo di lavori che possono essere lanciati sul nodo attuale. Per ulteriori informazioni riguardo la sintassi usata nelle linee 3 e 2, consultare la pagina del manuale di distcc.

CODE Esempi di definizioni degli host

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

Ci sono anche altri modi per impostare gli host. Consultare la pagina del manuale man distcc di distcc per ulteriori dettagli.

Se si deve anche compilare sulla macchina locale, occorre inserire localhost nella lista degli host. Per contro, se si vuole evitare di usare la macchina locale per compilare (caso d'uso comune), bisogna ometterlo dalla lista. Inserire localhost su una macchina lenta potrebbe addirittura rallentare le cose. È consigliabile effettuare dei test per raggiungere le prestazioni migliori.

Configuriamo distcc affinché usi gli host menzionati nella prima linea dell'esempio:

root #/usr/bin/distcc-config --set-hosts "192.168.0.1 192.168.0.2 192.168.0.3"

Distcc supporta anche una modalità "pompa", invocando il comando pump. Ciò può ridurre significativamente i tempi di compilazione quando vengono compilati più file in parallelo. Questa modalità mette in cache gli header preprocessati nel lato server e, di conseguenza, evita di ricaricarli e di preprocessarli nuovamente.

Per configurare un host affinché usi la modalità pompa, aggiungere il suffisso ,cpp,lzo alle definizioni degli host. La modalità pompa richiede sia l'opzione cpp</cpp> sia l'opzione lzo (a prescindere dal fatto che i file siano in C o in C++).

root #/usr/bin/distcc-config --set-hosts "192.168.0.1,cpp,lzo 192.168.0.2,cpp,lzo 192.168.0.3,cpp,lzo"

Hosts also need to be in:

FILE /etc/distcc/hostsShould match --set-hosts

192.168.0.1
192.168.0.2
192.168.0.3

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

FILE /etc/distcc/hostsSpecify max number of threads

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.

Utilizzo

Con Portage

Far usare distcc a Portage è semplice. Si tratta semplicemente di abilitare la feature distcc e di impostare un valore decente per il numero di lavori paralleli (in quando distcc fa crescere la quantità di risorse per la compilazione).

Adesso, impostare le variabili MAKEOPTS e FEATURES come mostrato sotto.

Una strategia comune consiste

• nell'impostare il valore di N al doppio del numero totale (locali + remoti) di core di CPU + 1, e
• nell'impostare il valore di M al numero di core di CPU locali

L'uso di -lM nella variabile MAKEOPTS preverrà la comparsa di troppe attività quando uno degli host cluster di distcc non è disponibile (accrescendo il numero di lavori simultanei negli altri sistemi) o quando un'ebuild è configurata per non permettere compilazioni remote (come nel caso di gcc). Tutto ciò viene raggiunto rifiutando di avviare lavori aggiuntivi quando il carico di sistema è maggiore o uguale al valore di M.

FILE /etc/portage/make.confConfigurare MAKEOPTS e FEATURES

# Sostituire N e M con il valore corretto come calcolato precedentemente
MAKEOPTS="-jN -lM"
FEATURES="distcc distcc-pump"

Per esempio, quando ci sono due PC host quad-core che usano distccd e il computer locale ha un processore dual-core, allora la variabile MAKEOPTS potrebbe essere come di seguito:

FILE /etc/portage/make.confEsempio di MAKEOPTS per 2 PC quad-core (remoti) e un PC dual core (locale)

# 2 host remoti con 4 core ciascuno = 8 core remoti
# 1 host locale con 2 core = 2 core locali
# il numero complessivo di core è 10, quindi N = 2*10+1 e M=2
MAKEOPTS="-j21 -l2"

CFLAGS e CXXFLAGS

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:

FILE /etc/portage/make.confinlined *FLAGS

# 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}"

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.

Configurare Distcc per funzionare con Automake

In molti casi, questa procedura è anche più semplice della parte riguardante Portage. Ciò che bisogna fare è aggiornare la propria variabile PATH per farle includere /usr/lib/distcc/bin di fronte alla directory che contiene gcc ( /usr/bin ). In ogni caso, c'è da fare attenzione. Se si usa ccache bisogna inserire distcc dopo ccache:

root #export PATH="/usr/lib/ccache/bin:/usr/lib/distcc/bin:${PATH}"

Si può inserire tutto questo dentro il proprio ~/.bashrc o equivalente, di modo da impostare PATH ogni volta che si esegue il login.

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:

CODE Flow diagram

[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

Attenzione
The following configuration must be done on all desired hosts!

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:

FILE /etc/conf.d/distccd

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

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

Attenzione
These variables must be set somewhere in /etc/env.d/, otherwise ccache tries to put cache files in ${HOME}/.ccache/, which might result in a COMPILE_ERROR, due to insufficient permissions. To pinpoint this, use the testing example mentioned below and export DISTCC_SAVE_TEMPS="1" as mentioned here. This will provide error logs from the remote site in /tmp/ by default. The logs will look like this: distcc_server_stderr_*.txt. Be aware, that these environment variables cannot be set in /etc/conf.d/distccd, since they will not be read from distccd for some reason.

FILE /etc/env.d/03distcc_ccache

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

Next, update the environment variables:

root #env-update

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

Finally, restart the daemon distccd to adapt all changes:

root #rc-service distccd restart

Configure ccache

Attenzione
When using distcc with ccache, it is necessary to prepare the cache directories manually, since the daemon distccd only works with the user distcc for some reason and it cannot create directories within /var/cache/ccache/. It is not sufficient to add this user to the group portage. Also be aware, that the variable cache_dir_levels, defined in ccache.conf, specifies how many subdirectories have to be created. The following example uses the default, which is 2.

First, prepare the cache directories:

root #cd "/var/cache/ccache/"

root #mkdir {a..z} {0..9} tmp

root #for first_level_directory in $(find . -maxdepth 1 -type d -not -name "." -and -not -name "tmp"); do pushd "${first_level_directory}" >/dev/null; mkdir {a..z} {0..9}; popd >/dev/null; done

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/.

Importante
The current directory . must be excluded with -not -name ".", otherwise the first pushd command will go to the current directory . and then goes back to whatever directory is currently on the stack via popd. It will navigate through the entire stack until it is empty, creating directories, where each pushd command fails. If this happens, one can search for them using find / -type d -name "0" and remove them with rm --recursive [a-z] [0-9]. It is advised to this manually!

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

root #find /var/cache/ccache -type d -exec chown distcc:portage "{}" +

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:

FILE /etc/portage/make.conf

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

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:

FILE /etc/conf.d/distccd

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

After that, restart the daemon to adapt the changes:

root #rc-service distccd restart

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:

root #chown -R distcc:portage /var/cache/ccache

Client

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

root #export PATH="/usr/lib/ccache/bin:${PATH}"

root #export CCACHE_DIR="/var/cache/ccache"

root #export DISTCC_DIR="/var/tmp/portage/.distcc"

root #export DISTCC_SAVE_TEMPS="1"

root #export DISTCC_VERBOSE="1"

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

root #cd $(mktemp --directory)

root #distcc gcc -c main.c -o main.o

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

CODE

[...]
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
[...]

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:

CODE

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

On the remote site, it will look like this:

CODE

[...]
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

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:

root #emerge --ask htop bzip2

Future usage

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

CODE

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

root #USE='-*' emerge --nodeps sys-devel/distcc

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.

Fase 3: Configurare Distcc ===

Lanciare distcc-config --install per configurare distcc; sostituire host* con gli indirizzi IP o con gli hostname delle macchine partecipanti.

root #/usr/bin/distcc-config --set-hosts "localhost host1 host2 host3 ..."

Update the PATH variable in the installation session as well:

Distcc è configurato per il bootstrap! Continuare con le istruzioni di installazioni ufficiali e non dimenticare di ri-emergere Distcc dopo aver lanciato emerge system, per assicurarsi che tutte le dipendenze desiderate vengano installate.

Nota
Durante il bootstrap e l'emerge system distcc potrebbe dare l'impressione di non essere usato. Questo è un comportamento normale in quanto alcune ebuild non funzionano correttamente con distcc, e di conseguenza lo disabilitano intenzionalmente.

Risoluzione dei problemi

Alcuni pacchetti non usano Distcc

Man mano che si emergono pacchetti, si può notare come alcuni di essi non vengano compilati in modalità distribuita (e neanche in parallelo). Questo è possibile quando il Makefile del pacchetto in questione non supporta le operazioni parallele, o quando il manutentore dell'ebuild le ha esplicitamente disabilitate, spesso a causa di problemi noti.

A volte distcc può causare fallimenti nelle compilazioni. Se succede, si è pregati di comunicarlo nel bugtracker.

Versioni di GCC differenti

Se si hanno diverse versioni di gcc nei propri host, molto probabilmente si manifesteranno problemi di varia natura. La soluzione consiste nell'installare in tutti gli host la stessa versione di GCC.

Gli aggiornamenti più recenti di Portage usano ${CHOST}-gcc invece di gcc. Questo significa che se si stanno usando macchine i686 insieme ad altre di diverso tipo (i586,i386) si incontreranno problemi. Una soluzione può essere quella di specificare export CC='gcc' CXX='c++' o di inserirlo direttamente in /etc/portage/make.conf.

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.

user $distccmon-text 10

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).

user $distccmon-gui

To monitor Portage's distcc usage:

root #DISTCC_DIR="/var/tmp/portage/.distcc/" distccmon-text 10

root #DISTCC_DIR="/var/tmp/portage/.distcc/" distccmon-gui

Importante
If the distcc directory is elsewhere, change the DISTCC_DIR variable accordingly.

A trick is to set DISTCC_DIR in environment variables:

root #echo 'DISTCC_DIR="/var/tmp/portage/.distcc/"' >> /etc/env.d/03distcc_custom

Importante
Be aware that DISTCC_DIR must be set somewhere else than /etc/env.d/02distcc, as it gets overwritten everytime, when using distcc-config!. distcc-config --set-env DISTCC_DIR <some_path> does not work.

Now update the environment:

root #env-update

root #source /etc/profile

Finally, start the GUI application:

root #distccmon-gui

SSH for communication

Cross-Compilazione

Attenzione
{{{1}}}

La cross-compilazione consiste nell'utilizzare un'architettura per costruire software che verranno eseguiti su un'altra architettura. La cosa può essere semplice come ad esempio usare un Athlon (i686) per compilare un programma per K6-2(i586), o usare uno Sparc per compilare un programma per ppc. Tutto ciò è documentato nella nostra Guida a DistCC per la Cross-compilazione .

Usare Distcc per il Bootstrap

Fase 1: Configurare Portage

Send the public key to each compilation node:

root #ssh-copy-id -i /var/tmp/portage/.ssh/id_rsa.pub UserName@CompilationNode

Avviare il computer con un Gentoo Linux LiveCD e seguire le istruzioni di installazione fino alla parte riguardante il bootstrap (consultare le Gentoo FAQ per ulteriori informazioni riguardo il bootstrap.). In seguito, configurare Portage per l'uso di Distcc

root #ssh-keyscan -t rsa <compilation-node-1> <compilation-node-2> [...] > /var/tmp/portage/.ssh/known_hosts

Fix the file ownership as follows:

root #chown -R portage:portage /var/tmp/portage/.ssh/

To set up the hosts test1 and test2, run:

root #nano -w /etc/portage/make.conf

FEATURES="distcc"
MAKEOPTS="-jN"

root #export PATH="/usr/lib/ccache/bin:/usr/lib/distcc/bin:${PATH}"

Finally, tell distcc which SSH binary to use:

FILE /etc/portage/make.conf

DISTCC_SSH="ssh"

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:

user $ssh -R3632:127.0.0.1:3632 root@distcc-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.

FILE main.c

#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:

user $export DISTCC_VERBOSE=1

user $distcc gcc -c main.c -o main.o # or 'pump distcc <...>'

user $gcc main.o -o main

Nota
Replace distcc command with pump distcc for use pump mode.

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.

user $./main

Hello distcc!

Importante
Effettuare questa modifica cambia alcuni comportamenti di Portage, il che potrebbe portare a strani risultati in futuro. Effettuare tutto ciò solo nel caso in cui si stiano usando CHOST differenti.

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:

root #mkdir -p /var/log/distcc

root #touch /var/log/distcc/distccd.log

root #chown distcc:daemon /var/log/distcc/distccd.log

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:

FILE /etc/conf.d/distccdUpdating log path

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

Finally, restart the distccd service:

root #/etc/init.d/distccd restart

-march=native

A partire da GCC 4.3.0, il compilatore supporta l'opzione -march=native, che abilita il rilevamento automatico della CPU e le conseguenti ottimizzazioni che val la pena utilizzare. L'uso di questa opzione rappresenta un problema per distcc in quanto abilita il mix di codice ottimizzato per processori differenti (come AMD Athlon e Intel Pentium). NON usare -march=native o -mtune=native nelle proprie CFLAGS o CXXFLAGS durante le compilazioni con distcc.

Gli extra di Distcc

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.

FILE /etc/portage/env/nodistcc.conf

MAKEOPTS="-jN"
FEATURES="-distcc"

FILE /etc/portage/package.env/nodistcc

dev-lang/rust           nodistcc.conf
mail-client/thunderbird nodistcc.conf
sys-libs/libcxx         nodistcc.conf
www-client/firefox      nodistcc.conf

Distcc Monitor

Distcc viene distribuito con due monitor. Quello testuale è sempre incluso, e viene lanciato con distccmon-text. La prima volta può apparire confusionario, ma è molto semplice da usare. Se si lancia il comando senza parametri aggiuntivi verrà eseguito solo una volta, mentre se gli si passa un numero N, verrà aggiornato ogni N secondi.

L'altro monitor viene attivato solo se è stata abilitata la USE flag gtk o gnome . Questo monitor è basato su gtk+, gira dentro l'ambiente X ed è molto bello. Per Gentoo il monitor con interfaccia grafica risponde al comando distccmon-gui. In altri ambienti dovrebbe rispondere al nome di distccmon-gnome.

root #export CC='gcc' CXX='c++'

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

root #distccmon-text N

Nota
Having the right version of gcc as a slot on a server isn’t enough. Portage uses distcc as a replacement for the compiler referenced by the CHOST variable (i.e. x86_64-pc-linux-gnu) and distccd invokes it by exactly same name. The right version of gcc should be a default system’s compiler on all involved compilation hosts.

o lanciare distccmon-gui:

root #distccmon-gui

Heed the following warning:

Attenzione
Do not use -march=native or -mtune=native in the CFLAGS or CXXFLAGS variables of make.conf when compiling with distcc.

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

Network is unreachable

Nota
When using SSH connection, there can be an error: ssh: Could not resolve hostname: Temporary failure in name resolution.

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:

FILE /etc/portage/make.confDisabling network-sandbox feature

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

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:

FILE /etc/portage/bashrcEnabling verbose logging

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.

FILE /etc/portage/bashrcSaving temporary output

export DISTCC_SAVE_TEMPS=1

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.

Fase 2: Procurarsi Distcc

• 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

---

This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Lisa Seelye, Mike Gilbert (floppym) , Erwin, Sven Vermeulen (SwifT) , Lars Weiler, Tiemo Kieft, and
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.