This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.

Please visit our production wiki at https://wiki.gentoo.org

Distcc

From Gentoo Wiki (test)
Jump to:navigation Jump to:search
This page is a translated version of the page Distcc and the translation is 35% complete.
Outdated translations are marked like this.
Other languages:
Resources

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.

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

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.

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

Emerge

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.

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.

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

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"

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"
Nota
Impostare il valore network-sandbox nella variabile FEATURES sul client sembra prevenire la distribuzione dei dati di compilazioni agli altri server, in quanto blocca la comunicazione di rete. Assicurarsi che non sia impostata (inesistente) o disabilitata (-network-sandbox).
Note
Distcc’s pump mode may significantly reduce build time for big packages. Consider the Specifying participating hosts section for more details.

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. An approximate set of -march= and machine flags can be obtained by running the following command:

user $gcc -v -E -x c -march=native -mtune=native - < /dev/null 2>&1 | grep cc1 | perl -pe 's/^.* - //g;'

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

A GCC bug has recently been fixed in the 8.0 dev tree which facilitates a more reliable and succinct mechanism for extrapolating appropriate machine flags. The fix has been backported to the 6 and 7 branches and should be released fairly soon. Some processing is still required and a script can be found in the distccflags repo, or via wget:

Warning
Downloading scripts and executing them without any validation is a security risk. Before executing such scripts, take a good look at what they want to accomplish and refrain from executing it when the content or behavior is not clear and purposeful.
user $chmod +x distccflags
user $./distccflags -march=native

With automake

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:

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

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.

To bootstrap

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

Step 1: Configure Portage

Boot the new box with a Gentoo Linux LiveCD and follow the installation instructions, while keeping track of the instructions in the Gentoo FAQ for information about bootstrapping. Then configure Portage to use distcc:

FILE /etc/portage/make.confConfigure Portage to use distcc
FEATURES="distcc"
MAKEOPTS="-jN"

Update the PATH variable in the installation session as well:

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

Step 2: Getting distcc

Install sys-devel/distcc:

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

Step 3: Setting up distcc

Run distcc-config --install to setup distcc; substitute the host# in the example with the IP addresses or hostnames of the participating nodes.

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

Distcc is now set up to bootstrap! Continue with the proper installation instructions and do not forget to run emerge distcc after running emerge @system. This is to make sure that all of the necessary dependencies are installed.

Note
During bootstrap and emerge @system distcc may not appear to be used. This is expected as some ebuilds do not work well with distcc, so they intentionally disable it.

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
Important
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/02distcc

Now update the environment:

root #env-update
root #source /etc/profile

Finally, start the GUI application:

root #distccmon-gui

SSH for communication

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/

root #ssh-keygen -b 2048 -t rsa -f /var/tmp/portage/.ssh/id_rsa

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

FILE /var/tmp/portage/.ssh/configAdd per-host sections
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:

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

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

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 #/usr/bin/distcc-config --set-hosts "@test1 @test2"

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

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.

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
Note
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!

Troubleshooting

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

Some packages do not use distcc

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

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:

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.

Important
Doing this explicitly redefines some behavior of Portage and may have some weird results in the future. Only do this if mixing CHOSTs is unavoidable.
Note
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.

-march=native

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:

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

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

See also

  • The DistCC Cross-compiling guide explains how using one architecture to build programs for another architecture is done through distcc. This can be as simple as using an Athlon (i686) to build a program for a K6-2 (i586), or using a SPARC to build a program for a PowerPC.

External resources

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 Joshua Saddler (nightmorph)
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.

Retrieved from "https://wikitest.gentoo.org/index.php?title=Distcc/it&oldid=686218"