Distcc/de

Distcc ist ein Programm, das die einzelnen Aufgaben bei der Kompilierung eines Paketes auf verschiedene Hosts in einem Netzwerk verteilt. Es besteht aus einem Server, distccd und einem Client-Programm, distcc. Mit geringem Aufwand ist es möglich ccache, Portage und Automake zu benutzen.

Bevor verwendet wird um eine Gentoo bootstrap Installation durchzuführen, wird empfohlen die Anleitung unter Using distcc to bootstrap zu lesen.

Installation
Das Packet sollte auf allen teilnehemenden Hosts installiert sein, bevor mit der Konfiguration von  begonnen wird.

Anforderungen an die teilnehmenden Rechner
sollte nur verwendet werden, wenn alle beteiligten Rechner die gleiche GCC-Hauptversion benutzen. Zum Beispiel ist das Verwenden von 3.3.x (x ist hier beliebig) problemlos, dagegen sollte 3.3.x nicht mit 3.2.x gemixt werden.

Stellen Sie sicher, dass alle Systeme dieselbe Version von binutils verwenden (eselect binutils list). Andernfalls können viele Pakete wegen der Verschiebung von relativen und absoluten Adressen im .elf Binary nicht übersetzt werden.

Emerge
Distccd beinhaltet ein graphisches Tool zur Überwachung der Aufgaben, die ein Rechner an andere Hosts übertragen hat. Dieses Tool ist verfügbar, wenn das USE Flag  gesetzt wird.

Wenn die USE-Flags entsprechend angepasst sind, kann mit der Installation des Paketes begonnen werden:

Dienste
Im Folgenden wird beschrieben, wie vorgegangen werden muss, um automatisch zu starten.

OpenRC
Es ist sicher zu stellen, dass alle teilnehmenden Hostes in mittels   als vertrauenswürdig benannt sind. Um die Sicherheit zu erhöhen, kann mit  der  auf eine bestimmte Netzwerkschnittstelle gebunden werden. Mehr Informationen zum Thema Sicherheit kann unter Distcc security notes abgerufen werden.

Jeder, der eine Verbindung zum distcc-Server-Port herstellen kann, kann als distccd-Benutzer beliebige Befehle auf diesem Computer ausführen.

Im folgenden Beispiel wird den Rechnern mit den IP-Adressen  und   die Verbindung zum lokalen  server erlaubt:

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

Der daemon ist auf allen beteiligten Rechnern zu starten.

systemd
Um mehreren Rechnern aus einem bestimmten Adressbereich den Zugriff zu erlauben, so ist dieser Bereich im CIDR Format in einzutragen. Im folgenden Beispiel wird allen Rechnern mit der IP-Adresse 192.168.1.xxx der Zugriff erlaubt:

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.

Mit dem folgendem Befehl wird der Dienst neu eingelesen:

Die folgenden Befehle starten während des Boot-Vorganges zu starten bzw. sofort.

Teilnehmende Rechner definieren
Hierfür wird der Befehl verwendet.

Im Folgenden sind verschiedene Varianten der Host-Definition zu sehen. Mit dem Zeichen  wird ein Limit gesetzt, wie viele Aufgaben diesem Host gleichzeitig übergeben werden können. Die Zeilen 3 und 4 werden in der distcc manual page näher erläutert.

Es gibt noch weitere Methoden um teilnehmende Hosts anzugeben. Einzelheiten dazu enthält die Manpage.

Ohne die Angabe  wird  keinen Kompiliervorgang auf dem lokalen Rechner anstoßen. Handelt es sich bei dem lokalen Host um einen langsamen Rechner, kann dieser sich als Flaschenhals des Übersetzungsvorganges herausstellen. Die bestmöglichen Einstellungen für das eigene Setup können nur durch Experimentieren mit dem  Eintrag herausgefunden werden.

Der folgende Befehl konfiguriert so, dass die Aufgaben auf die Rechner der 1.Zeile im obigen Beispiel verteilt werden:

In ist ein "pump" Modus implementiert, dieser wird durch den Befehl  aufgerufen. Dieser Modus kann zu einer beträchtlichen Einsparung an Rechenzeit führen, wenn viele verschiedene Dateien gleichzeitg übersetzt werden müssen. Es werden übersetzte Header-Dateien auf dem Server zwischengespeichert, wadurch sich bei wiederholten Upload Zeitersparnisse ergeben.

Um für einen Host den pump-Modus zu aktivieren, werden die Flags  an dessen Definition angehängt. Der Pump-Modus benötigt  und , ungeachtet ob es sich bei den zu übersetzenden Dateien um C oder C++-Quelltext handelt.

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.

für Portage
Portage für die Benutzung mit einzurichten, ist einfach. Es muss nur die  Option mit den gewünschten Modi in make.conf definiert werden. Weiterhin ist die  Variable an die gewünschte Anzahl anzupassen.

Die MAKEOPTS und FEATURES ist wie unten gezeigt zu setzen:

Es wird folgende Strategie empfohlen:
 * ist auf die Gesamtanzahl +1 (lokal und remote) an Rechnerkernen zu setzen
 * ist auf die Anzahl an lokalen Rechnerkernen zu setzen

Die Benutzung von  in der MAKEOPTS Variable, verhindert das Starten zu vieler lokaler Aufgaben, wenn entfernte Rechner nicht erreichbar sind oder die Vorgaben des Ebuild ein Übersetzen auf entfernten Rechner nicht zulassen. Es werden dann keine weiteren Jobs mehr gestartet, wenn die Systemlast auf einen Wert größer als  steigt.

Die Werte in der MAKEOPTS Varibalen können bei 2 PC mit einer QuadCore CPU auf denen und der lokale Rechner ist eine DualCore CPU folgendermaßen belegt werden:

CFLAGS und CXXFLAGS
Wenn die bearbeitet wird, ist darauf zu achten, das nicht die   in CFLAGS oder CXXFLAGS verwendet wird. wird keine Aufgaben an Remote Hosts übertragen, wenn  auf   steht. Der passende  Wert kann durch folgenden Befehl herausgefunden werden:

Der [//blogs.gentoo.org/mgorny/2014/06/23/inlining-marchnative-for-distcc/ Blog-Eintrag] Inlining  for distcc enthält hierzu Hintergrundinformationen.

Mit automake
In einigen Fällen ist dies einfacher als das Portage-Setup. Hierzu ist die Reihenfolge der Suchpfade in der PATH Variablen folgendermaßen zu setzen:


 * 1)  (wenn verwendet)
 * 2)  (enthält /usr/bin/gcc)
 * 1)  (enthält /usr/bin/gcc)

Die obige Anweisung kann in der jedes einzelnen Benutzer hinterlegt werden, so dass die PATH Variable bei jedem Login entsprechend gesetzt wird. Um dieses Verhalten für alle Benutzer zu erreichen, kann diese Anweisung in einer Datei in gespeichert werden.

Der Befehl sollte nicht ohne zusätzliche Argumente aufgerufen werden, sondern mit dem Zusatz , wie früher in diesem Artikel beschrieben.

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:

Verwendung für Bootstrapping
Wenn für das [//de.wikipedia.org/wiki/Bootstrapping_(Informatik) Bootstrapping] verwendet werden soll, z.B. um verschiedene Tools vor dem Hauptteil des Systems zu erstellen, sind einige vorbereitende Schritte erforderlich.

Schritt 1: Konfiguration von Portage
Der neue Rechner ist mit einer Gentoo Linux LiveCD zu starten und den Installations-Anweisungen des Handbuches zu folgen, mit besonderem Augenmerk auf die Informationen aus der FAQ für [//wiki.gentoo.org/wiki/FAQ/de Bootstrapping]. Danach ist Portage für die Verwendung von zu konfigurieren:

Die PATH Variable ist für die Installation wie folgt zu setzen:

Schritt 2: Installation von distcc
Für die Installation von ist folgendes Kommando zu verwenden:

Schritt 3: Konfiguration von distcc
Für das Setup von ist der Befehl  aufzurufen, hierzu sind die   im folgenden Beispiel entsprechend der teilnehmenden Rechner mit ihrer IP-Adresse bzw. Host-Namen anzupassen.

ist nun bereit für das Bootstrapping! Nun kann mit den normalen Installationsanweisungen fortgefahren werden. Nachdem ausgeführt wurde, ist zwingend  erneut durchzuführen um sicherzustellen, dass die notwendigen Abhängigkeiten installiert werden.

Extras
Im Paket sind einige zusätzliche Funktionen und Tools enthalten, die die Arbeit in einer  Umgebung unterstützen.

Tools zur Überwachung
enthält zwei Überwachungs-Tools. Bei handelt es sich um eine Text basiertes Programm. Wird es das erste Mal aufgerufen, kann sich etwas Verwirrung einstellen, aber es ist sehr einfach zu benutzen. Wird das Programm ohne Parameter aufgerufen, beendet es sich nach einem Durchlauf. Wenn das Programm mit einem Parameter N aufgerufen wird, aktualisiert es die Anzeige der laufenden Aufgaben alle N Sekunden.

Das andere Tool zur Verfolgung des Build-Prozesses steht nur zur verfügung, wenn das USE-Flag   gesetzt ist. Dieses Programm basiert auf GTK+ und läuft in einer X-Window Umgebung. Für Gentoo wurde dieses Programm von nach  umbenannt, um Verwirrung zu vermeiden.

Für die Überwachung von Portage's werden die folgenden Kommandos verwendet:

Als Alternative bietet sich an dieses Verzeichnis DISTCC_DIR dauerhaft beim Login einzulesen:

Nun ist die Umgebung neu einzulesen:

Das Starten des Programmes geschieht mit der folgenden Anweisung:

SSH-verschlüsselte Kommunikation
Das Setup für SSH beinhaltet einige Fallstricke. Als Erstes wird ein SSH-Schlüsselpaar benötigt, welches die Authentifizierung ohne Passwortabfrage durchführt. Es sei darauf hingewiesen, das Portage die Progamme als Portage-User übersetzt oder als root wenn  nicht gesetzt ist. Das Heimat-Verzeichnis des Portage User ist, was zur Folge hat, dass die Schlüssel in gespeichert werden.

Als Nächstes muss in der SSH Konfigurations-Datei für jeden Host ein Abschnitt angelegt werden:

Die öffentlichen Schlüssel müssen auf die teilnehmenden Hosts übertragen werden:

Weiterhin ist sicherzustellen, das jeder Host in bekannt gegeben ist.

Die Zugriffsrechte müssen wie folgt gesetzt werden:

Jetzt ist der SSH-Teil der Konfiguration erledigt, es folgt noch der Teil. Für das Beispiel mit den Hosts   und   ist folgender Aufruf notwendig:

Wichtig ist der Aufruf mit dem  (at-Zeichen), welches anzeigt, dass es sich um eine SSH gestützte Kommunikation handelt.

Zuletzt muss die make.conf angepasst werden, damit das passende Programm benutzt.

Es ist nicht notwendig, das Init-Skript auf den teilnehmenden Hosts aufzurufen, wenn  via SSH kommuniziert.

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.

Testen
Um zu testen, kann ein einfaches "Hallo distcc" Programm geschrieben werden und die Übersetzung im ausführlichen Modus gestartet werden um die fehlerfreie Kommunikation zu überprüfen.

Nun ist der ausführliche Modus einzuschalten, der Quelltext zu übersetzen und schlussendlich ein ausführbares Programm mit dem Linker zu erzeugen.

Es sollten eine Menge Ausgaben von über das Auffinden der Konfiguration, Auswahl der teilnehmenden Hosts, das Starten der Übersetzung auf diesen und schlussendlich die Übersetzung von  zu finden sein. Wenn die gewünschten Hosts nicht in der Ausgabe zu finden sind, muss die Konfiguration überprüft werden.

Ein letzter Test stellt sicher, dass das übersetzte Programm fehlerfrei funktioniert.

Fehlersuche
Sollte ein Problem bei der Benutzung von auftreten, sind in diesem Abschnitt Lösungsansätze zur Fehlerbehebung zu finden.

ERROR: failed to open
Seit dem 22.Januar 2015 kann Portage nicht das passende File in  erzeugen. Dieses Verhalten tritt nur bei Version distcc 3.1-r8 auf. Dieser Fehler wird gerade behoben (siehe ): Es ist möglich diesen Fehler zu umgehen, wenn das Log-File manuell erzeugt wird, mit den passenden Zugriffrechten versehen wird und der distccd Daemon neu gestartet wird.

In der Datei ist nun der neue Pfad der Log-Datei  einzutragen.

Neustart des Distccd Service:

Einige Pakete benutzen nicht distcc
Bei der Übersetzung von verschiedenen Paketen kann es vorkommen, das diese nicht verteilt übersetzt werden, sondern nur lokal. Dieses Verhalten tritt auf, wenn das keine parallelen Operationen unterstützt oder der Betreuer des Ebuild parallele Operationen aufgrund bekannter Fehler deaktiviert hat.

Manchmal tritt unerwartet ein Fehler bei einem Paket auf, so das es nicht verteilt übersetzt werden kann. Sollte dies eintreten, kann hier ein [//bugs.gentoo.org Fehlerreport] erstellt werden.

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.

Unterschiedliche GCC-Versionen
Wenn auf den teilnehmenden Hosts unterschiedliche gcc-Versionen aktiv sind, kann es zu sehr seltsamen Fehlern bei der Übersetzung kommen. Um dies zu vermeiden, sind stets nur gleiche gcc-Versionen zur Übersetzung einzusetzen.

Die aktuellen Portage Aktualisierungen benutzen  (minus gcc) anstelle. Werden i686 Rechner im Verbund mit anderen Rechner benutzt (i386, i586) treten sehr wahrscheinlich Probleme bei der Übersetzung auf. Abhilfe kann folgende Anweisung schaffen:

Es ist ebenfalls möglich die CC und CXX Variablen in auf die oben genannten Werte zu setzen.

-march=native
Seit der Version 4.3.0 unterstützt der gcc Compiler die  Option, mit der das übersetzte Programm auf die gerade benutzte CPU optimiert wird. Dies schafft ein Problem, da hier Code erzeugt wird, der für unterschiedliche Prozessoren optimiert ist. Als Beispiel sei das Mixen von AMD-Athlon und Intel-Pentium optimierten Code genannt, wenn auf den beteiligten Rechnern jeweils die Option gesetzt ist.

Daher sollte die folgende Warnung beachtet werden:

Für Hintergrundinformationen sei auf den Abschnitt CFLAGS and CXXFLAGS section und den Blogeintrag Inlining  for distcc verwiesen.

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:

Ausführlichere Ausgaben der emerge Logs
Durch das Einschalten des verbose-Modus werden mehr Logging Ausgaben angezeigt. Die wird durch Hinzufügen der Option DISTCC_VERBOSE in erreicht:

Die Ausgaben können in gefunden werden.

Der erste Aufruf von der in  sichtbar ist, ist nicht notwendigerweise der erste  Aufruf während des Build-Prozesses. Zum Beispiel kann ein Build-Server eine einminütige Auszeit bekommen (BackOff), wenn während der Konfiguration (configure ...) für einige Tests ein Compiler benutzt wird ( sperrt einen Remote Host für eine Minute, wenn dieser nicht erreichbar ist, unabhängig davon ob die Übersetzung auf der lokalen Maschine fehlschlug oder nicht).

Solche Fehler können durch die Analyse von gefunden werden. Alternativ kann händisch im work-Verzeichnis aufgerufen werden.

Eine weitere Option ist DISTCC_SAVE_TEMPS. Wenn diese gesetzt ist, wird die Ausgabe auch der Remote-Rechner im Verzeichnis gespeichert.

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.

Weiterführendes Material

 * [//blogs.gentoo.org/mgorny/2014/06/23/inlining-marchnative-for-distcc/ Inlining  for distcc]
 * [//github.com/distcc/distcc Distcc homepage]