Документація українською/ man/ man1/ distcc.1

НАЗВА

distcc - розподільний компілятор C/C++/ObjC

ЗВЕДЕННЯ

distcc <компілятор> [КЛЮЧІ КОМПІЛЯТОРА]

distcc [КЛЮЧІ КОМПІЛЯТОРА]

<компілятор> [КЛЮЧІ КОМПІЛЯТОРА]

ОПИС

distcc розподіляє компіляцію C-коду між декількома машинами в мережі. distcc завжди повинна генерувати ті самі результати, що і локальна компіляція, її легко встановити і використовувати, і вона, як правило, набагато швидша ніж локальна компіляція.

distcc надсилає через мережу кожному процесові повністю попередньо оброблений код C разом з аргументами компілятора, тож мережні машини не зобов'язані мати спільної файлової системи, ні тих самих заголовкових файлів і бібліотек, ні синхронізованих годинників.

Компіляція приводиться в дію "клієнтською" машиною, яка типово складається з робочої станції або портативного комп'ютеру розробника. На цій машині повинен знаходитись клієнт distcc так само як make(1), препроцесор, редактор зв'язків та інші стадії процесу компіляції. Клієнтові може допомогти побудувати програму будь-яка кількість "машин-волонтерів", за умови, що на них встановлено демон ?distccd(8), компілятор C і асемблер.

distcc може працювати або через сокети TCP (на 3632-у порту поза вибором), або через тунельну команду як ssh(1). Для TCP-з'єднань, на добровольцях має бути запущено демон distccd, або безпосередньо, або через inetd(8). Для SSH-сполучень потрібно, щоб distcc було інстальовано, але не чекало на з'єднання.

TCP-сполучення можна використовувати тільки в захищених мережах, оскільки автентифікація користувачів чи захист вихідного коду бракують. SSH-зв'язок, як правило, на 25% повільніший з-за витрат процесорного часу на шифрування, хоча це значення змінюватися в залежності від процесора, мережі та програми, яка компілюється.

distcc задумано для використання з ключем -j програми make(1) GNU, що дозволяє запустити декілька одночасних процесів компіляції. distcc поширює свої завдання як на локальний(і), так і на віддалені процесори. Через те що distcc спроможна розподілити більшу частину роботи через мережу, це дозволяє використати більший паралелізм для локальних побудов. Значення, яке отримає -j, має дорівнювати сумі процесорів помножено на два, щоб дозволити блокування деяких завдань, через затримку вводу/виводу диска або мережі. distcc може співпрацювати також з іншими знаряддями керування побудовою, як от SCons.

Ми настійно рекомендуємо встановити на всіх машинах ту саму версію компілятора. Несумісні компілятори можуть призвести до загадкових провалів компіляції чи зв'язки.

ШВИДКИЙ СТАРТ

  1. : Для кожної машини завантажте distcc, розархівуйте та інсталюйте її.

  2. : На кожному сервері виконайте distccd --daemon, можна з опцією --allow, щоб обмежити доступ (дивіться ?distccd(8)).

  3. : Додайте імена серверів до вашого середовища:

    $ export DISTCC_HOSTS='localhost red green blue'

  4. : Почніть розподілену побудову вашої програми:

    $ make -j8 CC=distcc

ЯК ВОНО ВСЕ ПРАЦЮЄ

distcc віддалено користується тільки компілятором і асемблером. Препроцесор завжди повинен виконуватись локально, оскільки йому потрібний доступ до різноманітних заголовкових файлів на локальній машині, яких може бракувати або відрізнятися на віддалених. Редактор зв'язків так само повинен вивчити бібліотеки та об'єктні файли, а отже виконуватиметься локально.

Компілятор і асемблер візьмуть тільки один файл вводу (попередньо оброблений препроцесором вихідний текст) і зпродукують один (об'єктний) файл виводу. distcc лише транспортує ці два файли через мережу, і тому може віддалено використовувати компілятор/асемблер.

На щастя для більшості програм, робота препроцесора відносно нересурсоємка, і редактор зв'язків викликається порівняно рідко, тож більшість роботи можна росзосередити.

distcc вивчає командний рядок, щоб визначити, яка з цих фаз зараз викликано, і чи можна розподілити це завдання.

ПІДСУМОК ОПЦІЙ

Більшість опцій переданих distcc інтерпретуються як опції компілятора. Однак, дві з них зрозумілі самій distcc:

ІНСТАЛЯЦІЯ DISTCC

Існує три відмінних способи викликати distcc, щоб задовольнити різні обставини: .IP distcc можна встановити під іменем справжнього компілятора, щоб перехоплювати виклики до нього, і виконувати їх віддалено. Цей "замаскований" компілятор найбільш сумісний з уже наявними структурами вихідного тексту, і зручний, коли ви хочете використовувати distcc. для всіх компіляцій. Той факт, що застосовується distcc залишатиметься непомітним (прозорим) для make-файлів. .IP distcc можна додати попереду виклику компілятора на командному рядку, як от "distcc cc -c hello.c" або CC="distcc gcc". Це зручно коли ви хочете використати distcc тільки для деяких компіляцій чи спробувати її, але може спричинити до проблем з деякими make-файлами або версіями libtool, які гадають, що $CC не містить пробілів. .IP Нарешті, distcc можна використати безпосередньо як компілятор. "cc" завжди використовується як назва справжнього компілятора в цей "непрямий" спосіб. Це може виявитись зручним для інтерактивного використання, коли "явний" спосіб не спрацьовує, але не рекомендується новим користувачам.

--help : Виведе коротку інструкцію по використанню.

--version : Виведе версію distcc-клієнта.

Пам'ятайте, що не можна користуватися двома різними методами виклику distcc одночасно. Використовуючи замаскований каталог, не змінюйте CC і/або CXX, просто додайте зарані цей каталог до змінної PATH. Коли замаскований каталог не використовується, вам треба або змінити CC і/або CXX, або редагувати makefile-и для безпосереднього виклику distcc.

МАСКУВАННЯ

Основна ідея полягає у створенні "замаскованого каталогу", який міститиме посилання з назви справжнього компілятора на бінарний файл distcc. Цей каталог слід завчасно додати до PATH, щоб перехопити виклики компілятора і виконувати distcc натомість. distcc сама видалить себе з PATH, щоб знайти справжній компілятор.

Наприклад:

  1. mkdir /usr/lib/distcc/bin
  2. cd /usr/lib/distcc/bin
  3. ln -s ../../../bin/distcc gcc
  4. ln -s ../../../bin/distcc cc
  5. ln -s ../../../bin/distcc g++
  6. ln -s ../../../bin/distcc c++

Тепер, для використання distcc користувачеві залишилось додати /usr/lib/distcc/bin до PATH, і назви машин до DISTCC_HOSTS або якогось файла. distcc впорається з рештою.

Пам'ятайте: цей замаскований каталог повинен з'являтися в PATH раніше ніж каталог, що містить дійсний компілятор, те саме стосується допоміжних програм які може викликати цей компілятор (таких як ?as(1) чи ?ld(1)), їхній каталог також має стояти після замаскованого, оскільки після того як distcc викличе справжній компілятор, замаскований каталог буде видалено з PATH.

Також, можна отримати помилку рекурсії (recursion error) в режимі "маскування", що означає, що distcc якимось чином знаходить тільки саму себе, а не справжній компілятор. Це може означати, що ви або маєте два маскованих каталоги в PATH (можливо того, що встановили distcc двічі в різних каталогах). Це також може означати, що ви намагаєтесь змішати обидва, "маскований" і "явний" режими роботи.

ВИКОРИСТАННЯ DISTCC РАЗОМ ІЗ CCACHE

ccache(1) - це програма, що прискорює побудову з вихідного коду шляхом кешування наслідків компіляції. ccache, зазвичай, викликають до distcc, щоб результати можна було здобути з нормального кешу. В деякій мірі, може знадобитися трохи експериментування з ідіотськими make-файлами для того, щоб змусити все працювати разом.

Найбільш надійний спосіб, це задати змінну середовища

CCACHE_PREFIX="distcc"

Це вказує ccache використати distcc як обгортку навколо справжнього компілятора. ccache все ж користується справжнім компілятором, щоб виявити зміну версії і вдосконалення.

Після цього, ccache можна запустити або через маскований каталог (дивіться ccache(1)), або встановивши

CC="ccache gcc"

Починаючи з версії 2.2, ccache не кешує компіляції обробленого препроцесором вихідного коду, тож ніколи не отримає попадання в кеш, якщо запущена з distccd або distcc. Її слід використовувати тільки на клієнтському боці і до distcc, щоб мати з неї якусь користь.

ПЕРЕЛІК ВУЗЛІВ

"Список вузлів" вказує distcc які машини використати для компіляції. distcc шукає його в змінній середовища $DISTCC_HOSTS, користувацькому файлі $DISTCC_DIR/hosts, і загальносистемному файлі host, саме в цій послідовності. Якщо жодного списку не знайдено, distcc видасть попередження і компілюватиме локально.

Список вузлів, простий, розділений пробілами перелік специфікацій машин. Найпростіша та найпоширеніша форма, це просто назви машин, як

localhost red green blue

distcc надає перевагу машинам на початку списку, тож їх слід вказувати в послідовності зменшення швидкості (спочатку швидші). Зокрема, коли можна виконати тільки одну компіляцію (як скажімо зі сценарію configure), буде використано першу машину в переліку.

Щоб добитися хорошої швидкості, важливо вказати localhost (локальну машину) першою в списку. Оскільки затримка при виконанні завдань локально незначна, localhost звичайно має стояти перший. Однак, важливо, щоб клієнт мав досить (процесорних) циклів як для виконання локальних завдань, так і для роботи distcc. Коли клієнт повільніший за добровольців, або коли добровольців багато, тоді клієнта можна розмістити далі по списку або не додавати взагалі. Як загальне правило, якщо агрегатна швидкість процесора клієнта менша за одну п'яту загальної, тоді клієнта можна усунути зі списку.

Швидкість також залежить від деталей вихідного коду та make-файлів, і від підставової машини та швидкості (пропускної здатності) мережі. Ефективність може дещо покращитись, якщо поекспериментувати з різними настройками вузлів і параметром ключа -j програми make(1).

Використовується наступний синтаксис:

DISTCC_HOSTS = СПЕЦИФІКАЦІЯ ...
СПЕЦИФІКАЦІЯ = ЛОКАЛЬНА_МАШИНА | SSH_МАШИНА | TCP_МАШИНА
               | TCP_МАШИНА_СТАРОГО_СТИЛЮ
ЛОКАЛЬНА_МАШИНА = localhost[/ОБМЕЖЕННЯ]
SSH_МАШИНА = [КОРИСТУВАЧ]@МАШИНА[/ОБМЕЖЕННЯ][:КОМАНДА][ОПЦІЇ]
TCP_МАШИНА = МАШИНА[:ПОРТ][/ОБМЕЖЕННЯ][ОПЦІЇ]
TCP_МАШИНА_СТАРОГО_СТИЛЮ = МАШИНА[/ОБМЕЖЕННЯ][:ПОРТ][ОПЦІЇ]
МАШИНА = НАЗВА | IPV4
ОПЦІЇ = ,ОПЦІЯ[ОПЦІЇ]
ОПЦІЯ = lzo

Ось докладніше пояснення синтаксису:

localhost : Слово "localhost" інтерпретується як спеціальне, зумовлюючи безпосереднє виконання компіляцій замість передачі їх демону на локальній машині. Якщо ж вам для тестування треба сполучитися з демоном на локальній машині, тоді вкажіть IP-адресу машини чи її мережну назву. (Це працюватиме повільніше.)

IPV4 : Буквальна IPV4-адреса, як 10.0.0.1.

@МАШИНА : Сполучення з вузлом через SSH замість TCP. Параметри SSH-з'єднання можна задати в ~/.ssh/config (дивіться ?ssh config(5)).

КОРИСТУВАЧ@> КОМАНДА: Сполучитися через SSH, і скористатися вказаним у КОМАНДІ шляхом для знаходження distccd-сервера. Це звичайно потрібно коли ви з якихось причин не змогли інсталювати distccd у каталозі, внесеному в PATH. Скористайтеся з цього, коли ви отримали помилку "distccd: command not found" (команди не знайдено) в SSH-режимі.

: Сполучитися з вузлом через SSH як вказаний користувач.

/ОБМЕЖЕННЯ : Дозволяє вказати обмеження (як десяткове ціле) кількості завдань, які клієнт надсилатиме цій машині. Поза вибором, обмеження складатиме по чотири завдання на вузол (два для localhost), але це значення може бути зменшене сервером. Ви можете збільшити його тільки для серверів з більш як двома процесорами.

,lzo : Робить можливим LZO-компресію для TCP або SSH-сполучень.

Ось приклад, що ілюструє деякі можливості:

localhost/2 @bigman/16:/opt/bin/distccd oldmachine:4200/1
# cartman is down
distant/3,lzo

У переліку вузлів дозволяються коментарі. Коментарі починаються з гратки (#) і продовжуються до кінця рядка.

Якщо машина зі списку недосяжна, distcc видасть попередження і на хвилину проігнорує цей вузол.

СТИСНЕННЯ

Якщо за назвою вузла вказана опція lzo, тоді для передачі даних, включаючи попередньо оброблений вихідний код, об'єктний код і повідомлення про помилки, використовуватиметься алгоритм стиснення LZO. Стискання звичайно буває ефективне, коли мережа повільніша за 100Мб/с, але результати можуть відрізнятися в залежності від мережі, процесорів, структури вихідного тексту.

Уможливлення компресії призводить до більшого використання клієнтом і сервером distcc процесорного часу, але до меншого навантаження на мережу. Коефіцієнт стискання, типово, дорівнює 4:1 для вихідного тексту і 2:1 для об'єктного коду.

Застосування компресії вимагає, щоб обидва, клієнт і сервер, використовували щонайменше 2.9-у версію distcc.

ШЛЯХИ ПОШУКУ ПРОГРАМ

Якщо назва компілятора вказана як абсолютний шлях до нього, її буде передано без змін сервера, і компілятор запускатиметься з цього каталогу. Наприклад:

distcc /usr/local/bin/gcc-3.1415 -c hello.c

Коли назва компілятора не складається з абсолютного шляху, відбудеться пошук каталогів PATH сервера distccd. Якщо distcc запущено з маскованого каталогу, використовуватиметься тільки базове ім'я компілятора. Клієнтська змінна PATH використовується тільки для запуску препроцесора, і не має жодного впливу на PATH сервера.

ЛІМІТ ЧАСУ

Обидва, клієнт і сервер distcc, накладають певне обмеження часу на передачу даних через мережу. Це робиться заради того, щоб виявити недосяжні вузли, запобігти необмеженому зависанню компіляторів, коли сервер від'єднано під час використання. Якщо ліміт часу, визначений клієнтом, вийшов, це завдання буде виконано локально.

На дану мить, ліміт часу неможливо настроїти (його на стале компільовано в програму).

ДІАГНОСТИКА

Повідомлення про помилки або попередження локального та віддалених компіляторів передаються діагностичному виводові клієнта.

distcc може забезпечити докладною зневаджувальною інформацією, коли вказати багатослівний режим. Цього можна досягти з допомогою змінної середовища DISTCC_VERBOSE на клієнті і опції --verbose на сервері. Для виявлення несправностей, перегляньте повідомлення як клієнта, так і сервера.

КОДИ ЗАВЕРШЕННЯ

Код виходу distcc, як правило, відповідає кодові виходу компілятора: нуль означає успішну компіляцію, ненульове значення означає помилку.

distcc розрізняє "справжні" помилки, як от синтаксична помилка у вихідному тексті, і "випадкових" помилок, як нездатність сполучитися з вузлом через мережу. У разі "випадкової" помилки, distcc спробує локальну компіляцію, хіба що опцію DISTCC_FALLBACK скасовано.

Якщо компілятор завершив свою роботу із якимось сигналом, distcc поверне код виходу 128 плюс номер сигналу, отриманого від компілятора.

Внутрішні помилки самої distcc спричиняють до кодів завершення зі значеннями від 100 до 127. Зокрема:

100 : Загальна помилка distcc.

105 : Не залишилось вільної пам'яті.

110 : Компілятор не знайдено.

111 : Рекурсивний виклик distcc.

116 : Не вказано жодного вузла й, одночасно, скасовано DISTCC_FALLBACK.

(Решту ви знайдете в exitcode.h.)

ФАЙЛИ

Якщо змінної $DISTCC_HOSTS не встановлено, distcc спробує прочитати список вузлів або в $DISTCC_DIR/hosts, або в загальносистемному файлі конфігурації, вказаному під час компіляції. Про місцезнаходження цих файлів можна дізнатися за допомогою команди distcc --help.

distcc створює певну кількість тимчасових та блокувальних файлів у тимчасовому каталозі.

ЗМІННІ СЕРЕДОВИЩА

На поводження distcc впливають кілька змінних середовища. В більшості випадків, нічого не треба встановлювати, коли список вузлів збережено у файлі.

ПЕРЕХРЕСНА КОМПІЛЯЦІЯ

Перехресна компіляція означає побудову програм для машин з відмінним процесором, архітектурою, або операційною системою від того, де вони компілюються. distcc підтримує перехресну компіляцію, включаючи групи машин з різною архітектурою, хоча це може вимагати деяких змін команд компіляції.

DISTCC_HOSTS : Розділений пробілами список специфікацій машин-волонтерів.

DISTCC_VERBOSE : Якщо набуде значення 1, distcc виводитиме докладні повідомлення про все, що відбувається, на стандартний пристрій помилок чи журнальний файл. Це може бути корисним при зневадженні.

DISTCC_LOG : Журнальний файл, де записуватимуться повідомлення distcc, замість виводу їх на стандартний пристрій помилок.

DISTCC_FALLBACK : Типово, distcc компілюватиме локально, якщо не вдасться розподілити завдання між волонтерами, або якщо не знайдено списку вузлів. Якщо присвоїти цій змінній значення 0, то такий відступ буде неможливим, і компіляція просто зазнає невдачі. Зауважте, що це не впливає завдання, які завжди мають виконуватись локально, як редагування зв'язків.

DISTCC_SAVE_TEMPS : Якщо набуде значення 1, тимчасові файли не видаляються після використання. Добре для зневадження, або коли ваш твердий диск занадто порожній.

DISTCC_TCP_CORK : Якщо отримає значення 0, це зробить неможливим використання "корків TCP", навіть якщо ця властивість підтримується системою. Використання корків, як правило, допомагає укласти звернення в меншу кількість пакетів, що збільшує ефективність. Тому, цю рису краще дозволити.

DISTCC_SSH : Вказує команду для відкриття SSH-сполучень. Стандартним значенням є "ssh", яке можна замінити на іншу команду, як "lsh" або "tsocks-ssh". Команда не розбивається на окремі слова і не виконується оболонкою.

DISTCC_DIR : Користувацький конфігураційний каталог, де зберігатимуться блокувальні та файли стану. Стандартно, використовується ~/.distcc/.

TMPDIR : Каталог для тимчасових файлів, таких як вивід препроцесора. Стандартно, використовується /tmp/.

UNCACHED_ERR_FD : Якщо встановлено цю змінну, а DISTCC_LOG - ні, тоді помилки distcc записуватимуться до дескриптора файла, вказаного цією змінною. Ця змінна призначається, головним чином, для використання ccache, яка встановлює її, щоб запобігти кешуванню короткочасних помилок, як от проблем, пов'язаних з мережею.

Компіляційна команда, передана distcc має бути такою, яку можна правильно виконати на будь-якій волонтерській машині, і це утворить об'єктний файл певного типу. Якщо машини мають різні процесори, то простого distcc cc може не вистачити, оскільки це викличе волонтерський рідний компілятор.

Машини з однаковим процесором, але різними операційними системами, так само не обов'язково утворять сумісні об'єктні файли.

Можна встановити декілька конфігурацій gcc на кожній з машин. Якщо ви будуєте gcc з сирців, вам треба скористатися конфігураційної опції --program-suffix, щоб інсталювати gcc з назвою, що включає в собі версію та цільову платформу.

Рекомендованою умовністю для назви gcc є ПЛАТФОРМА-gcc-ВЕРСІЯ, як от i686-linux-gcc-3.2. GCC 3.3 автоматично інсталює себе під таким іменем, на додачу до ПЛАТФОРМА-gcc, та, якщо це рідна інсталяція, gcc-ВЕРСІЯ та gcc.

Компілятор із такою самою назвою має бути встановлено як на клієнті, так і на кожній машині-волонтері.

ВАДИ

Якщо ви вважаєте, що знайшли блоху в distcc, тоді передивіться файл reporting-bugs.txt в каталозі з документацією, для інформації щодо звітів про помилки.

Деякі make-файли мають недосить або зайві залежності, що призводить до неправильних або повільних паралельних побудов. Рекурсивні команди make неефективні, і можуть призвести до тривалого простоювання процесорів. (Дивіться статтю "Recursive Make Considered Harmful" Пітера Міллера.) Помилки в make-файлах являються основною причиною неспроможності побудови структур вихідного коду з distcc. Альтернативи make, такі як SCons можуть значно пришвидшити побудову деяких проектів.

Використання відмінних версій gcc може спричинити заплутані проблеми з побудовою, з-за зміни з часом заголовкових файлів і бінарних інтерфейсів, і того, що деякі дистрибутори включили несумісні латки без зміни номера версії програми. distcc не може захистити вас від використання несумісних версій. Помилки компілятора щодо посилань чи оголошень в системних заголовкових файлах завдячують, як правило, неузгодженим або неправильно встановленим компіляторам.

Внаслідок обмежень gcc, gdb за деяких обставин не може автоматично знайти вихідні тексти програм, побудованих з допомогою distcc. В такому разі можна використати команду directory gdb. Це мають виправити в GCC 3.4.

Опція -MD gcc може спричинити вивід в помилковому каталозі, якщо вихідний текст і об'єктні файли знаходяться в різних каталогах і не вказано ключ -MF. У цьому випадку, не існує ідеального рішення з-за несумісних змін в різних версіях gcc. Явне вказування файла виводу залежностей опцією -MF має усунути цю проблему.

TCP-сполучення слід використовувати тільки в надійних мережах.

Включення повільних машин у список вузлів може сповільнити побудову.

Коли distcc із ccache використовуються з NFS, файлову систему слід експортувати з опцією no_subtree_check, щоб добитися надійних змін назв серед каталогів.

Компілятор можна викликати командою gcc hello.c, щоб компілювати і зв'язати одночасно. distcc не розбиває цей процес на окремі частини, натомість виконує все це локально.

Опис інших відомих помилок можна знайти на http://distcc.samba.org/.

АВТОР

distcc було написано Мартіном Пулом mbp@sourcefrog.net спільно з багатьма науковцями, включаючи Вейна Дейвідсона, Фреріча Рабе, Дмітрія Пападопулуса та інших, згаданих у файлі NEWS. Будь ласка, повідомляйте про помилки за адресою distcc@lists.samba.org.

ЛІЦЕНЗІЯ

Ви вільні користуватися distcc. distcc (ця сторінка посібника включно) можна копіювати, змінювати та розповсюджувати згідно з умовами GNU General Public Licence версії 2 або більше. distcc надано без жодних гарантій. Копію GPL включено у файл COPYING.

ДИВІТЬСЯ ТАКОЖ

?distccd(1), ccache(1), ?gcc(1), make(1) http://distcc.samba.org/ http://ccache.samba.org/