1distcc(1)                   General Commands Manual                  distcc(1)
2
3
4

NAME

6       distcc - distributed C/C++/ObjC compiler with distcc-pump extensions
7

SYNOPSIS

9       distcc <compiler> [COMPILER OPTIONS]
10
11       distcc [COMPILER OPTIONS]
12
13       <compiler> [COMPILER OPTIONS]
14
15       distcc [DISTCC OPTIONS]
16

DESCRIPTION

18       distcc  distributes  compilation of C code across several machines on a
19       network.  distcc should always generate the same  results  as  a  local
20       compile,  it  is simple to install and use, and it is often much faster
21       than a local compile.
22
23       This version incorporates plain distcc as well as an enhancement called
24       pump mode or distcc-pump.
25
26       For  each  job,  distcc  in  plain mode sends the complete preprocessed
27       source code and compiler arguments across the network from  the  client
28       to  a  compilation  server.  In pump mode, distcc sends the source code
29       and recursively included header files (excluding those from the default
30       system  header directories), so that both preprocessing and compilation
31       can take place on the compilation servers. This speeds up the  delivery
32       of compilations by up to an order of magnitude over plain distcc.
33
34       Compilation  is  driven  by  a  client  machine, which is typically the
35       developer's workstation or laptop.  The  distcc  client  runs  on  this
36       machine,  as  does make, the preprocessor (if distcc's pump mode is not
37       used), the linker, and other stages of the build process.   Any  number
38       of volunteer machines act as compilation servers and help the client to
39       build the program, by running the distccd(1)  daemon,  C  compiler  and
40       assembler as required.
41
42       distcc  can run across either TCP sockets (on port 3632 by default), or
43       through a tunnel command such as ssh(1).  For TCP connections the  vol‐
44       unteers  must  run the distccd(1) daemon either directly or from inetd.
45       For SSH connections distccd must be installed but should not be listen‐
46       ing for connections.
47
48       TCP connections should only be used on secure networks because there is
49       no user authentication or protection of source  or  object  code.   SSH
50       connections are slower.
51
52       distcc  is  intended  to  be used with GNU Make's -j option, which runs
53       several compiler  processes  concurrently.   distcc  spreads  the  jobs
54       across  both local and remote CPUs.  Because distcc is able to distrib‐
55       ute most of the work across the network, a higher concurrency level can
56       be used than for local builds.  As a rule of thumb, the -j value should
57       be set to about twice the total number of  available  server  CPUs  but
58       subject  to client limitations.  This setting allows for maximal inter‐
59       leaving of tasks being blocked waiting for disk  or  network  IO.  Note
60       that  distcc  can  also  work  with  other build control tools, such as
61       SCons, where similar concurrency settings must be adjusted.
62
63       The -j setting, especially for large  values  of  -j,  must  take  into
64       account  the CPU load on the client.  Additional measures may be needed
65       to curtail the client load.  For example, concurrent linking should  be
66       severely  curtailed  using  auxiliary locks.  The effect of other build
67       activity, such as Java compilation when building mixed code, should  be
68       considered.   The  --localslots_cpp  parameter  is by default set to 8.
69       This limits the number of concurrent processes that do preprocessing in
70       plain  distcc  (non-pump) mode.  Therefore, larger -j values than 8 may
71       be used without overloading a single-CPU client due  to  preprocessing.
72       Such large values may speed up parts of the build that do not involve C
73       compilations, but they may not be useful to distcc efficiency in  plain
74       mode.
75
76       In  contrast,  using pump mode and say 40 servers, a setting of -j80 or
77       larger may be appropriate even for single-CPU clients.
78
79       It is strongly recommended that you install the same  compiler  version
80       on  all  machines participating in a build.  Incompatible compilers may
81       cause mysterious compile or link failures.
82

QUICKSTART

84       1      For each machine, download distcc, unpack, and install.
85
86       2      On each of  the  servers,  run  distccd  --daemon  with  --allow
87              options to restrict access.
88
89       3      Put the names of the servers in your environment:
90              $ export DISTCC_HOSTS='localhost red green blue'
91
92       4      Build!
93              $ make -j8 CC=distcc
94

QUICKSTART FOR DISTCC-PUMP MODE

96       Proceed  as  above, but in Step 3, specify that the remote hosts are to
97       carry the burden of preprocessing and that the files sent over the net‐
98       work should be compressed:
99
100              $   export   DISTCC_HOSTS='--randomize   localhost   red,cpp,lzo
101              green,cpp,lzo blue,cpp,lzo'
102
103       The --randomize option enforces a uniform  usage  of  compile  servers.
104       While you will get some benefit from distcc's pump mode with only a few
105       servers, you get increasing benefit with more server CPUs  (up  to  the
106       hundreds!).   Wrap your build inside the pump command, here assuming 10
107       servers:
108
109              $ pump make -j20 CC=distcc
110
111

QUICKSTART FOR DISTCC-GSSAPI MODE

113       Proceed as per the QUICKSTART but in Step 3, specify  that  the  remote
114       hosts are to mutually authenticate with the client:
115
116              $ export DISTCC_HOSTS='--randomize localhost red,auth green,auth
117              blue,auth'
118
119       If distccd runs under a specific principal name then execute  the  fol‐
120       lowing command prior to step 4:
121
122              export DISTCC_PRINICIPAL=<name>
123
124

HOW PLAIN (NON-PUMP) DISTCC WORKS

126       distcc  only ever runs the compiler and assembler remotely.  With plain
127       distcc, the preprocessor must always run locally because  it  needs  to
128       access  various  header  files  on  the  local machine which may not be
129       present, or may not be the same, on the volunteer.   The  linker  simi‐
130       larly  needs  to  examine  libraries  and object files, and so must run
131       locally.
132
133       The compiler and assembler take only a single input file  (the  prepro‐
134       cessed  source)  and produce a single output (the object file).  distcc
135       ships these two files across the network and can therefore run the com‐
136       piler/assembler remotely.
137
138       Fortunately,  for  most programs running the preprocessor is relatively
139       cheap, and the linker is called relatively infrequent, so most  of  the
140       work can be distributed.
141
142       distcc examines its command line to determine which of these phases are
143       being invoked, and whether the job can be distributed.
144
145

HOW DISTCC-PUMP MODE WORKS

147       In pump mode, distcc runs the preprocessor remotely too.  To do so, the
148       preprocessor  must  have  access  to  all  the files that it would have
149       accessed if had been running locally.  In pump mode, therefore,  distcc
150       gathers  all  of the recursively included headers, except the ones that
151       are default system headers, and sends them along with the  source  file
152       to the compilation server.
153
154       In  distcc-pump mode, the server unpacks the set of all source files in
155       a temporary directory, which contains a directory tree that mirrors the
156       part  of  the  file system that is relevant to preprocessing, including
157       symbolic links.
158
159       The compiler is then run from the path in the temporary directory  that
160       corresponds  to  the  current working directory on the client.  To find
161       and transmit the many hundreds of files that are often part of a single
162       compilation,  pump mode uses an incremental include analysis algorithm.
163       The include server is a Python program that implements this  algorithm.
164       The pump command starts the include server so that throughout the build
165       it can answer include queries by distcc commands.
166
167       The include server uses static analysis of the macro language  to  deal
168       with  conditional compilation and computed includes.  It uses the prop‐
169       erty that when a given  header  file  has  already  been  analyzed  for
170       includes, it is not necessary to do so again if all the include options
171       (-I's) are unchanged (along with other conditions).
172
173       For large builds, header files are included, on  average,  hundreds  of
174       times each. With distcc-pump mode each such file is analyzed only a few
175       times, perhaps just once, instead of  being  preprocessed  hundreds  of
176       times.   Also,  each source or header file is now compressed only once,
177       because the include server memoizes the compressed files.  As a result,
178       the  time used for preparing compilations may drop by up to an order of
179       magnitude over the preprocessing of plain distcc.
180
181       Because distcc in pump mode is able to push out files up to  about  ten
182       times faster, build speed may increase 3X or more for large builds com‐
183       pared to plain distcc mode.
184
185

RESTRICTIONS FOR PUMP MODE

187       Using pump mode requires both client and servers to use release 3.0  or
188       later of distcc and distccd (respectively).
189
190       The incremental include analysis of distc-pump mode rests on the funda‐
191       mental assumption that source and header files do not change during the
192       build  process.   A  few  complex build systems, such as that for Linux
193       kernel 2.6, do not quite satisfy this requirement.   To  overcome  such
194       issues,  and other corner cases such as absolute filepaths in includes,
195       see the include_server(1) man page.
196
197       Another important assumption is that the include configuration  of  all
198       machines  must be identical.  Thus the headers under the default system
199       path must be the same on all servers and all clients.   If  a  standard
200       GNU compiler installation is used, then this requirement applies to all
201       libraries whose  header  files  are  installed  under  /usr/include  or
202       /usr/local/include/.  Note that installing software packages often lead
203       to additional headers files being placed in subdirectories of either.
204
205       If this assumption does not hold, then it is possible to  break  builds
206       with  distcc-pump mode, or worse, to get wrong results without warning.
207       Presently this condition is not verified, and it is on our TODO list to
208       address this issue.
209
210       An  easy way to guarantee that the include configurations are identical
211       is to use a cross-compiler that defines a default  system  search  path
212       restricted to directories of the compiler installation.
213
214       See  the  include_server(1) manual for more information on symptoms and
215       causes of violations of distcc-pump mode assumptions.
216
217

HOW DISTCC-GSSAPI MODE WORKS

219       In this mode distcc will use the GSS-API framework to access  the  cur‐
220       rently  configured security mechanism and perform mutual authentication
221       with the daemon.
222
223

OPTION SUMMARY

225       Most options passed to distcc are interpreted as compiler options.  The
226       following  options  are  understood  by distcc itself.  If any of these
227       options are specified, distcc will not invoke the compiler.
228
229
230       --help Displays summary instructions.
231
232       --version
233              Displays the distcc client version.
234
235       --show-hosts
236              Displays the host list that distcc  would  use.   See  the  Host
237              Specifications section.
238
239       --scan-includes
240              Displays  the list of files that distcc would send to the remote
241              machine, as computed by the include server.  This is a conserva‐
242              tive (over-)approximation of the files that would be read by the
243              C compiler.  This option only works in pump mode.  See the  "How
244              Distcc-pump  Mode Works" section for details on how this is com‐
245              puted.
246
247              The list output by distcc --scan-includes will contain one entry
248              per  line.   Each  line  contains a category followed by a path.
249              The category is one of FILE, SYMLINK, DIRECTORY, or SYSTEMDIR:
250
251                     FILE indicates a source file or header file that would be
252                     sent to the distcc server host.
253
254                     SYMLINK  indicates  a symbolic link that would be sent to
255                     the distcc server host.
256
257                     DIRECTORY indicates a directory that  may  be  needed  in
258                     order  to compile the source file.  For example, a direc‐
259                     tory "foo" may be needed because of  an  include  of  the
260                     form  #include "foo/../bar.h".  Such directories would be
261                     created on the distcc server host.
262
263                     SYSTEMDIR indicates a system include  directory,  i.e.  a
264                     directory  which  is  on  the  compiler's default include
265                     path,  such  as  "/usr/include";  such  directories   are
266                     assumed  to  be present on the distcc server host, and so
267                     would not be sent to the distcc server host.
268
269       -j     Displays distcc's concurrency level, as calculated from the host
270              list;  it  is  the  maximum number of outstanding jobs issued by
271              this client to all servers.  By default this will be four  times
272              the  number  of hosts in the host list, unless the /LIMIT option
273              was used in the host list.  See the Host Specifications section.
274
275       --show-principal
276              Displays the name of the distccd  security  principal  extracted
277              from  the  environment.  This option is only available if distcc
278              was compiled with the --with-auth configure option.
279
280

INSTALLING DISTCC

282       There are three different ways to call distcc, to suit  different  cir‐
283       cumstances:
284
285              distcc  can be installed under the name of the real compiler, to
286              intercept calls to it and run them remotely.  This "masqueraded"
287              compiler  has  the  widest  compatibility  with  existing source
288              trees, and is convenient when you want to  use  distcc  for  all
289              compilation.   The fact that distcc is being used is transparent
290              to the makefiles.
291
292              distcc can be prepended  to  compiler  command  lines,  such  as
293              "distcc  cc  -c hello.c" or CC="distcc gcc".  This is convenient
294              when you want to use distcc for only some compilations or to try
295              it out, but can cause trouble with some makefiles or versions of
296              libtool that assume $CC does not contain a space.
297
298              Finally, distcc can be used directly as  a  compiler.   "cc"  is
299              always  used as the name of the real compiler in this "implicit"
300              mode.   This  can  be  convenient  for  interactive   use   when
301              "explicit"  mode does not work but is not really recommended for
302              new use.
303
304       Remember that you should not use two methods for calling distcc at  the
305       same  time.   If  you are using a masquerade directory, don't change CC
306       and/or CXX, just put the directory early on your PATH.  If  you're  not
307       using  a  masquerade  directory, you'll need to either change CC and/or
308       CXX, or modify the makefile(s) to call distcc explicitly.
309

MASQUERADING

311       The basic idea is to create a  "masquerade  directory"  which  contains
312       links  from  the  name of the real compiler to the distcc binary.  This
313       directory is inserted early on the PATH, so that calls to the  compiler
314       are  intercepted and distcc is run instead.  distcc then removes itself
315       from the PATH to find the real compiler.
316
317       For example:
318
319              # mkdir /usr/lib/distcc/bin
320              # cd /usr/lib/distcc/bin
321              # ln -s ../../../bin/distcc gcc
322              # ln -s ../../../bin/distcc cc
323              # ln -s ../../../bin/distcc g++
324              # ln -s ../../../bin/distcc c++
325
326       Then,  to  use  distcc,  a  user  just  needs  to  put  the   directory
327       /usr/lib/distcc/bin  early  in  the  PATH,  and have set a host list in
328       DISTCC_HOSTS or a file.  distcc will handle the rest.
329
330       To automatically discover compilers and create masquerade links run the
331       provided update-distcc-symlinks script.
332
333       Note that this masquerade directory must occur on the PATH earlier than
334       the directory that contains the actual compilers of the same names, and
335       that  any  auxiliary  programs that these compilers call (such as as or
336       ld) must also be found on the PATH in a directory after the  masquerade
337       directory since distcc calls out to the real compiler with a PATH value
338       that has all directory up to and  including  the  masquerade  directory
339       trimmed off.
340
341       It  is  possible  to  get a "recursion error" in masquerade mode, which
342       means that distcc is somehow finding itself again, not  the  real  com‐
343       piler.   This  can indicate that you have two masquerade directories on
344       the PATH, possibly because of having two distcc installations  in  dif‐
345       ferent locations.  It can also indicate that you're trying to mix "mas‐
346       queraded" and "explicit" operation.
347
348       Recursion errors can be avoided  by  using  shell  scripts  instead  of
349       links.  For example, in /usr/lib/distcc/bin create a file cc which con‐
350       tains:
351
352              #!/bin/sh
353              distcc /usr/bin/gcc "$@"
354
355       In this way, we are not dependent on distcc having to locate  the  real
356       gcc  by investigating the PATH variable. Instead, the compiler location
357       is explicitly provided.
358
359

USING DISTCC WITH CCACHE

361       ccache is a program that speeds software builds by caching the  results
362       of  compilations.   ccache  is  normally  called before distcc, so that
363       results are retrieved from a normal cache.  Some experimentation may be
364       required for idiosyncratic makefiles to make everything work together.
365
366       The most reliable method is to set
367
368              CCACHE_PREFIX="distcc"
369
370       This  tells ccache to run distcc as a wrapper around the real compiler.
371       ccache still uses the real compiler to detect compiler upgrades.
372
373       ccache  can then be run using either a masquerade directory or by  set‐
374       ting
375
376              CC="ccache gcc"
377
378       As  of version 2.2, ccache does not cache compilation from preprocessed
379       source and so will never get a cache hit if it is run from  distccd  or
380       distcc.  It must be run only on the client side and before distcc to be
381       any use.
382
383       distcc's pump mode is not compatible with ccache.
384

HOST SPECIFICATIONS

386       A "host list" tells distcc which machines to use for  compilation.   In
387       order,  distcc  looks  in  the  $DISTCC_HOSTS environment variable, the
388       user's $DISTCC_DIR/hosts file, and the system-wide host  file.   If  no
389       host list can be found, distcc emits a warning and compiles locally.
390
391       The  host list is a simple whitespace separated list of host specifica‐
392       tions.  The simplest and most common form is a host names, such as
393
394              localhost red green blue
395
396       distcc prefers hosts towards the start of the list, so machines  should
397       be  listed  in  descending  order of speed.  In particular, when only a
398       single compilation can be run (such as from a  configure  script),  the
399       first machine listed is used (but see --randomize below).
400
401       Placing  localhost  at the right point in the list is important to get‐
402       ting good performance.  Because overhead for running  jobs  locally  is
403       low, localhost should normally be first.  However, it is important that
404       the client have enough cycles free to run the local jobs and the distcc
405       client.   If  the client is slower than the volunteers, or if there are
406       many volunteers, then the client should be put later in the list or not
407       at all.  As a general rule, if the aggregate CPU speed of the client is
408       less than one fifth of the total, then the client should be left out of
409       the list.
410
411       If  you  have  a  large  shared build cluster and a single shared hosts
412       file, the above rules would cause the first few machines in  the  hosts
413       file  to  be  tried first even though they are likely to be busier than
414       machines later in the list.  To avoid this, place the keyword --random‐
415       ize  into  the  host list.  This will cause the host list to be random‐
416       ized, which should improve performance slightly for large  build  clus‐
417       ters.
418
419       There  are  two  special  host  names --localslots and --localslots_cpp
420       which are useful for adjusting load on the local machine.  The --local‐
421       slots host specifies how many jobs that cannot be run remotely that can
422       be run concurrently on the local machine, while  --localslots_cpp  con‐
423       trols how many preprocessors will run in parallel on the local machine.
424       Tuning these values can improve performance.  Linking on large projects
425       can take large amounts of memory.  Running parallel linkers, which can‐
426       not be executed remotely,  may force the machine to swap, which reduces
427       performance  over  just  running the jobs in sequence without swapping.
428       Getting the number of parallel preprocessors just right allows  you  to
429       use  larger parallel factors with make, since the local machine now has
430       some mechanism for measuring local resource usage.
431
432       Finally there is the host entry
433
434       Performance depends on the details of the source and makefiles used for
435       the  project,  and  the machine and network speeds.  Experimenting with
436       different settings for the host list and -j factor may improve  perfor‐
437       mance.
438
439       The syntax is
440
441         DISTCC_HOSTS = HOSTSPEC ...
442         HOSTSPEC = LOCAL_HOST | SSH_HOST | TCP_HOST | OLDSTYLE_TCP_HOST
443                               | GLOBAL_OPTION
444                               | ZEROCONF
445         LOCAL_HOST = localhost[/LIMIT]
446                    | --localslots=<int>
447                    | --localslots_cpp=<int>
448         SSH_HOST = [USER]@HOSTID[/LIMIT][:COMMAND][OPTIONS]
449         TCP_HOST = HOSTID[:PORT][/LIMIT][OPTIONS]
450         OLDSTYLE_TCP_HOST = HOSTID[/LIMIT][:PORT][OPTIONS]
451         HOSTID = HOSTNAME | IPV4 | IPV6
452         OPTIONS = ,OPTION[OPTIONS]
453         OPTION = lzo | cpp | auth[=AUTH_NAME]
454         GLOBAL_OPTION = --randomize
455         ZEROCONF = +zeroconf
456
457       Here are some individual examples of the syntax:
458
459       localhost
460              The  literal  word "localhost" is interpreted specially to cause
461              compilations to be directly executed, rather than  passed  to  a
462              daemon  on  the  local  machine.  If you do want to connect to a
463              daemon on the local machine for testing, then give the machine's
464              IP address or real hostname.  (This will be slower.)
465
466       IPV6   A  literal  IPv6  address  enclosed  in square brackets, such as
467              [::1]
468
469       IPV4   A literal IPv4 address, such as 10.0.0.1
470
471       HOSTNAME
472              A hostname to be looked up using the resolver.
473
474       :PORT  Connect to a specified decimal  port  number,  rather  than  the
475              default of 3632.
476
477       @HOSTID
478              Connect  to the host over SSH, rather than TCP.  Options for the
479              SSH connection can be set in ~/.ssh/config
480
481       USER@  Connect to the host over SSH as a specified username.
482
483       :COMMAND
484              Connect over SSH, and use a specified path to find  the  distccd
485              server.   This  is  normally  only needed if for some reason you
486              can't install distccd into a directory on the default  PATH  for
487              SSH connections.  Use this if you get errors like "distccd: com‐
488              mand not found" in SSH mode.
489
490       /LIMIT A decimal limit can  be  added  to  any  host  specification  to
491              restrict  the  number  of jobs that this client will send to the
492              machine.  The limit defaults to four per host  (two  for  local‐
493              host),  but may be further restricted by the server.  You should
494              only need to increase this for servers with more than  two  pro‐
495              cessors.
496
497       ,lzo   Enables LZO compression for this TCP or SSH host.
498
499       ,cpp   Enables distcc-pump mode for this host.  Note: the build command
500              must be wrapped in the pump script in order to start the include
501              server.
502
503       ,auth  Enables GSSAPI-based mutual authentication for this host.
504
505       AUTH_NAME
506              The  "canonical"  name  to  use  for  the service principal name
507              instead of HOSTNAME (or its corresponding fqdn). This option  is
508              useful in case of accessing an authenticated server via ssh port
509              forwarding, in which case the HOSTNAME is 127.0.0.1.
510
511       --randomize
512              Randomize the order of the host list before execution.
513
514       +zeroconf
515              This option is only available if distcc was compiled with  Avahi
516              support  enabled  at configure time.  When this special entry is
517              present in the hosts list, distcc will use  Avahi  Zeroconf  DNS
518              Service  Discovery  (DNS-SD)  to  locate  any  available distccd
519              servers on the local network.  This avoids the need  to  explic‐
520              itly  list  the  host names or IP addresses of the distcc server
521              machines.  The distccd servers must have been started  with  the
522              "--zeroconf"  option to distccd.  An important caveat is that in
523              the current implementation, pump mode (",cpp")  and  compression
524              (",lzo") will never be used for hosts located via zeroconf.
525
526       Here is an example demonstrating some possibilities:
527
528              localhost/2 @bigman/16:/opt/bin/distccd oldmachine:4200/1
529              # cartman is down
530              distant/3,lzo
531
532       Comments  are  allowed  in  host specifications.  Comments start with a
533       hash/pound sign (#) and run to the end of the line.
534
535       If a host in the list is not reachable distcc will emit a  warning  and
536       ignore that host for about one minute.
537

COMPRESSION

539       The  lzo  host option specifies that LZO compression should be used for
540       data transfer, including preprocessed source,  object  code  and  error
541       messages.   Compression  is  usually economical on networks slower than
542       100Mbps, but results may vary depending on the network, processors  and
543       source tree.
544
545       Enabling  compression  makes  the distcc client and server use more CPU
546       time, but less network traffic.  The added CPU  time  is  insignificant
547       for  pump  mode.  The compression ratio is typically 4:1 for source and
548       2:1 for object code.
549
550       Using compression requires both client  and  server  to  use  at  least
551       release 2.9 of distcc.  No server configuration is required: the server
552       always responds with compressed replies to compressed requests.
553
554       Pump mode requires the servers to have the lzo host option on.
555

SEARCH PATHS

557       If the compiler name is an absolute path, it is passed verbatim to  the
558       server and the compiler is run from that directory.  For example:
559
560              distcc /usr/local/bin/gcc-3.1415 -c hello.c
561
562       If the compiler name is not absolute, or not fully qualified, distccd's
563       PATH is searched.  When distcc is run from a masquerade directory, only
564       the  base name of the compiler is used.  The client's PATH is used only
565       to run the preprocessor and has no effect on the server's path.
566

TIMEOUTS

568       Both the distcc client and server impose timeouts on transfer  of  data
569       across the network.  This is intended to detect hosts which are down or
570       unreachable, and to prevent compiles hanging indefinitely if  a  server
571       is  disconnected  while  in use.  If a client-side timeout expires, the
572       job will be re-run locally.
573
574       The transfer timeout is not configurable at present. The  timeout  that
575       detects  stale  distributed  job  is configurable via DISTCC_IO_TIMEOUT
576       environment variable.
577

DIAGNOSTICS

579       Error messages or warnings from local or remote  compilers  are  passed
580       through to diagnostic output on the client.
581
582       distcc  can  supply  extensive  debugging  information when the verbose
583       option is used.  This is controlled by the  DISTCC_VERBOSE  environment
584       variable  on  the  client, and the --verbose option on the server.  For
585       troubleshooting, examine both the client and server error messages.
586

EXIT CODES

588       The exit code of distcc is normally that of the compiler: zero for suc‐
589       cessful compilation and non-zero otherwise.
590
591       distcc distinguishes between "genuine" errors such as a syntax error in
592       the source, and "accidental" errors such as a networking  problem  con‐
593       necting  to a volunteer.  In the case of accidental errors, distcc will
594       retry the compilation locally unless  the  DISTCC_FALLBACK  option  has
595       been disabled.
596
597       If the compiler exits with a signal, distcc returns an exit code of 128
598       plus the signal number.
599
600       distcc internal errors cause an exit code between 100 and 127.  In par‐
601       ticular
602
603       100    General distcc failure.
604
605       101    Bad arguments.
606
607       102    Bind failed.
608
609       103    Connect failed.
610
611       104    Compiler crashed.
612
613       105    Out of memory.
614
615       106    Bad Host SPEC
616
617       107    I/O Error
618
619       108    Truncated.
620
621       109    Protocol Error.
622
623       110    The given compiler was not found on the remote host.  Check that
624              $CC is set appropriately and that it's installed in a  directory
625              on the search path for distccd.
626
627       111    Recursive call to distcc.
628
629       112    Failed to discard privileges.
630
631       113    Network access denied.
632
633       114    In use by another process.
634
635       115    No such file.
636
637       116    No hosts defined and fallbacks disabled.
638
639       118    Timeout.
640
641       119    GSS-API - Catchall error code for GSS-API related errors.
642
643       120    Called for preprocessing, which needs to be done locally.
644
645

FILES

647       If  $DISTCC_HOSTS  is  not  set,  distcc  reads a host list from either
648       $DISTCC_DIR/hosts or a system-wide configuration file  set  at  compile
649       time.  The file locations are shown in the output from distcc --help
650
651       distcc creates a number of temporary and lock files underneath the tem‐
652       porary directory.
653

ENVIRONMENT VARIABLES

655       distcc's behaviour is controlled by a number of environment  variables.
656       For  most  cases  nothing  need  be set if the host list is stored in a
657       file.
658
659       DISTCC_HOSTS
660              Space-separated list of volunteer host specifications.
661
662       DISTCC_VERBOSE
663              If set to 1, distcc produces explanatory messages on  the  stan‐
664              dard  error  stream  or in the log file.  This can be helpful in
665              debugging problems.  Bug reports should include verbose output.
666
667       DISTCC_LOG
668              Log file to receive messages from  distcc  itself,  rather  than
669              stderr.
670
671       DISTCC_FALLBACK
672              By default distcc will compile locally if it fails to distribute
673              a job to the intended machine, or if no host list can be  found.
674              If  this  variable  is  set to 0 then fallbacks are disabled and
675              those compilations will simply fail.  Note that  this  does  not
676              affect jobs which must always be local such as linking.
677
678       DISTCC_NO_CROSS_REWRITE
679              By  default distcc will rewrite calls gcc to use fully qualified
680              names (like x86_64-linux-gnu-gcc), and clang to use the  -target
681              option. Setting this turns that off.
682
683       DISTCC_BACKOFF_PERIOD
684              Specifies  how long (in seconds) distcc will avoid trying to use
685              a particular compilation server after that server yields a  com‐
686              pile  failure.   By  default  set to 60 seconds.  To disable the
687              backoff behavior altogether, set this to 0.
688
689       DISTCC_IO_TIMEOUT
690              Specifies how long (in seconds) distcc will wait before deciding
691              a  distributed  job  has  timed  out.   If  a distributed job is
692              expected to takes a long time, consider increasing this value so
693              the  job  does not time out and fallback to a local compile.  By
694              default set to 300 seconds.
695
696       DISTCC_PAUSE_TIME_MSEC
697              Specifies how long (in milliseconds) distcc will pause when  all
698              compilation  servers  are  in  use.  By default set to 1000 mil‐
699              liseconds (1 second).  Setting this to a smaller value (e.g.  10
700              milliconds)  may  improve throughput for some configurations, at
701              the expense of increased CPU load on the distcc client machine.
702
703       DISTCC_SAVE_TEMPS
704              If set to 1, temporary files are not deleted  after  use.   Good
705              for debugging, or if your disks are too empty.
706
707       DISTCC_TCP_CORK
708              If set to 0, disable use of "TCP corks", even if they're present
709              on this system.  Using corks normally helps pack  requests  into
710              fewer  packets  and  aids  performance.  This should normally be
711              left enabled.
712
713       DISTCC_SSH
714              Specifies  the  command  used  for  opening   SSH   connections.
715              Defaults  to "ssh" but may be set to a different connection com‐
716              mand such as "lsh" or "tsocks-ssh" that accepts a  similar  com‐
717              mand  line.  The command is not split into words and is not exe‐
718              cuted through the shell.
719
720       DISTCC_SKIP_LOCAL_RETRY
721              If set, when a remote compile fails, distcc will no  longer  try
722              to recompile that file locally.
723
724       DISTCC_DIR
725              Per-user  configuration  directory to store lock files and state
726              files.  By default ~/.distcc/ is used.
727
728       TMPDIR Directory for temporary files such as preprocessor  output.   By
729              default /tmp/ is used.
730
731       UNCACHED_ERR_FD
732              If  set  and if DISTCC_LOG is not set, distcc errors are written
733              to the file descriptor identified by this variable.  This  vari‐
734              able  is intended mainly for automatic use by ccache, which sets
735              it to avoid caching transient errors such as network problems.
736
737       DISTCC_ENABLE_DISCREPANCY_EMAIL
738              If  set,  distcc  sends  an  email  when  a  compilation  failed
739              remotely,  but  succeeded  locally.  Built-in heuristics prevent
740              some such discrepancy email from being sent if  the  problem  is
741              that a local file changed between the failing remote compilation
742              and the succeeding local compilation.
743
744       DISTCC_MAX_DISCREPANCY
745              The maximum number of remote  compilation  failures  allowed  in
746              pump  mode  before  distcc  switches  to  plain  distcc mode. By
747              default set to 1.
748
749       DCC_EMAILLOG_WHOM_TO_BLAME
750              The email address for discrepancy email; the default is "distcc-
751              pump-errors".
752
753       DISTCC_PRINCIPAL
754              If  set,  specifies  the name of the principal that distccd runs
755              under, and is used to authenticate the  server  to  the  client.
756              This  environment  variable  is only used if distcc was compiled
757              with the --with-auth configure option and  the  ,auth  per  host
758              option is specified.
759

CROSS COMPILING

761       Cross  compilation  means  building programs to run on a machine with a
762       different processor, architecture, or operating system  to  where  they
763       were  compiled.   distcc supports cross compilation, including teams of
764       mixed-architecture machines, although some changes to  the  compilation
765       commands may be required.
766
767       The  compilation command passed to distcc must be one that will execute
768       properly on every volunteer machine to produce an object  file  of  the
769       appropriate type.  If the machines have different processors, then sim‐
770       ply using distcc cc will probably not work, because that will  normally
771       invoke the volunteer's native compiler.
772
773       Machines with the same CPU but different operating systems may not nec‐
774       essarily generate compatible .o files.
775
776       Several different gcc configurations can be installed  side-by-side  on
777       any  machine.   If you build gcc from source, you should use the --pro‐
778       gram-suffix configuration options to cause it to be  installed  with  a
779       name that encodes the gcc version and the target platform.
780
781       The  recommended convention for the gcc name is TARGET-gcc-VERSION such
782       as i686-linux-gcc-3.2 .  GCC 3.3 will install itself under  this  name,
783       in addition to TARGET-gcc and, if it's native, gcc-VERSION and gcc .
784
785       The compiler must be installed under the same name on the client and on
786       every volunteer machine.
787

BUGS

789       If you think you have found a  distcc bug, please see the file  report‐
790       ing-bugs.txt  in  the documentation directory for information on how to
791       report it.
792
793       Some makefiles have missing or extra dependencies that cause  incorrect
794       or  slow  parallel builds.  Recursive make is inefficient and can leave
795       processors unnecessarily idle for long periods.   (See  Recursive  Make
796       Considered Harmful by Peter Miller.)  Makefile bugs are the most common
797       cause of trees failing to build under  distcc.   Alternatives  to  Make
798       such as SCons can give much faster builds for some projects.
799
800       Using  different  versions  of  gcc  can cause confusing build problems
801       because the header files and binary interfaces have changed over  time,
802       and some distributors have included incompatible patches without chang‐
803       ing the version number.  distcc does not protect against  using  incom‐
804       patible  versions.  Compiler errors about link problems or declarations
805       in system header files are usually due  to  mismatched  or  incorrectly
806       installed compilers.
807
808       gcc's  -MD  option  can  produce  output  in the wrong directory if the
809       source and object files are in different directories and the -MF option
810       is  not  used.   There  is  no perfect solution because of incompatible
811       changes between gcc versions.   Explicitly  specifying  the  dependency
812       output file with -MF will fix the problem.
813
814       TCP mode connections should only be used on trusted networks.
815
816       Including  slow  machines  in  the list of volunteer hosts can slow the
817       build down.
818
819       When distcc or ccache is used on NFS, the filesystem must  be  exported
820       with  the  no_subtree_check  option  to  allow reliable renames between
821       directories.
822
823       The compiler can be invoked with a command line  gcc  hello.c  to  both
824       compile  and  link.  distcc doesn't split this into separate parts, but
825       rather runs the whole thing locally.
826
827       distcc-pump mode reverts to plain distcc mode  for  source  files  that
828       contain includes with absolute paths (either directly or in an included
829       file).
830
831       Due to limitations in gcc, gdb may not be able  to  automatically  find
832       the source files for programs built using distcc in some circumstances.
833       The gdb directory command can be used.  For distcc's  plain  (non-pump)
834       mode,  this  is  fixed in gcc 3.4 and later.  For pump mode, the fix in
835       gcc 3.4 does not suffice; we've worked around  the  gcc  limitation  by
836       rewriting the object files that gcc produces, but this is only done for
837       ELF object files, but not for other object file formats.
838
839       The .o files produced by discc in pump  mode  will  be  different  from
840       those  produced  locally: for non-ELF files, the debug information will
841       specify compile directories of the server.  The code itself  should  be
842       identical.
843
844       For  the  ELF-format,  distcc  rewrites the .o files to correct compile
845       directory path information.  While the resulting .o files are not byte‐
846       wise  identical  to  what  would have been produced by compiling on the
847       local client (due to different padding, etc), they should be  function‐
848       ally identical.
849
850       In  distcc-pump  mode,  the  include server is unable to handle certain
851       very complicated computed includes as  found  in  parts  of  the  Boost
852       library.  The  include  server  will time out and distcc will revert to
853       plain mode.
854
855       In distcc-pump mode, certain  assumptions  are  made  that  source  and
856       header files do not change during the build.  See discussion in section
857       DISTCC DISCREPANCY SYMPTOMS of include_server(1().
858
859       Other known bugs may be documented on http://code.google.com/p/distcc/
860

AUTHOR

862       distcc was written by Martin Pool <mbp@sourcefrog.net>,  with  the  co-
863       operation of many scholars including Wayne Davison, Frerich Raabe, Dim‐
864       itri Papadopoulos and others noted in the  NEWS  file.   Please  report
865       bugs  to <distcc@lists.samba.org>.  See pump(1) for the authors of pump
866       mode.
867

LICENCE

869       You are free to use distcc.  distcc  (including  this  manual)  may  be
870       copied, modified or distributed only under the terms of the GNU General
871       Public Licence version 2 or later.  distcc  comes  with  absolutely  no
872       warrany.  A copy of the GPL is included in the file COPYING.
873

SEE ALSO

875       distccd(1),    pump(1),   include_server(1),   gcc(1),   make(1),   and
876       ccache(1).  http://code.google.com/p/distcc/ https://ccache.dev/
877
878
879
880                                  9 June 2008                        distcc(1)
Impressum