1distcc(1) General Commands Manual distcc(1)
2
6 distcc - distributed C/C++/ObjC compiler with distcc-pump extensions
7
9 distcc <compiler> [COMPILER OPTIONS]
10 distcc [COMPILER OPTIONS]
12 <compiler> [COMPILER OPTIONS]
14 distcc [DISTCC OPTIONS]
16
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 This version incorporates plain distcc as well as an enhancement called
24 pump mode or distcc-pump.
25 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 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 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 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 typically 25% slower because of processor overhead for
51 encryption, although this can vary greatly depending on CPUs, network
52 and the program being built.
53 distcc is intended to be used with GNU Make's -j option, which runs
55 several compiler processes concurrently. distcc spreads the jobs
56 across both local and remote CPUs. Because distcc is able to distrib‐
57 ute most of the work across the network, a higher concurrency level can
58 be used than for local builds. As a rule of thumb, the -j value should
59 be set to about twice the total number of available server CPUs but
60 subject to client limitations. This setting allows for maximal inter‐
61 leaving of tasks being blocked waiting for disk or network IO. Note
62 that distcc can also work with other build control tools, such as
63 SCons, where similar concurrency settings must be adjusted.
64 The -j setting, especially for large values of -j, must take into
66 account the CPU load on the client. Additional measures may be needed
67 to curtail the client load. For example, concurrent linking should be
68 severely curtailed using auxiliary locks. The effect of other build
69 activity, such as Java compilation when building mixed code, should be
70 considered. The --localslots_cpp parameter is by default set to 16.
71 This limits the number of concurrent processes that do preprocessing in
72 plain distcc (non-pump) mode. Therefore, larger -j values than 16 may
73 be used without overloading a single-CPU client due to preprocessing.
74 Such large values may speed up parts of the build that do not involve C
75 compilations, but they may not be useful to distcc efficiency in plain
76 mode.
77 In contrast, using pump mode and say 40 servers, a setting of -j80 or
79 larger may be appropriate even for single-CPU clients.
80 It is strongly recommended that you install the same compiler version
82 on all machines participating in a build. Incompatible compilers may
83 cause mysterious compile or link failures.
84
86 1 For each machine, download distcc, unpack, and install.
87 2 On each of the servers, run distccd --daemon with --allow
89 options to restrict access.
90 3 Put the names of the servers in your environment:
92 $ export DISTCC_HOSTS='localhost red green blue'
93 4 Build!
95 $ make -j8 CC=distcc
96
98 Proceed as above, but in Step 3, specify that the remote hosts are to
99 carry the burden of preprocessing and that the files sent over the net‐
100 work should be compressed:
101 $ export DISTCC_HOSTS='--randomize localhost red,cpp,lzo
103 green,cpp,lzo blue,cpp,lzo'
104 The --randomize option enforces a uniform usage of compile servers.
106 While you will get some benefit from distcc's pump mode with only a few
107 servers, you get increasing benefit with more server CPUs (up to the
108 hundreds!). Wrap your build inside the pump command, here assuming 10
109 servers:
110 $ pump make -j20 CC=distcc
112
115 Proceed as per the QUICKSTART but in Step 3, specify that the remote
116 hosts are to mutually authenticate with the client:
117 $ export DISTCC_HOSTS='--randomize localhost red,auth green,auth
119 blue,auth'
120 If distccd runs under a specific principal name then execute the fol‐
122 lowing command prior to step 4:
123 export DISTCC_PRINICIPAL=<name>
125
128 distcc only ever runs the compiler and assembler remotely. With plain
129 distcc, the preprocessor must always run locally because it needs to
130 access various header files on the local machine which may not be
131 present, or may not be the same, on the volunteer. The linker simi‐
132 larly needs to examine libraries and object files, and so must run
133 locally.
134 The compiler and assembler take only a single input file (the prepro‐
136 cessed source) and produce a single output (the object file). distcc
137 ships these two files across the network and can therefore run the com‐
138 piler/assembler remotely.
139 Fortunately, for most programs running the preprocessor is relatively
141 cheap, and the linker is called relatively infrequent, so most of the
142 work can be distributed.
143 distcc examines its command line to determine which of these phases are
145 being invoked, and whether the job can be distributed.
146
149 In pump mode, distcc runs the preprocessor remotely too. To do so, the
150 preprocessor must have access to all the files that it would have
151 accessed if had been running locally. In pump mode, therefore, distcc
152 gathers all of the recursively included headers, except the ones that
153 are default system headers, and sends them along with the source file
154 to the compilation server.
155 In distcc-pump mode, the server unpacks the set of all source files in
157 a temporary directory, which contains a directory tree that mirrors the
158 part of the file system that is relevant to preprocessing, including
159 symbolic links.
160 The compiler is then run from the path in the temporary directory that
162 corresponds to the current working directory on the client. To find
163 and transmit the many hundreds of files that are often part of a single
164 compilation, pump mode uses an incremental include analysis algorithm.
165 The include server is a Python program that implements this algorithm.
166 The pump command starts the include server so that throughout the build
167 it can answer include queries by distcc commands.
168 The include server uses static analysis of the macro language to deal
170 with conditional compilation and computed includes. It uses the prop‐
171 erty that when a given header file has already been analyzed for
172 includes, it is not necessary to do so again if all the include options
173 (-I's) are unchanged (along with other conditions).
174 For large builds, header files are included, on average, hundreds of
176 times each. With distcc-pump mode each such file is analyzed only a few
177 times, perhaps just once, instead of being preprocessed hundreds of
178 times. Also, each source or header file is now compressed only once,
179 because the include server memoizes the compressed files. As a result,
180 the time used for preparing compilations may drop by up to an order of
181 magnitude over the preprocessing of plain distcc.
182 Because distcc in pump mode is able to push out files up to about ten
184 times faster, build speed may increase 3X or more for large builds com‐
185 pared to plain distcc mode.
186
189 Using pump mode requires both client and servers to use release 3.0 or
190 later of distcc and distccd (respectively).
191 The incremental include analysis of distc-pump mode rests on the funda‐
193 mental assumption that source and header files do not change during the
194 build process. A few complex build systems, such as that for Linux
195 kernel 2.6, do not quite satisfy this requirement. To overcome such
196 issues, and other corner cases such as absolute filepaths in includes,
197 see the include_server(1) man page.
198 Another important assumption is that the include configuration of all
200 machines must be identical. Thus the headers under the default system
201 path must be the same on all servers and all clients. If a standard
202 GNU compiler installation is used, then this requirement applies to all
203 libraries whose header files are installed under /usr/include or
204 /usr/local/include/. Note that installing software packages often lead
205 to additional headers files being placed in subdirectories of either.
206 If this assumption does not hold, then it is possible to break builds
208 with distcc-pump mode, or worse, to get wrong results without warning.
209 Presently this condition is not verified, and it is on our TODO list to
210 address this issue.
211 An easy way to guarantee that the include configurations are identical
213 is to use a cross-compiler that defines a default system search path
214 restricted to directories of the compiler installation.
215 See the include_server(1) manual for more information on symptoms and
217 causes of violations of distcc-pump mode assumptions.
218
221 In this mode distcc will use the GSS-API framework to access the cur‐
222 rently configured security mechanism and perform mutual authentication
223 with the daemon.
224
227 Most options passed to distcc are interpreted as compiler options. The
228 following options are understood by distcc itself. If any of these
229 options are specified, distcc will not invoke the compiler.
230 --help Displays summary instructions.
233 --version
235 Displays the distcc client version.
236 --show-hosts
238 Displays the host list that distcc would use. See the Host
239 Specifications section.
240 --scan-includes
242 Displays the list of files that distcc would send to the remote
243 machine, as computed by the include server. This is a conserva‐
244 tive (over-)approximation of the files that would be read by the
245 C compiler. This option only works in pump mode. See the "How
246 Distcc-pump Mode Works" section for details on how this is com‐
247 puted.
248 The list output by distcc --scan-includes will contain one entry
250 per line. Each line contains a category followed by a path.
251 The category is one of FILE, SYMLINK, DIRECTORY, or SYSTEMDIR:
252 FILE indicates a source file or header file that would be
254 sent to the distcc server host.
255 SYMLINK indicates a symbolic link that would be sent to
257 the distcc server host.
258 DIRECTORY indicates a directory that may be needed in
260 order to compile the source file. For example, a direc‐
261 tory "foo" may be needed because of an include of the
262 form #include "foo/../bar.h". Such directories would be
263 created on the distcc server host.
264 SYSTEMDIR indicates a system include directory, i.e. a
266 directory which is on the compiler's default include
267 path, such as "/usr/include"; such directories are
268 assumed to be present on the distcc server host, and so
269 would not be sent to the distcc server host.
270 -j Displays distcc's concurrency level, as calculated from the host
272 list; it is the maximum number of outstanding jobs issued by
273 this client to all servers. By default this will be four times
274 the number of hosts in the host list, unless the /LIMIT option
275 was used in the host list. See the Host Specifications section.
276 --show-principal
278 Displays the name of the distccd security principal extracted
279 from the environment. This option is only available if distcc
280 was compiled with the --with-auth configure option.
281
284 There are three different ways to call distcc, to suit different cir‐
285 cumstances:
286 distcc can be installed under the name of the real compiler, to
288 intercept calls to it and run them remotely. This "masqueraded"
289 compiler has the widest compatibility with existing source
290 trees, and is convenient when you want to use distcc for all
291 compilation. The fact that distcc is being used is transparent
292 to the makefiles.
293 distcc can be prepended to compiler command lines, such as
295 "distcc cc -c hello.c" or CC="distcc gcc". This is convenient
296 when you want to use distcc for only some compilations or to try
297 it out, but can cause trouble with some makefiles or versions of
298 libtool that assume $CC does not contain a space.
299 Finally, distcc can be used directly as a compiler. "cc" is
301 always used as the name of the real compiler in this "implicit"
302 mode. This can be convenient for interactive use when
303 "explicit" mode does not work but is not really recommended for
304 new use.
305 Remember that you should not use two methods for calling distcc at the
307 same time. If you are using a masquerade directory, don't change CC
308 and/or CXX, just put the directory early on your PATH. If you're not
309 using a masquerade directory, you'll need to either change CC and/or
310 CXX, or modify the makefile(s) to call distcc explicitly.
311
313 The basic idea is to create a "masquerade directory" which contains
314 links from the name of the real compiler to the distcc binary. This
315 directory is inserted early on the PATH, so that calls to the compiler
316 are intercepted and distcc is run instead. distcc then removes itself
317 from the PATH to find the real compiler.
318 For example:
320 # mkdir /usr/lib/distcc/bin
322 # cd /usr/lib/distcc/bin
323 # ln -s ../../../bin/distcc gcc
324 # ln -s ../../../bin/distcc cc
325 # ln -s ../../../bin/distcc g++
326 # ln -s ../../../bin/distcc c++
327 Then, to use distcc, a user just needs to put the directory
329 /usr/lib/distcc/bin early in the PATH, and have set a host list in
330 DISTCC_HOSTS or a file. distcc will handle the rest.
331 Note that this masquerade directory must occur on the PATH earlier than
333 the directory that contains the actual compilers of the same names, and
334 that any auxiliary programs that these compilers call (such as as or
335 ld) must also be found on the PATH in a directory after the masquerade
336 directory since distcc calls out to the real compiler with a PATH value
337 that has all directory up to and including the masquerade directory
338 trimmed off.
339 It is possible to get a "recursion error" in masquerade mode, which
341 means that distcc is somehow finding itself again, not the real com‐
342 piler. This can indicate that you have two masquerade directories on
343 the PATH, possibly because of having two distcc installations in dif‐
344 ferent locations. It can also indicate that you're trying to mix "mas‐
345 queraded" and "explicit" operation.
346 Recursion errors can be avoided by using shell scripts instead of
348 links. For example, in /usr/lib/distcc/bin create a file cc which con‐
349 tains:
350 #!/bin/sh
352 distcc /usr/bin/gcc "$@"
353 In this way, we are not dependent on distcc having to locate the real
355 gcc by investigating the PATH variable. Instead, the compiler location
356 is explicitly provided.
357
360 ccache is a program that speeds software builds by caching the results
361 of compilations. ccache is normally called before distcc, so that
362 results are retrieved from a normal cache. Some experimentation may be
363 required for idiosyncratic makefiles to make everything work together.
364 The most reliable method is to set
366 CCACHE_PREFIX="distcc"
368 This tells ccache to run distcc as a wrapper around the real compiler.
370 ccache still uses the real compiler to detect compiler upgrades.
371 ccache can then be run using either a masquerade directory or by set‐
373 ting
374 CC="ccache gcc"
376 As of version 2.2, ccache does not cache compilation from preprocessed
378 source and so will never get a cache hit if it is run from distccd or
379 distcc. It must be run only on the client side and before distcc to be
380 any use.
381 distcc's pump mode is not compatible with ccache.
383
385 A "host list" tells distcc which machines to use for compilation. In
386 order, distcc looks in the $DISTCC_HOSTS environment variable, the
387 user's $DISTCC_DIR/hosts file, and the system-wide host file. If no
388 host list can be found, distcc emits a warning and compiles locally.
389 The host list is a simple whitespace separated list of host specifica‐
391 tions. The simplest and most common form is a host names, such as
392 localhost red green blue
394 distcc prefers hosts towards the start of the list, so machines should
396 be listed in descending order of speed. In particular, when only a
397 single compilation can be run (such as from a configure script), the
398 first machine listed is used (but see --randomize below).
399 Placing localhost at the right point in the list is important to get‐
401 ting good performance. Because overhead for running jobs locally is
402 low, localhost should normally be first. However, it is important that
403 the client have enough cycles free to run the local jobs and the distcc
404 client. If the client is slower than the volunteers, or if there are
405 many volunteers, then the client should be put later in the list or not
406 at all. As a general rule, if the aggregate CPU speed of the client is
407 less than one fifth of the total, then the client should be left out of
408 the list.
409 If you have a large shared build cluster and a single shared hosts
411 file, the above rules would cause the first few machines in the hosts
412 file to be tried first even though they are likely to be busier than
413 machines later in the list. To avoid this, place the keyword --random‐
414 ize into the host list. This will cause the host list to be random‐
415 ized, which should improve performance slightly for large build clus‐
416 ters.
417 There are two special host names --localslots and --localslots_cpp
419 which are useful for adjusting load on the local machine. The --local‐
420 slots host specifies how many jobs that cannot be run remotely that can
421 be run concurrently on the local machine, while --localslots_cpp con‐
422 trols how many preprocessors will run in parallel on the local machine.
423 Tuning these values can improve performance. Linking on large projects
424 can take large amounts of memory. Running parallel linkers, which can‐
425 not be executed remotely, may force the machine to swap, which reduces
426 performance over just running the jobs in sequence without swapping.
427 Getting the number of parallel preprocessors just right allows you to
428 use larger parallel factors with make, since the local machine now has
429 some machanism for measuring local resource usage.
430 Finally there is the host entry
432 Performance depends on the details of the source and makefiles used for
434 the project, and the machine and network speeds. Experimenting with
435 different settings for the host list and -j factor may improve perfor‐
436 mance.
437 The syntax is
439 DISTCC_HOSTS = HOSTSPEC ...
441 HOSTSPEC = LOCAL_HOST | SSH_HOST | TCP_HOST | OLDSTYLE_TCP_HOST
442 | GLOBAL_OPTION
443 | ZEROCONF
444 LOCAL_HOST = localhost[/LIMIT]
445 | --localslots=<int>
446 | --localslots_cpp=<int>
447 SSH_HOST = [USER]@HOSTID[/LIMIT][:COMMAND][OPTIONS]
448 TCP_HOST = HOSTID[:PORT][/LIMIT][OPTIONS]
449 OLDSTYLE_TCP_HOST = HOSTID[/LIMIT][:PORT][OPTIONS]
450 HOSTID = HOSTNAME | IPV4 | IPV6
451 OPTIONS = ,OPTION[OPTIONS]
452 OPTION = lzo | cpp | auth
453 GLOBAL_OPTION = --randomize
454 ZEROCONF = +zeroconf
455 Here are some individual examples of the syntax:
457 localhost
459 The literal word "localhost" is interpreted specially to cause
460 compilations to be directly executed, rather than passed to a
461 daemon on the local machine. If you do want to connect to a
462 daemon on the local machine for testing, then give the machine's
463 IP address or real hostname. (This will be slower.)
464 IPV6 A literal IPv6 address enclosed in square brackets, such as
466 [::1]
467 IPV4 A literal IPv4 address, such as 10.0.0.1
469 HOSTNAME
471 A hostname to be looked up using the resolver.
472 :PORT Connect to a specified decimal port number, rather than the
474 default of 3632.
475 @HOSTID
477 Connect to the host over SSH, rather than TCP. Options for the
478 SSH connection can be set in ~/.ssh/config
479 USER@ Connect to the host over SSH as a specified username.
481 :COMMAND
483 Connect over SSH, and use a specified path to find the distccd
484 server. This is normally only needed if for some reason you
485 can't install distccd into a directory on the default PATH for
486 SSH connections. Use this if you get errors like "distccd: com‐
487 mand not found" in SSH mode.
488 /LIMIT A decimal limit can be added to any host specification to
490 restrict the number of jobs that this client will send to the
491 machine. The limit defaults to four per host (two for local‐
492 host), but may be further restricted by the server. You should
493 only need to increase this for servers with more than two pro‐
494 cessors.
495 ,lzo Enables LZO compression for this TCP or SSH host.
497 ,cpp Enables distcc-pump mode for this host. Note: the build command
499 must be wrapped in the pump script in order to start the include
500 server.
501 ,auth Enables GSSAPI-based mutual authentication for this host.
503 --randomize
505 Randomize the order of the host list before execution.
506 +zeroconf
508 This option is only available if distcc was compiled with Avahi
509 support enabled at configure time. When this special entry is
510 present in the hosts list, distcc will use Avahi Zeroconf DNS
511 Service Discovery (DNS-SD) to locate any available distccd
512 servers on the local network. This avoids the need to explic‐
513 itly list the host names or IP addresses of the distcc server
514 machines. The distccd servers must have been started with the
515 "--zeroconf" option to distccd. An important caveat is that in
516 the current implementation, pump mode (",cpp") and compression
517 (",lzo") will never be used for hosts located via zeroconf.
518 Here is an example demonstrating some possibilities:
520 localhost/2 @bigman/16:/opt/bin/distccd oldmachine:4200/1
522 # cartman is down
523 distant/3,lzo
524 Comments are allowed in host specifications. Comments start with a
526 hash/pound sign (#) and run to the end of the line.
527 If a host in the list is not reachable distcc will emit a warning and
529 ignore that host for about one minute.
530
532 The lzo host option specifies that LZO compression should be used for
533 data transfer, including preprocessed source, object code and error
534 messages. Compression is usually economical on networks slower than
535 100Mbps, but results may vary depending on the network, processors and
536 source tree.
537 Enabling compression makes the distcc client and server use more CPU
539 time, but less network traffic. The added CPU time is insignificant
540 for pump mode. The compression ratio is typically 4:1 for source and
541 2:1 for object code.
542 Using compression requires both client and server to use at least
544 release 2.9 of distcc. No server configuration is required: the server
545 always responds with compressed replies to compressed requests.
546 Pump mode requires the servers to have the lzo host option on.
548
550 If the compiler name is an absolute path, it is passed verbatim to the
551 server and the compiler is run from that directory. For example:
552 distcc /usr/local/bin/gcc-3.1415 -c hello.c
554 If the compiler name is not absolute, or not fully qualified, distccd's
556 PATH is searched. When distcc is run from a masquerade directory, only
557 the base name of the compiler is used. The client's PATH is used only
558 to run the preprocessor and has no effect on the server's path.
559
561 Both the distcc client and server impose timeouts on transfer of data
562 across the network. This is intended to detect hosts which are down or
563 unreachable, and to prevent compiles hanging indefinitely if a server
564 is disconnected while in use. If a client-side timeout expires, the
565 job will be re-run locally.
566 The timeouts are not configurable at present.
568
570 Error messages or warnings from local or remote compilers are passed
571 through to diagnostic output on the client.
572 distcc can supply extensive debugging information when the verbose
574 option is used. This is controlled by the DISTCC_VERBOSE environment
575 variable on the client, and the --verbose option on the server. For
576 troubleshooting, examine both the client and server error messages.
577
579 The exit code of distcc is normally that of the compiler: zero for suc‐
580 cessful compilation and non-zero otherwise.
581 distcc distinguishes between "genuine" errors such as a syntax error in
583 the source, and "accidental" errors such as a networking problem con‐
584 necting to a volunteer. In the case of accidental errors, distcc will
585 retry the compilation locally unless the DISTCC_FALLBACK option has
586 been disabled.
587 If the compiler exits with a signal, distcc returns an exit code of 128
589 plus the signal number.
590 distcc internal errors cause an exit code between 100 and 127. In par‐
592 ticular
593 100 General distcc failure.
595 101 Bad arguments.
597 102 Bind failed.
599 103 Connect failed.
601 104 Compiler crashed.
603 105 Out of memory.
605 106 Bad Host SPEC
607 107 I/O Error
609 108 Truncated.
611 109 Protocol Error.
613 110 The given compiler was not found on the remote host. Check that
615 $CC is set appropriately and that it's installed in a directory
616 on the search path for distccd.
617 111 Recursive call to distcc.
619 112 Failed to discard privileges.
621 113 Network access denied.
623 114 In use by another process.
625 115 No such file.
627 116 No hosts defined and fallbacks disabled.
629 118 Timeout.
631 119 GSS-API - Catchall error code for GSS-API related errors.
633
636 If $DISTCC_HOSTS is not set, distcc reads a host list from either
637 $DISTCC_DIR/hosts or a system-wide configuration file set at compile
638 time. The file locations are shown in the output from distcc --help
639 distcc creates a number of temporary and lock files underneath the tem‐
641 porary directory.
642
644 distcc's behaviour is controlled by a number of environment variables.
645 For most cases nothing need be set if the host list is stored in a
646 file.
647 DISTCC_HOSTS
649 Space-separated list of volunteer host specifications.
650 DISTCC_VERBOSE
652 If set to 1, distcc produces explanatory messages on the stan‐
653 dard error stream or in the log file. This can be helpful in
654 debugging problems. Bug reports should include verbose output.
655 DISTCC_LOG
657 Log file to receive messages from distcc itself, rather than
658 stderr.
659 DISTCC_FALLBACK
661 By default distcc will compile locally if it fails to distribute
662 a job to the intended machine, or if no host list can be found.
663 If this variable is set to 0 then fallbacks are disabled and
664 those compilations will simply fail. Note that this does not
665 affect jobs which must always be local such as linking.
666 DISTCC_IO_TIMEOUT
668 Specifies how long (in seconds) distcc will wait before deciding
669 a distributed job has timed out. If a distributed job is
670 expected to takes a long time, consider increasing this value so
671 the job does not time out and fallback to a local compile. By
672 default set to 300 seconds.
673 DISTCC_SAVE_TEMPS
675 If set to 1, temporary files are not deleted after use. Good
676 for debugging, or if your disks are too empty.
677 DISTCC_TCP_CORK
679 If set to 0, disable use of "TCP corks", even if they're present
680 on this system. Using corks normally helps pack requests into
681 fewer packets and aids performance. This should normally be
682 left enabled.
683 DISTCC_SSH
685 Specifies the command used for opening SSH connections.
686 Defaults to "ssh" but may be set to a different connection com‐
687 mand such as "lsh" or "tsocks-ssh" that accepts a similar com‐
688 mand line. The command is not split into words and is not exe‐
689 cuted through the shell.
690 DISTCC_SKIP_LOCAL_RETRY
692 If set, when a remote compile fails, distcc will no longer try
693 to recompile that file locally.
694 DISTCC_DIR
696 Per-user configuration directory to store lock files and state
697 files. By default ~/.distcc/ is used.
698 TMPDIR Directory for temporary files such as preprocessor output. By
700 default /tmp/ is used.
701 UNCACHED_ERR_FD
703 If set and if DISTCC_LOG is not set, distcc errors are written
704 to the file descriptor identified by this variable. This vari‐
705 able is intended mainly for automatic use by ccache, which sets
706 it to avoid caching transient errors such as network problems.
707 DISTCC_ENABLE_DISCREPANCY_EMAIL
709 If set, distcc sends an email when a compilation failed
710 remotely, but succeeded locally. Built-in heuristics prevent
711 some such discrepancy email from being sent if the problem is
712 that a local file changed between the failing remote compilation
713 and the succeeding local compilation.
714 DISTCC_MAX_DISCREPANCY
716 The maximum number of remote compilation failures allowed in
717 pump mode before distcc switches to plain distcc mode. By
718 default set to 1.
719 DCC_EMAILLOG_WHOM_TO_BLAME
721 The email address for discrepancy email; the default is "distcc-
722 pump-errors".
723 DISTCC_PRINCIPAL
725 If set, specifies the name of the principal that distccd runs
726 under, and is used to authenticate the server to the client.
727 This environment variable is only used if distcc was compiled
728 with the --with-auth configure option and the ,auth per host
729 option is specified.
730
732 Cross compilation means building programs to run on a machine with a
733 different processor, architecture, or operating system to where they
734 were compiled. distcc supports cross compilation, including teams of
735 mixed-architecture machines, although some changes to the compilation
736 commands may be required.
737 The compilation command passed to distcc must be one that will execute
739 properly on every volunteer machine to produce an object file of the
740 appropriate type. If the machines have different processors, then sim‐
741 ply using distcc cc will probably not work, because that will normally
742 invoke the volunteer's native compiler.
743 Machines with the same CPU but different operating systems may not nec‐
745 essarily generate compatible .o files.
746 Several different gcc configurations can be installed side-by-side on
748 any machine. If you build gcc from source, you should use the --pro‐
749 gram-suffix configuration options to cause it to be installed with a
750 name that encodes the gcc version and the target platform.
751 The recommended convention for the gcc name is TARGET-gcc-VERSION such
753 as i686-linux-gcc-3.2 . GCC 3.3 will install itself under this name,
754 in addition to TARGET-gcc and, if it's native, gcc-VERSION and gcc .
755 The compiler must be installed under the same name on the client and on
757 every volunteer machine.
758
760 If you think you have found a distcc bug, please see the file report‐
761 ing-bugs.txt in the documentation directory for information on how to
762 report it.
763 Some makefiles have missing or extra dependencies that cause incorrect
765 or slow parallel builds. Recursive make is inefficient and can leave
766 processors unnecessarily idle for long periods. (See Recursive Make
767 Considered Harmful by Peter Miller.) Makefile bugs are the most common
768 cause of trees failing to build under distcc. Alternatives to Make
769 such as SCons can give much faster builds for some projects.
770 Using different versions of gcc can cause confusing build problems
772 because the header files and binary interfaces have changed over time,
773 and some distributors have included incompatible patches without chang‐
774 ing the version number. distcc does not protect against using incom‐
775 patible versions. Compiler errors about link problems or declarations
776 in system header files are usually due to mismatched or incorrectly
777 installed compilers.
778 gcc's -MD option can produce output in the wrong directory if the
780 source and object files are in different directories and the -MF option
781 is not used. There is no perfect solution because of incompatible
782 changes between gcc versions. Explicitly specifying the dependency
783 output file with -MF will fix the problem.
784 TCP mode connections should only be used on trusted networks.
786 Including slow machines in the list of volunteer hosts can slow the
788 build down.
789 When distcc or ccache is used on NFS, the filesystem must be exported
791 with the no_subtree_check option to allow reliable renames between
792 directories.
793 The compiler can be invoked with a command line gcc hello.c to both
795 compile and link. distcc doesn't split this into separate parts, but
796 rather runs the whole thing locally.
797 distcc-pump mode reverts to plain distcc mode for source files that
799 contain includes with absolute paths (either directly or in an included
800 file).
801 Due to limitations in gcc, gdb may not be able to automatically find
803 the source files for programs built using distcc in some circumstances.
804 The gdb directory command can be used. For distcc's plain (non-pump)
805 mode, this is fixed in gcc 3.4 and later. For pump mode, the fix in
806 gcc 3.4 does not suffice; we've worked around the gcc limitation by
807 rewriting the object files that gcc produces, but this is only done for
808 ELF object files, but not for other object file formats.
809 The .o files produced by discc in pump mode will be different from
811 those produced locally: for non-ELF files, the debug information will
812 specify compile directories of the server. The code itself should be
813 identical.
814 For the ELF-format, distcc rewrites the .o files to correct compile
816 directory path information. While the resulting .o files are not byte‐
817 wise identical to what would have been produced by compiling on the
818 local client (due to different padding, etc), they should be function‐
819 ally identical.
820 In distcc-pump mode, the include server is unable to handle certain
822 very complicated computed includes as found in parts of the Boost
823 library. The include server will time out and distcc will revert to
824 plain mode.
825 In distcc-pump mode, certain assumptions are made that source and
827 header files do not change during the build. See discussion in section
828 DISTCC DISCREPANCY SYMPTOMS of include_server(1().
829 Other known bugs may be documented on http://code.google.com/p/distcc/
831
833 distcc was written by Martin Pool <mbp@sourcefrog.net>, with the co-
834 operation of many scholars including Wayne Davison, Frerich Raabe, Dim‐
835 itri Papadopoulos and others noted in the NEWS file. Please report
836 bugs to <distcc@lists.samba.org>. See pump(1) for the authors of pump
837 mode.
838
840 You are free to use distcc. distcc (including this manual) may be
841 copied, modified or distributed only under the terms of the GNU General
842 Public Licence version 2 or later. distcc comes with absolutely no
843 warrany. A copy of the GPL is included in the file COPYING.
844
846 distccd(1), pump(1), include_server(1), gcc(1), make(1), and
847 ccache(1). http://code.google.com/p/distcc/ http://ccache.samba.org/
848 9 June 2008 distcc(1)