Distcc/it

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

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

Installazione
Prima di configurare, diamo un'occhiata all'installazione del pacchetto su tutti gli host.

Requisiti per tutti gli host
Per poter usare, 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.

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.

Dopo aver configurato le opzioni USE, si installi il pacchetto :

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

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

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

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

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

systemd
Modificare il file 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:

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

To set the proper environment variables for, place them into. For example,

For workaround, you need to edit distccd.service by running the following command.

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

Alternatively, you could also write a shell script wrapper for.

Ricaricare i file unit dopo aver apportato tali cambiamenti:

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

Specificare gli Host Partecipanti
Utilizzare il comando 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  per informare  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.

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

Se si deve anche compilare sulla macchina locale, occorre inserire  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 affinché usi gli host menzionati nella prima linea dell'esempio:

Distcc supporta anche una modalità "pompa", invocando il comando. 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  alle definizioni degli host. La modalità pompa richiede sia l'opzione  (a prescindere dal fatto che i file siano in C o in C++).

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:

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

Con Portage
Far usare a Portage è semplice. Si tratta semplicemente di abilitare la feature e di impostare un valore decente per il numero di lavori paralleli (in quando  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  al doppio del numero totale (locali + remoti) di core di CPU + 1, e
 * nell'impostare il valore di  al numero di core di CPU locali

L'uso di  nella variabile MAKEOPTS preverrà la comparsa di troppe attività quando uno degli host cluster di  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.

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

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

See Inlining  for distcc for more information.

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  per farle includere  di fronte alla directory che contiene. In ogni caso, c'è da fare attenzione. Se si usa ccache bisogna inserire distcc dopo ccache:

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

Instead of calling alone, add in   (where   is an integer). The value of  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, 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 use, it must masquerade the path  with. Furthermore, when it uses, should use the prefix  :

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

Next, update the environment variables:

Finally, restart the daemon to adapt all changes:

Configure ccache
First, prepare the cache directories:

The second command will create the first level directories from  to,  to  and. The following loop will then look for the first level directories, excluding the current directory  and. It then descends into each of them, creates the second level directories from to  and  to   and goes back to the previous directory , which is.

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

Configure portage
To use with  and, make sure, that both features are enabled and that CCACHE_DIR is set in :

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

Remote
First enable verbose logging by setting  to   in :

After that, restart the daemon to adapt the changes:

Also check, if there are directories in - including the directory  itself - which are not owned by the user   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 and compile the example mentioned below:

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

Any occuring error from the remote site are saved in.

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 is a save symlink to.

Also, on the remote site, there should be the cached file in, assuming, the example with its filename was copied from this wiki article. Generally, one can monitor the ccache size using, while compiling.

Testing distcc with ccache using emerge
Check, if necessary environment variables are present for the current shell, see here and that was configured properly, see here.

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

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

Using 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  per configurare distcc; sostituire   con gli indirizzi IP o con gli hostname delle macchine partecipanti.

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, per assicurarsi che tutte le dipendenze desiderate vengano installate.

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  invece di. 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  o di inserirlo direttamente in.

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

Monitoring utilities
Distcc ships with two monitoring utilities. The text-based monitoring utility is always built and is called. 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  seconds, where   is the argument that was passed.

The other monitoring utility is only enabled when the  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 to make it less confusing (it is originally called ).

To monitor Portage's usage:

A trick is to set DISTCC_DIR in environment variables:

Now update the environment:

Finally, start the GUI application:

Cross-Compilazione
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.

Fase 1: Configurare Portage
Send the public key to each compilation node:

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

Fix the file ownership as follows:

To set up the hosts  and , run:

Finally, tell which SSH binary to use:

It is not necessary to run the initscript on the hosts when  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 as a literal keyword for special purpose so that  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 on the client.

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

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

There should be a bunch of output about finding its configuration, selecting the host to connect to, starting to connect to it, and ultimately compile. If the output does not list the desired 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, then this section might help in resolving the problem.

ERROR: failed to open
As of January 22nd, 2015 emerging fails to create the proper file in. This apparently only effects version 3.1-r8 of distcc. This bug is in the process of being corrected (see ). 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 path of the  configuration file in  to the  directory created in the step before:

Finally, restart the distccd service:

-march=native
A partire da GCC 4.3.0, il compilatore supporta l'opzione, 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  in quanto abilita il mix di codice ottimizzato per processori differenti (come AMD Athlon e Intel Pentium). NON usare  o   nelle proprie   o   durante le compilazioni con.

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

Distcc Monitor
Distcc viene distribuito con due monitor. Quello testuale è sempre incluso, e viene lanciato con. 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  flag   o. Questo monitor è basato su gtk+, gira dentro l'ambiente X ed è molto bello. Per Gentoo il monitor con interfaccia grafica risponde al comando. In altri ambienti dovrebbe rispondere al nome di.

It is also possible to set the CC and CXX variables in to the values list in the command above.

o lanciare :

Heed the following warning:

See the CFLAGS and CXXFLAGS section and Inlining  for distcc for more information.

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

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 :

The verbose logging can then be found in.

Keep in mind that the first invocation visible in  isn’t necessary the first  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 ( 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 directory to investigate such situations. Find other logs, or call 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 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 you set DISTCC_SAVE_TEMPS. It only occurs when using with.

Likely, it is because CCACHE_DIR is not properly set, or not passed correctly to. will then default to as its cache folder. However, is run by  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.

External resources

 * Inlining  for distcc
 * Distcc on Github
 * Distcc homepage