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 slower.
51 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 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 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 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
84 1 For each machine, download distcc, unpack, and install.
85 2 On each of the servers, run distccd --daemon with --allow
87 options to restrict access.
88 3 Put the names of the servers in your environment:
90 $ export DISTCC_HOSTS='localhost red green blue'
91 4 Build!
93 $ make -j8 CC=distcc
94
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 $ export DISTCC_HOSTS='--randomize localhost red,cpp,lzo
101 green,cpp,lzo blue,cpp,lzo'
102 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 $ pump make -j20 CC=distcc
110
113 Proceed as per the QUICKSTART but in Step 3, specify that the remote
114 hosts are to mutually authenticate with the client:
115 $ export DISTCC_HOSTS='--randomize localhost red,auth green,auth
117 blue,auth'
118 If distccd runs under a specific principal name then execute the fol‐
120 lowing command prior to step 4:
121 export DISTCC_PRINICIPAL=<name>
123
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 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 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 distcc examines its command line to determine which of these phases are
143 being invoked, and whether the job can be distributed.
144
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 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 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 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 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 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
187 Using pump mode requires both client and servers to use release 3.0 or
188 later of distcc and distccd (respectively).
189 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 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 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 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 See the include_server(1) manual for more information on symptoms and
215 causes of violations of distcc-pump mode assumptions.
216
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
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 --help Displays summary instructions.
231 --version
233 Displays the distcc client version.
234 --show-hosts
236 Displays the host list that distcc would use. See the Host
237 Specifications section.
238 --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 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 FILE indicates a source file or header file that would be
252 sent to the distcc server host.
253 SYMLINK indicates a symbolic link that would be sent to
255 the distcc server host.
256 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 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 -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 --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
282 There are three different ways to call distcc, to suit different cir‐
283 cumstances:
284 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 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 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 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
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 For example:
318 # 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 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 To automatically discover compilers and create masquerade links run the
331 provided update-distcc-symlinks script.
332 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 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 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 #!/bin/sh
353 distcc /usr/bin/gcc "$@"
354 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
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 The most reliable method is to set
367 CCACHE_PREFIX="distcc"
369 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 ccache can then be run using either a masquerade directory or by set‐
374 ting
375 CC="ccache gcc"
377 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 distcc's pump mode is not compatible with ccache.
384
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 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 localhost red green blue
395 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 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 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 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 Finally there is the host entry
433 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 The syntax is
440 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 Here are some individual examples of the syntax:
458 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 IPV6 A literal IPv6 address enclosed in square brackets, such as
467 [::1]
468 IPV4 A literal IPv4 address, such as 10.0.0.1
470 HOSTNAME
472 A hostname to be looked up using the resolver.
473 :PORT Connect to a specified decimal port number, rather than the
475 default of 3632.
476 @HOSTID
478 Connect to the host over SSH, rather than TCP. Options for the
479 SSH connection can be set in ~/.ssh/config
480 USER@ Connect to the host over SSH as a specified username.
482 :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 /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 ,lzo Enables LZO compression for this TCP or SSH host.
498 ,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 ,auth Enables GSSAPI-based mutual authentication for this host.
504 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 --randomize
512 Randomize the order of the host list before execution.
513 +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 Here is an example demonstrating some possibilities:
527 localhost/2 @bigman/16:/opt/bin/distccd oldmachine:4200/1
529 # cartman is down
530 distant/3,lzo
531 Comments are allowed in host specifications. Comments start with a
533 hash/pound sign (#) and run to the end of the line.
534 If a host in the list is not reachable distcc will emit a warning and
536 ignore that host for about one minute.
537
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 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 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 Pump mode requires the servers to have the lzo host option on.
555
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 distcc /usr/local/bin/gcc-3.1415 -c hello.c
561 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
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 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
579 Error messages or warnings from local or remote compilers are passed
580 through to diagnostic output on the client.
581 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
588 The exit code of distcc is normally that of the compiler: zero for suc‐
589 cessful compilation and non-zero otherwise.
590 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 If the compiler exits with a signal, distcc returns an exit code of 128
598 plus the signal number.
599 distcc internal errors cause an exit code between 100 and 127. In par‐
601 ticular
602 100 General distcc failure.
604 101 Bad arguments.
606 102 Bind failed.
608 103 Connect failed.
610 104 Compiler crashed.
612 105 Out of memory.
614 106 Bad Host SPEC
616 107 I/O Error
618 108 Truncated.
620 109 Protocol Error.
622 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 111 Recursive call to distcc.
628 112 Failed to discard privileges.
630 113 Network access denied.
632 114 In use by another process.
634 115 No such file.
636 116 No hosts defined and fallbacks disabled.
638 118 Timeout.
640 119 GSS-API - Catchall error code for GSS-API related errors.
642 120 Called for preprocessing, which needs to be done locally.
644
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 distcc creates a number of temporary and lock files underneath the tem‐
652 porary directory.
653
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 DISTCC_HOSTS
660 Space-separated list of volunteer host specifications.
661 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 DISTCC_LOG
668 Log file to receive messages from distcc itself, rather than
669 stderr.
670 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 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 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 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 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 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 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 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 DISTCC_SKIP_LOCAL_RETRY
721 If set, when a remote compile fails, distcc will no longer try
722 to recompile that file locally.
723 DISTCC_DIR
725 Per-user configuration directory to store lock files and state
726 files. By default ~/.distcc/ is used.
727 TMPDIR Directory for temporary files such as preprocessor output. By
729 default /tmp/ is used.
730 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 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 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 DCC_EMAILLOG_WHOM_TO_BLAME
750 The email address for discrepancy email; the default is "distcc-
751 pump-errors".
752 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
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 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 Machines with the same CPU but different operating systems may not nec‐
774 essarily generate compatible .o files.
775 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 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 The compiler must be installed under the same name on the client and on
786 every volunteer machine.
787
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 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 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 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 TCP mode connections should only be used on trusted networks.
815 Including slow machines in the list of volunteer hosts can slow the
817 build down.
818 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 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 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 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 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 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 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 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 Other known bugs may be documented on http://code.google.com/p/distcc/
860
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
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
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 9 June 2008 distcc(1)