Avis aux courageux, Voici, pour relecture, le premier manuel de distcc. Le deuxième devrait arriver la semaine prochaine : c'est chouette mais c'est long. Ci-jointes une version troff et une version texte générée par « man -l ».
-- Pour info, voici qq précisions sur la VO extraites d'un échange avec le responsable : > In the distcc(1) manpage, description section you wrote : > "For SSH connections distccd me be installed but should not > be listening for connections." > I don't get "distccd me be installed" and I guess it's a typo, but I couldn't > guess whether you mean "distccd may be installed" or "distccd must be > installed". Can you please tell me ? 'must be' > In another paragraph you wrote : > "Because the overhead of distcc and network traffic is low relative to the > work of running the compiler, this can greatly reduce build time." (...) The sentence is not really clear. How about .PP distcc is intended to be used with GNU Make's .B -j option, which runs several compiler processes concurrently. distcc spreads the jobs across both local and remote CPUs. Because distcc is able to distribute most of the work across the network a higher concurrency level can be used than for local builds. The .B -j value should normally be set to about twice the total number of available CPUs, to allow for some tasks being blocked waiting for disk or network IO. distcc can also work with other build control tools such as SCons. -- Lionel Sausin
distcc.1
Description: Troff document
distcc(1) distcc(1) NNAAMMEE distcc - Compilateur C/C++/ObjC réparti SSYYNNOOPPSSIISS ddiissttcccc _<_c_o_m_p_i_l_a_t_e_u_r_> _[_O_P_T_I_O_N_S _D_U _C_O_M_P_I_L_A_T_E_U_R_] ddiissttcccc _[_O_P_T_I_O_N_S _D_U _C_O_M_P_I_L_A_T_E_U_R_] <<ccoommppiilleerr>> _[_O_P_T_I_O_N_S _D_U _C_O_M_P_I_L_A_T_E_U_R_] DDEESSCCRRIIPPTTIIOONN distcc distribue la compilation de code C entre plusieurs machines en réseau. A priori, distcc génère toujours les mêmes exécutables qu'un compilateur local ; il est simple à installer et à utiliser ; enfin il est souvent bien plus rapide qu'une compilation locale. distcc envoi tout le code source prétraité et les paramètres de compilation sur le réseau pour chaque tâche de la construction : les machines n'ont donc pas besoin de partager un système de fichiers, d'avoir les mêmes en-têtes ou bibliothèques installées, ni d'avoir une hor loge synchronisée. La compilation est pilotée par une machine « client », qui est typiquement la station de travail ou l'ordinateur portable du développeur. Le client distcc s'exécute sur cette machine, tout comme make, le préprocesseur, l'éditeur de liens et les autres étapes du processus de construction. Les machines « volontaires », sans limita tion de nombre, aident le client à construire le programme en exécutant le démon ddiissttccccdd((11)),, le compilateur et l'assembleur à la demande. distcc peut s'exécuter soit en utilisant des sockets TCP (sur le port 3632 par défaut), soit grâce à une commande « tunnel » telle que ssh(1). Pour utiliser les connexions TCP les clients doivent exécuter le démon distccd(1) directement ou à partir de inetd. Pour les connections SSH, distcc doit être installé mais nnee doit ppaass rester à l'écoute en attente de connections. Les connexions TCP ne doivent être utilisées que sur un réseau digne de confiance car les codes sources et objet ne sont ni authentifiés ni protégés. Les connexions SSH sont typiquement 25 % plus lentes en raison de la charge supplémentaire due au cryptage, bien que ce nombre varie beaucoup en fonction du processeur, du réseau et du pro gramme construit. distcc est conçu pour s'utiliser avec l'option --jj de GNU Make, qui exécute plusieurs processus de compilation en même temps. Puisque distcc peut répartir la plus grande partie du travail sur le réseau, un plus grand niveau de concurrence est atteint que lors d'une construction locale. On fixe normalement la valeur de l'option --jj à peu près au double du nombre de processeurs disponibles, afin de pouvoir traiter certaines tâches bloquées en attente d'E/S disque ou réseau. distcc peut également être utilisé avec d'autres outils de contrôle de construction tels que SCons. Il est fortement recommandé d'installer la même version du compilateur sur chaque machine participant à la construc tion. Des compilateurs incompatibles peuvent causer des erreurs mystérieuses de compilation et d'édition des liens. DDÉÉMMAARRRRAAGGEE RRAAPPIIDDEE 1 Sur chaque machine : téléchargez distcc, décom pressez-le, et installez-le ; 2 Sur chaque serveur, exécutez ddiissttccccdd ----ddaaeemmoonn avec l'option ----aallllooww pour restreindre l'accès ; 3 Placez les noms des serveurs dans votre environ nement : $ export DISTCC_HOSTS='localhost rouge vert bleu' 4 Lancez la construction ! $ make -j8 CC=distcc FFOONNCCTTIIOONNNNEEMMEENNTT distcc ne répartit que les tâches de compilation et d'assemblage. Le préprocesseur doit toujours s'exécuter localement car il doit accéder à divers fichiers d'en-tête sur la machine locale qui pourraient être absents ou différents sur la volontaire. De même, l'éditeur de liens doit examiner les bibliothèques et les fichiers objets, et doit donc s'exécuter localement. Le compilateur et l'assembleur attendent un seul fichier en entrée (le code source prétraité) et produisent un seul fichier en sortie (le fichier objet). distcc expédie ces deux fichiers sur le réseau et peut ainsi exécuter la com pilation / l'assemblage à distance. Heureusement, pour la majorité des programmes l'exécution du préprocesseur est relativement peu coûteuse et l'éditeur de liens n'est pas appelé souvent, donc la plus grande partie du travail peut être distribuée. distcc examine sa ligne de commande pour déterminer laque lle de ces phases est invoquée, et si la tâche peut être distribué. RRÉÉSSUUMMÉÉ DDEESS OOPPTTIIOONNSS La plupart des options passées à distcc sont interprétées comme des options du compilateur. Deux options sont com prises par distcc lui-même : ----hheellpp Affiche des instructions résumées. ----vveerrssiioonn Affiche la version du client distcc. IINNSSTTAALLLLAATTIIOONN DDEE DDIISSTTCCCC Il y a trois manières d'appeler distcc, qui correspondent à différentes circonstances : distcc peut être installé sous le nom du vrai com pilateur, pour intercepter les appels qui y sont faits et les exécuter à distance. Ce compilateur « masqué » a la plus grande compatibilité avec les arborescences sources existantes, et convient à ceux qui veulent utiliser distcc pour toutes les compilations. L'utilisation de distcc est transpar ente pour les makefiles. distcc peut être utilisé comme préfixe dans les lignes de commandes, telles que « distcc cc -c hello.c » ou « CC="distcc gcc" ». Cela convient à ceux qui n'utilisent distcc que pour certaines compilations ou qui sont en train de l'essayer, mais cela peut pauser des problèmes avec certains makefiles ou certaines versions de libtools qui considèrent que $CC ne contient pas d'espaces. Enfin, distcc peut être utilisé directement comme compilateur. « cc » est toujours utilisé comme nom du vrai compilateur dans ce mode « implicite ». Cela peut convenir pour une utilisation interactive quand le mode « explicite » ne fonctionne pas mais ce n'est pas recommandé aux nouveaux utilisateurs. Gardez à l'esprit que vous ne devez utiliser qu'une seule méthode à la fois pour appeler distcc. Si vous utilisez un répertoire de masquage, ne changez pas CC et/ou CXX : indiquez simplement le répertoire vers le début de votre chemin de recherche (« PATH »). Si vous n'utilisez pas de répertoire de masquage, vous devrez soit changer CC et/ou CXX, soit modifier le(s) makefile(s) pour qu'il(s) appelle(nt) distcc explicitement. MMAASSQQUUAAGGEE Le principe est de créer un « répertoire de masquage » qui contient des liens portant le nom du vrai compilateur et pointant vers l'exécutable de distcc. Ce répertoire est inséré vers le début du chemin de recherche (« PATH »), afin que les appels au compilateur soient interceptés et que distcc soit exécuté à sa place. distcc se retire alors lui-même du chemin de recherche et trouve le vrai compilateur. Par exemple : # mkdir /usr/lib/distcc/bin # cd /usr/lib/distcc/bin # ln -s ../../../bin/distcc gcc # ln -s ../../../bin/distcc cc # ln -s ../../../bin/distcc g++ # ln -s ../../../bin/distcc c++ Ainsi, pour utiliser distcc, un utilisateur doit simple ment placer le répertoire /usr/lib/distcc/bin vers le début du chemin de recherche, et fixer une liste d'hôtes dans DISTCC_HOSTS ou dans un fichier. distcc se charge du reste. Notez que le répertoire de masquage doit se trouver dans le chemin de recherche avant le répertoire contenant le compilateur dont il porte le nom. De plus, tous les pro grammes auxiliaires que ce compilateur utilise (tels que as ou ld) doivent également se trouver dans un répertoire cité après le répertoire de masquage dans le chemin de recherche. En effet, distcc appelle le vrai compilateur avec un chemin de recherche dont sont retirés tous les répertoires jusqu'au répertoire de masquage inclus. Il est possible de rencontrer une « erreur de récursion » dans le mode masqué, ce qui signifie que distcc se trouve lui-même plutôt que de trouver le vrai compilateur. Cela peut indiquer que deux répertoires de masquage sont indiqués dans le chemin de recherche, peut-être à cause de l'installation de distcc à deux emplacement différents. Cela peut également indiquer que vous tentez de mélanger le mode « masqué » et le mode « explicite ». UUTTIILLIISSAATTIIOONN DDEE DDIISSTTCCCC AAVVEECC CCCCAACCHHEE ccache est un programme qui accélère la construction de logiciels en conservant en cache les résultats des compi lations. ccache est normalement appelé avant distcc, afin que les résultats soient tirés d'un cache normal. Le moyen le plus simple d'utiliser ccache avec distcc est de crée un répertoire de masquage pour chacun d'eux, et de lister le répertoire de ccache avant celui de distcc. Par exemple : PPAATTHH==//uussrr//lliibb//ccccaacchhee//bbiinn:://uussrr//lliibb//ddiissttcccc//bbiinn:://uussrr//bbiinn:://bbiinn Une autre solution consiste à fixer CCCCAACCHHEE__PPRREEFFIIXX==ddiissttcccc et à utiliser CCCC==""ccccaacchhee ggcccc"" . Depuis la version 2.2, ccache ne conserve plus la compila tion des sources prétraités, donc il ne trouvera jamais de correspondance dans le cache s'il est exécuté depuis distccd ou distcc. Il ne doit être exécuté que sur le client et avant distcc pour être efficace. SSPPÉÉCCIIFFIICCAATTIIOONNSS DD''HHÔÔTTEESS Une « liste d'hôtes » indique à distcc quelles machines utiliser pour la compilation. distcc consulte, dans l'ordre : la variable d'environnement $$DDIISSTTCCCC__HHOOSSTTSS ;; le fichier ~~//..ddiissttcccc//hhoossttss de l'utilisateur ; puis le fichier d'hôtes du système. Si distcc ne trouve aucune liste d'hôtes, il émet un avertissement et effectue les compila tions localement. La liste d'hôtes est une simple énumération de spécifica tions d'hôtes séparées par des espaces. La forme la plus simple et la plus courante est l'énumération de noms d'hôtes, telle que llooccaallhhoosstt rroouuggee vveerrtt bblleeuu distcc accorde une préférence aux hôtes citées en début de liste, aussi les machines doivent être citées par ordre décroissant de vitesse. En particulier, lorsqu'une seule compilation doit être exécutée (par exemple depuis un script « configure »), la première machine de la liste est utilisée. Du fait de la faible surcharge entraînée par l'exécution des tâches locales, localhost doit normalement être la première. Si le client est largement plus lent que les autres machines (cas d'un ordinateur de poche par exemple), on peut le citer plus loin dans la liste, voire pas du tout. La syntaxe est : HÔTE_DISTCC = SPEC_HÔTE ... SPEC_HÔTE = HÔTE_LOCAL | HÔTE_SSH | HÔTE_TCP | HÔTE_TCP_ANCIENSTYLE HÔTE_LOCAL = localhost[/LIMITE] HÔTE_SSH = [EMAIL PROTECTED]/LIMITE][:COMMANDE][OPTIONS] HÔTE_TCP = IDHÔTE[:PORT][/LIMITE][OPTIONS] HÔTE_TCP_ANCIENSTYLE = IDHÔTE[/LIMITE][:PORT][OPTIONS] IDHÔTE = NOMHÔTE | IPV4 OPTIONS = ,OPTION[OPTIONS] OPTION = lzo Voici quelques exemples de cette syntaxe : llooccaallhhoosstt Le mot réservé « localhost » est interprété spécialement et impose que les compilations soient exécutées directement, plutôt que d'être passées au démon sur la machine locale. Si vous désirez effectivement vous connecter au démon de la machine locale pour effectuer des tests, indiquez l'adresse IP de la machine ou son véritable nom d'hôte. (Ce sera plus lent.) IIPPVV44 Une adresse IPv4 littérale, telle que 1100..00..00..11 NNOOMMHHÔÔTTEE Un nom d'hôte qui sera résolu par le serveur de noms. ::PPOORRTT Établit la connexion au port indiqué en décimal, plutôt qu'au port par défaut 3632. @[EMAIL PROTECTED] Établit la connexion sur SSH plutôt que sur TCP. Les options concernant la connexion SSH peuvent être fixées dans ~~//..sssshh//ccoonnffiigg [EMAIL PROTECTED]@ Établit la connexion sur SSH sous le nom d'utilisa teur indiqué. ::CCOOMMMMAANNDDEE Établit la connexion sur SSH, et utilise le chemin indiqué pour trouver le serveur distccd. Ce n'est normalement nécessaire que si vous ne pouvez pas installer distccd dans un répertoire du chemin de recherche (« PATH ») des connexion SSH. Utilisez cette option si vous rencontrez des erreurs du type « distccd : commande introuvable » en mode SSH. //LLIIMMIITTEE Une limite décimale peut être ajoutée à chaque spécification d'hôte afin de restreindre le nombre de tâches que le client enverra à cette machine. Cette limite est fixée par défaut à quatre tâches par hôte, mais peut être encore réduite par le serveur. Vous ne devriez avoir à augmenter cette valeur que pour les serveurs dotés de plus de deux processeurs. ,,llzzoo Active la compression LZO pour cet hôte TCP ou SSH. Voici un exemple illustrant certaines de ces possi bilités : llooccaallhhoosstt//22 @[EMAIL PROTECTED]//1166:://oopptt//bbiinn//ddiissttccccdd vviieelllleemmaa cchhiinnee::44220000//11 ddiissttaanntt//33,,llzzoo Si un hôte de la liste n'est pas joignable distcc émet un avertissement et ignore cet hôte pendant environs une minute. CCOOMMPPRREESSSSIIOONN L'option d'hôte llzzoo indique que la compression LZO doit être utilisée pour les transferts de données : code source prétraité, code objet et messages d'erreur. La compres sion est généralement économique sur les réseaux dont le débit est inférieur à 100 Mb/s, mais les résultats peuvent varier selon le réseau, les processeurs et l'arborescence source. Activer la compression fait consommer plus de temps CPU par distcc, mais moins de trafic réseau. Le taux de com pression est typiquement de 4/1 pour le code source et 2/1 pour le code objet. L'utilisation de la compression exige que le client et le serveur utilisent tous deux la version 2.9 de distcc ou une version plus récente. Aucune configuration du serveur n'est nécessaire : le serveur répond toujours à des requêtes compressées par des réponses compressées. DDIIAAGGNNOOSSTTIIQQUUEE Les messages d'erreur ou les avertissements des compila teurs locaux ou distants sont transférés à la sortie de diagnostique du client. distcc peut fournir des information de débogage détaillées si l'option « verbose » est employée. On la contrôle grâce à la variable d'environnement DDIISSTTCCCC__VVEERRBBOOSSEE sur le client, et grâce à l'option ----vveerrbboossee sur le serveur. Pour corriger les erreurs, vous devez examiner aussi bien les messages du client que ceux des serveurs. CCOODDEESS DDEE SSOORRTTIIEE Le code de sortie de distcc est normalement celui du com pilateur : zéro pour une compilation menée à bien, non-zéro sinon. distcc distingue les erreurs « authentiques » telles que les erreurs de syntaxe dans le code source, des erreurs « accidentelles » telles que les problèmes de réseau ren contrés lors de la connexion à un volontaire. Dans le cas d'une erreur accidentelle, distcc réessayera la connexion en local à moins que l'option DISTCC_FALLBACK n'ait été désactivée. Si le compilateur se termine avec un signal, distcc retourne un code de sortie de 128 plus le numéro du sig nal. Les erreurs internes de distcc provoquent des codes de sortie entre 100 et 127. En particulier : 100 Échec général de distcc ; 105 Mémoire saturée ; 110 Compilateur introuvable ; 111 Appel récursif à distcc ; 116 Aucun hôte défini et repli (« fallback ») désac tivé. (D'autres codes d'erreur sont listés dans exitcode.h) FFIICCHHIIEERRSS Si $DISTCC_HOSTS n'est pas défini, distcc lit une liste d'hôtes soit dans ~~//..ddiissttcccc//hhoossttss soit dans un fichier système défini à lors de sa compilation. L'emplacement de ce fichier est affiché parmi les informations données par ddiissttcccc ----hheellpp distcc crée un certain nombre de fichiers temporaires et de fichiers de verrouillage dans le répertoire temporaire. VVAARRIIAABBLLEESS DD''EENNVVIIRROONNNNEEMMEENNTT Le comportement de distcc est contrôlé par un certain nom bre de variables d'environnement. Dans la plupart des cas il n'est nécessaire de rien définir si la liste d'hôtes est stockée dans un fichier. DDIISSTTCCCC__HHOOSSTTSS Liste de spécifications d'hôtes, séparées par des espaces. DDIISSTTCCCC__VVEERRBBOOSSEE Si cette variable est fixée à 1, distcc produit un message d'explication sur le flux d'erreur standard ou dans le fichier-journal. Cela peut être utile face à des problèmes de débogage. Les rapports de bogue doivent contenir ce type de message. DDIISSTTCCCC__LLOOGG Fichier-journal destiné à recevoir les messages de distcc lui-même à la place de stderr. DDIISSTTCCCC__FFAALLLLBBAACCKK Par défaut, distcc exécute les compilations en local s'il ne parvient pas à distributer les tâches correspondantes aux machines voulues, ou si aucun hôte n'est trouvable. Si cette variable est fixée à 0, le repli (« fallback ») est désactivé et ces compilations sont simplement abandonnées. Notez que cela n'affecte pas les tâches qui doivent toujours s'exécuter en local telles que l'édition des liens. DDIISSTTCCCC__SSAAVVEE__TTEEMMPPSS Si cette variable est fixée à 1, les fichiers tem poraires sont conservés après utilisation. Utile pour le débogage, ou si vous avez trop de place sur vos disques. DDIISSTTCCCC__TTCCPP__CCOORRKK Si cette variable est fixée à 0, désactive l'utili sation des « bouchons TCP » (« TCP corks »). L'utilisation des bouchons TCP permet de regrouper plusieurs requêtes en un nombre réduit de paquets, ce qui améliore les performances. Elle devrait rester activer. DDIISSTTCCCC__SSSSHH Précise la commande à utiliser pour ouvrir une con nexion SSH. La valeur par défaut est « ssh » mais elle peut être fixée à une autre commande de con nexion telle que « lsh » ou « tsocks-ssh », qui acceptent des lignes de commandes similaires. La commande n'est pas scindée en mots et n'est pas exécutée à travers l'interpréteur de commande (« shell »). TTMMPPDDIIRR Répertoire temporaire du système. distcc crée un sous-répertoire dont le nom comprend le nom d'hôte et l'identifiant de l'utilisateur pour y stocker tous ses fichiers. Par défaut, /tmp/ est utilisé. UUNNCCAACCHHEEDD__EERRRR__FFDD Si cette variable est définie et que DISTCC_LOG n'est pas définie, les erreurs rencontrées par distcc sont inscrites dans le descripteur de fichier identifié par cette variable. Cette option a pour but de permettre aux erreurs passagères telles que les erreurs réseaux de ne pas être placées en cache par ccache. CCOOMMPPIILLAATTIIOONN CCRROOIISSÉÉEE Effectuer une compilation croisée consiste à construire un programme destiné à s'exécuter sur un autre processeur, une autre architecture, ou un autre système d'exploitation que ceux sur lequel il a été compilé. distcc supporte la compilation croisée, y compris l'utilisation de machines d'architectures différentes, bien que certains changements aux lignes de commandes puissent être nécessaires. La commande de compilation passée à distcc doit être apte à s'exécuter correctement sur chacune des machines volon taires pour produire un fichier objet du type approprié. Si les machines ont des processeurs différents, la simple utilisation de ddiissttcccc cccc ne fonctionnera probablement pas, car cela lancera normalement le compilateur natif du volontaire. Des machines ayant le même processeur mais des systèmes d'exploitation différents ne génèrent pas nécessairement des fichiers .o compatibles. Plusieurs configurations différentes de gcc peuvent être installées côte-à-côte sur une machine. Si vous constru isez gcc à partir du code source, utilisez l'option de configuration ----pprrooggrraamm--ssuuffffiixx afin qu'il soit installé sous un nom qui contienne la version de gcc et la plate-forme cible. La convention recommandée pour le nom de gcc est _C_I_B_L_E_-_g_c_c_-_V_E_R_S_I_O_N (par exemple : ii668866--lliinnuuxx--ggcccc--33..22 ). GCC 3.3 s'installera de lui-même sous ce nom, en complément de _C_I_B_L_E_-_g_c_c et, s'il est adapté à la machine locale, de _g_c_c_-_V_E_R_S_I_O_N et de _g_c_c . Le compilateur doit être installé sous le même nom sur le client et sur chaque machine volontaire. BBOOGGUUEESS Si vous pensez avoir rencontré un bug dans distcc, merci de vous reporter au fichier _r_e_p_o_r_t_i_n_g_-_b_u_g_s_._t_x_t dans le répertoire de la documentation pour toute information sur la manière de le rapporter. Du fait d'une limitation de gcc, gdb peut être incapable de trouver automatiquement les fichiers sources des pro grammes construits en utilisant distcc dans certaines cir constances. La commande ddiirreeccttoorryy de gdb peut être utilisée à cet effet. L'option --MMDD de gcc peut produire une sortie dans un mau vais répertoire si les fichiers sources et objets sont dans des répertoires différents et que l'option --MMFF n'est pas utilisée. Il n'y a pas de solution parfaite en raison de changements incompatibles entre les versions de gcc. Indiquer explicitement le fichier de sortie de dépendance avec l'option --MMFF résoudra ce problème. Le mode de connexion TCP ne doit être utilisé que sur les réseaux dignes de confiance. Inscrire des machines lentes dans la liste des volontaires peut ralentir la construction. Utiliser des versions de gcc différentes peut provoquer des problèmes car les fichiers d'en-tête et les interfaces binaires ont évolué, et de plus certaines distributions ont inclu des correctifs incompatibles sans changer le numéro de version. distcc n'offre aucune protection contre l'utilisation de versions incompatibles. Certains makefiles ont des dépendances manquantes ou superflues qui provoquent des constructions en parallèle incorrectes ou lentes. Réparez le makefile en corrigeant les dépendances, rapportez le bogue au responsable du logiciel, ou ne construisez pas l'arborescence en par allèle. D'autres bogues connus peuvent être documentés à l'adresse _h_t_t_p_:_/_/_d_i_s_t_c_c_._s_a_m_b_a_._o_r_g_/ AAUUTTEEUURR distcc a été écrit par Martin Pool <[EMAIL PROTECTED]>, avec la coopération de nombreux érudits dont Wayne Davi son, Frerich Raabe, Dimitri Papadopoulos, et d'autres cités dans le fichier NEWS. Merci de rapporter les bogues à <distcc@lists.samba.org>. LLIICCEENNCCEE Vous êtes libre d'utiliser distcc. Il ne peut être copié, modifié ou distribué que selon les termes de licence publique générale GNU (GPL : « GNU General Public Licence »), version 2 ou suivantes. Une copie [NDT : en anglais] de cette licence est incluse dans le fichier COPYING. VVOOIIRR AAUUSSSSII distccd(1), ccache(1), gcc(1), make(1) _h_t_t_p_:_/_/_d_i_s_t_c_c_._s_a_m_b_a_._o_r_g_/ _h_t_t_p_:_/_/_c_c_a_c_h_e_._s_a_m_b_a_._o_r_g_/ TTRRAADDUUCCTTIIOONN Lionel Sausin. Merci aux participants de la liste Debian-i10n-fr. 12 août 2003 distcc(1)