| 1 |
<HTML> |
| 2 |
<!-- this file was generated by troffcvt and tc2html --> |
| 3 |
<HEAD> |
| 4 |
<TITLE> |
| 5 |
distcc manual page |
| 6 |
</TITLE> |
| 7 |
</HEAD> |
| 8 |
<BODY> |
| 9 |
<H1> |
| 10 |
distcc manual page<BR> |
| 11 |
</H1> |
| 12 |
<P> |
| 13 |
<H2> |
| 14 |
Table of Contents |
| 15 |
</H2> |
| 16 |
<!-- INSERT TOC HERE, MAYBE --> |
| 17 |
<!-- TOC BEGIN --> |
| 18 |
<UL> |
| 19 |
<LI> |
| 20 |
<A HREF=#TOC_1> NAME</A> |
| 21 |
<LI> |
| 22 |
<A HREF=#TOC_2> SYNOPSIS</A> |
| 23 |
<LI> |
| 24 |
<A HREF=#TOC_3> DESCRIPTION</A> |
| 25 |
<LI> |
| 26 |
<A HREF=#TOC_4> QUICKSTART</A> |
| 27 |
<LI> |
| 28 |
<A HREF=#TOC_5> QUICKSTART FOR DISTCC-PUMP MODE</A> |
| 29 |
<LI> |
| 30 |
<A HREF=#TOC_6> QUICKSTART FOR DISTCC-GSSAPI MODE</A> |
| 31 |
<LI> |
| 32 |
<A HREF=#TOC_7> HOW PLAIN (NON-PUMP) DISTCC WORKS</A> |
| 33 |
<LI> |
| 34 |
<A HREF=#TOC_8> HOW DISTCC-PUMP MODE WORKS</A> |
| 35 |
<LI> |
| 36 |
<A HREF=#TOC_9> RESTRICTIONS FOR PUMP MODE</A> |
| 37 |
<LI> |
| 38 |
<A HREF=#TOC_10> HOW DISTCC-GSSAPI MODE WORKS</A> |
| 39 |
<LI> |
| 40 |
<A HREF=#TOC_11> OPTION SUMMARY</A> |
| 41 |
<LI> |
| 42 |
<A HREF=#TOC_12> INSTALLING DISTCC</A> |
| 43 |
<LI> |
| 44 |
<A HREF=#TOC_13> MASQUERADING</A> |
| 45 |
<LI> |
| 46 |
<A HREF=#TOC_14> USING DISTCC WITH CCACHE</A> |
| 47 |
<LI> |
| 48 |
<A HREF=#TOC_15> HOST SPECIFICATIONS</A> |
| 49 |
<LI> |
| 50 |
<A HREF=#TOC_16> COMPRESSION</A> |
| 51 |
<LI> |
| 52 |
<A HREF=#TOC_17> SEARCH PATHS</A> |
| 53 |
<LI> |
| 54 |
<A HREF=#TOC_18> TIMEOUTS</A> |
| 55 |
<LI> |
| 56 |
<A HREF=#TOC_19> DIAGNOSTICS</A> |
| 57 |
<LI> |
| 58 |
<A HREF=#TOC_20> EXIT CODES</A> |
| 59 |
<LI> |
| 60 |
<A HREF=#TOC_21> FILES</A> |
| 61 |
<LI> |
| 62 |
<A HREF=#TOC_22> ENVIRONMENT VARIABLES</A> |
| 63 |
<LI> |
| 64 |
<A HREF=#TOC_23> CROSS COMPILING</A> |
| 65 |
<LI> |
| 66 |
<A HREF=#TOC_24> BUGS</A> |
| 67 |
<LI> |
| 68 |
<A HREF=#TOC_25> AUTHOR</A> |
| 69 |
<LI> |
| 70 |
<A HREF=#TOC_26> LICENCE</A> |
| 71 |
<LI> |
| 72 |
<A HREF=#TOC_27> SEE ALSO</A> |
| 73 |
</UL> |
| 74 |
<!-- TOC END --> |
| 75 |
<BR> |
| 76 |
<H2> |
| 77 |
<A NAME=TOC_1> |
| 78 |
NAME</A> |
| 79 |
</H2> |
| 80 |
distcc - distributed C/C++/ObjC compiler with distcc-pump extensions<BR> |
| 81 |
<H2> |
| 82 |
<A NAME=TOC_2> |
| 83 |
SYNOPSIS</A> |
| 84 |
</H2> |
| 85 |
<B>distcc</B> <I> <compiler> [COMPILER OPTIONS]</I><BR> |
| 86 |
<P> |
| 87 |
<B>distcc</B> <I> [COMPILER OPTIONS]</I><BR> |
| 88 |
<P> |
| 89 |
<B><compiler></B> <I> [COMPILER OPTIONS]</I><BR> |
| 90 |
<P> |
| 91 |
<B>distcc</B> <I> [DISTCC OPTIONS]</I><BR> |
| 92 |
<H2> |
| 93 |
<A NAME=TOC_3> |
| 94 |
DESCRIPTION</A> |
| 95 |
</H2> |
| 96 |
distcc distributes compilation of C code across several machines |
| 97 |
on a network. distcc should always generate the same results |
| 98 |
as a local compile, it is simple to install and use, and it is |
| 99 |
often much faster than a local compile.<BR> |
| 100 |
<P> |
| 101 |
This version incorporates plain distcc as well as an enhancement |
| 102 |
called pump mode or distcc-pump.<BR> |
| 103 |
<P> |
| 104 |
For each job, distcc in plain mode sends the complete preprocessed |
| 105 |
source code and compiler arguments across the network from the |
| 106 |
client to a compilation server. In pump mode, distcc sends the |
| 107 |
source code and recursively included header files (excluding those |
| 108 |
from the default system header directories), so that both preprocessing |
| 109 |
and compilation can take place on the compilation servers. This |
| 110 |
speeds up the delivery of compilations by up to an order of magnitude |
| 111 |
over plain distcc.<BR> |
| 112 |
<P> |
| 113 |
Compilation is driven by a client machine, which is typically |
| 114 |
the developer's workstation or laptop. The distcc client runs |
| 115 |
on this machine, as does make, the preprocessor (if distcc's pump |
| 116 |
mode is not used), the linker, and other stages of the build process. |
| 117 |
Any number of volunteer machines act as compilation servers and |
| 118 |
help the client to build the program, by running the <B> distccd(1)</B> |
| 119 |
daemon, C compiler and assembler as required.<BR> |
| 120 |
<P> |
| 121 |
distcc can run across either TCP sockets (on port 3632 by default), |
| 122 |
or through a tunnel command such as ssh(1). For TCP connections |
| 123 |
the volunteers must run the distccd(1) daemon either directly |
| 124 |
or from inetd. For SSH connections distccd must be installed but |
| 125 |
should <B> not</B> be listening for connections.<BR> |
| 126 |
<P> |
| 127 |
TCP connections should only be used on secure networks because |
| 128 |
there is no user authentication or protection of source or object |
| 129 |
code. SSH connections are typically 25% slower because of processor |
| 130 |
overhead for encryption, although this can vary greatly depending |
| 131 |
on CPUs, network and the program being built.<BR> |
| 132 |
<P> |
| 133 |
distcc is intended to be used with GNU Make's <B> -j</B> option, |
| 134 |
which runs several compiler processes concurrently. distcc spreads |
| 135 |
the jobs across both local and remote CPUs. Because distcc is |
| 136 |
able to distribute most of the work across the network, a higher |
| 137 |
concurrency level can be used than for local builds. As a rule |
| 138 |
of thumb, the <B> -j</B> value should be set to about twice the |
| 139 |
total number of available server CPUs but subject to client limitations. |
| 140 |
This setting allows for maximal interleaving of tasks being blocked |
| 141 |
waiting for disk or network IO. Note that distcc can also work |
| 142 |
with other build control tools, such as SCons, where similar concurrency |
| 143 |
settings must be adjusted.<BR> |
| 144 |
<P> |
| 145 |
The <B> -j</B> setting, especially for large values of <B> -j,</B> |
| 146 |
must take into account the CPU load on the client. Additional |
| 147 |
measures may be needed to curtail the client load. For example, |
| 148 |
concurrent linking should be severely curtailed using auxiliary |
| 149 |
locks. The effect of other build activity, such as Java compilation |
| 150 |
when building mixed code, should be considered. The <B> --localslots_cpp</B> |
| 151 |
parameter is by default set to 16. This limits the number of concurrent |
| 152 |
processes that do preprocessing in plain distcc (non-pump) mode. |
| 153 |
Therefore, larger <B> -j</B> values than 16 may be used without |
| 154 |
overloading a single-CPU client due to preprocessing. Such large |
| 155 |
values may speed up parts of the build that do not involve C compilations, |
| 156 |
but they may not be useful to distcc efficiency in plain mode.<BR> |
| 157 |
<P> |
| 158 |
In contrast, using pump mode and say 40 servers, a setting of |
| 159 |
<B>-j80</B> or larger may be appropriate even for single-CPU clients.<BR> |
| 160 |
<P> |
| 161 |
It is strongly recommended that you install the same compiler |
| 162 |
version on all machines participating in a build. Incompatible |
| 163 |
compilers may cause mysterious compile or link failures.<BR> |
| 164 |
<H2> |
| 165 |
<A NAME=TOC_4> |
| 166 |
QUICKSTART</A> |
| 167 |
</H2> |
| 168 |
<BR> |
| 169 |
<DL> |
| 170 |
<DT> |
| 171 |
1 |
| 172 |
</DT> |
| 173 |
<DD> |
| 174 |
For each machine, download distcc, unpack, and install.<BR> |
| 175 |
</DD> |
| 176 |
<DT> |
| 177 |
2 |
| 178 |
</DT> |
| 179 |
<DD> |
| 180 |
On each of the servers, run <B> distccd --daemon</B> with <B> |
| 181 |
--allow</B> options to restrict access.<BR> |
| 182 |
</DD> |
| 183 |
<DT> |
| 184 |
3 |
| 185 |
</DT> |
| 186 |
<DD> |
| 187 |
Put the names of the servers in your environment:<BR> |
| 188 |
</DD> |
| 189 |
</DL> |
| 190 |
<UL> |
| 191 |
$ export DISTCC_HOSTS='localhost red green blue'<BR> |
| 192 |
</UL> |
| 193 |
<DL> |
| 194 |
<DT> |
| 195 |
4 |
| 196 |
</DT> |
| 197 |
<DD> |
| 198 |
Build!<BR> |
| 199 |
</DD> |
| 200 |
</DL> |
| 201 |
<UL> |
| 202 |
$ make -j8 CC=distcc<BR> |
| 203 |
</UL> |
| 204 |
<H2> |
| 205 |
<A NAME=TOC_5> |
| 206 |
QUICKSTART FOR DISTCC-PUMP MODE</A> |
| 207 |
</H2> |
| 208 |
Proceed as above, but in Step 3, specify that the remote hosts |
| 209 |
are to carry the burden of preprocessing and that the files sent |
| 210 |
over the network should be compressed:<BR> |
| 211 |
<UL> |
| 212 |
$ export DISTCC_HOSTS='--randomize localhost red,cpp,lzo green,cpp,lzo |
| 213 |
blue,cpp,lzo'<BR> |
| 214 |
</UL> |
| 215 |
The <B> --randomize</B> option enforces a uniform usage of compile |
| 216 |
servers. While you will get some benefit from distcc's pump mode |
| 217 |
with only a few servers, you get increasing benefit with more |
| 218 |
server CPUs (up to the hundreds!). Wrap your build inside the |
| 219 |
pump command, here assuming 10 servers:<BR> |
| 220 |
<UL> |
| 221 |
$ pump make -j20 CC=distcc<BR> |
| 222 |
</UL> |
| 223 |
<H2> |
| 224 |
<A NAME=TOC_6> |
| 225 |
QUICKSTART FOR DISTCC-GSSAPI MODE</A> |
| 226 |
</H2> |
| 227 |
Proceed as per the <B> QUICKSTART</B> but in Step 3, specify that |
| 228 |
the remote hosts are to mutually authenticate with the client:<BR> |
| 229 |
<UL> |
| 230 |
$ export DISTCC_HOSTS='--randomize localhost red,auth green,auth |
| 231 |
blue,auth'<BR> |
| 232 |
</UL> |
| 233 |
If distccd runs under a specific principal name then execute the |
| 234 |
following command prior to step 4:<BR> |
| 235 |
<UL> |
| 236 |
export DISTCC_PRINICIPAL=<name><BR> |
| 237 |
</UL> |
| 238 |
<H2> |
| 239 |
<A NAME=TOC_7> |
| 240 |
HOW PLAIN (NON-PUMP) DISTCC WORKS</A> |
| 241 |
</H2> |
| 242 |
distcc only ever runs the compiler and assembler remotely. With |
| 243 |
plain distcc, the preprocessor must always run locally because |
| 244 |
it needs to access various header files on the local machine which |
| 245 |
may not be present, or may not be the same, on the volunteer. |
| 246 |
The linker similarly needs to examine libraries and object files, |
| 247 |
and so must run locally.<BR> |
| 248 |
<P> |
| 249 |
The compiler and assembler take only a single input file (the |
| 250 |
preprocessed source) and produce a single output (the object file). |
| 251 |
distcc ships these two files across the network and can therefore |
| 252 |
run the compiler/assembler remotely.<BR> |
| 253 |
<P> |
| 254 |
Fortunately, for most programs running the preprocessor is relatively |
| 255 |
cheap, and the linker is called relatively infrequent, so most |
| 256 |
of the work can be distributed.<BR> |
| 257 |
<P> |
| 258 |
distcc examines its command line to determine which of these phases |
| 259 |
are being invoked, and whether the job can be distributed.<BR> |
| 260 |
<H2> |
| 261 |
<A NAME=TOC_8> |
| 262 |
HOW DISTCC-PUMP MODE WORKS</A> |
| 263 |
</H2> |
| 264 |
In pump mode, distcc runs the preprocessor remotely too. To do |
| 265 |
so, the preprocessor must have access to all the files that it |
| 266 |
would have accessed if had been running locally. In pump mode, |
| 267 |
therefore, distcc gathers all of the recursively included headers, |
| 268 |
except the ones that are default system headers, and sends them |
| 269 |
along with the source file to the compilation server.<BR> |
| 270 |
<P> |
| 271 |
In distcc-pump mode, the server unpacks the set of all source |
| 272 |
files in a temporary directory, which contains a directory tree |
| 273 |
that mirrors the part of the file system that is relevant to preprocessing, |
| 274 |
including symbolic links.<BR> |
| 275 |
<P> |
| 276 |
The compiler is then run from the path in the temporary directory |
| 277 |
that corresponds to the current working directory on the client. |
| 278 |
To find and transmit the many hundreds of files that are often |
| 279 |
part of a single compilation, pump mode uses an incremental include |
| 280 |
analysis algorithm. The include server is a Python program that |
| 281 |
implements this algorithm. The pump command starts the include |
| 282 |
server so that throughout the build it can answer include queries |
| 283 |
by distcc commands.<BR> |
| 284 |
<P> |
| 285 |
The include server uses static analysis of the macro language |
| 286 |
to deal with conditional compilation and computed includes. It |
| 287 |
uses the property that when a given header file has already been |
| 288 |
analyzed for includes, it is not necessary to do so again if all |
| 289 |
the include options (-I's) are unchanged (along with other conditions).<BR> |
| 290 |
<P> |
| 291 |
For large builds, header files are included, on average, hundreds |
| 292 |
of times each. With distcc-pump mode each such file is analyzed |
| 293 |
only a few times, perhaps just once, instead of being preprocessed |
| 294 |
hundreds of times. Also, each source or header file is now compressed |
| 295 |
only once, because the include server memoizes the compressed |
| 296 |
files. As a result, the time used for preparing compilations |
| 297 |
may drop by up to an order of magnitude over the preprocessing |
| 298 |
of plain distcc.<BR> |
| 299 |
<P> |
| 300 |
Because distcc in pump mode is able to push out files up to about |
| 301 |
ten times faster, build speed may increase 3X or more for large |
| 302 |
builds compared to plain distcc mode.<BR> |
| 303 |
<H2> |
| 304 |
<A NAME=TOC_9> |
| 305 |
RESTRICTIONS FOR PUMP MODE</A> |
| 306 |
</H2> |
| 307 |
<BR> |
| 308 |
Using pump mode requires both client and servers to use release |
| 309 |
3.0 or later of distcc and distccd (respectively).<BR> |
| 310 |
<P> |
| 311 |
The incremental include analysis of distc-pump mode rests on the |
| 312 |
fundamental assumption that source and header files do not change |
| 313 |
during the build process. A few complex build systems, such as |
| 314 |
that for Linux kernel 2.6, do not quite satisfy this requirement. |
| 315 |
To overcome such issues, and other corner cases such as absolute |
| 316 |
filepaths in includes, see the <B>include_server(1)</B> man page.<BR> |
| 317 |
<P> |
| 318 |
Another important assumption is that the include configuration |
| 319 |
of all machines must be identical. Thus the headers under the |
| 320 |
default system path must be the same on all servers and all clients. |
| 321 |
If a standard GNU compiler installation is used, then this requirement |
| 322 |
applies to all libraries whose header files are installed under |
| 323 |
/usr/include or /usr/local/include/. Note that installing software |
| 324 |
packages often lead to additional headers files being placed in |
| 325 |
subdirectories of either.<BR> |
| 326 |
<P> |
| 327 |
If this assumption does not hold, then it is possible to break |
| 328 |
builds with distcc-pump mode, or worse, to get wrong results without |
| 329 |
warning. Presently this condition is not verified, and it is |
| 330 |
on our TODO list to address this issue.<BR> |
| 331 |
<P> |
| 332 |
An easy way to guarantee that the include configurations are identical |
| 333 |
is to use a cross-compiler that defines a default system search |
| 334 |
path restricted to directories of the compiler installation.<BR> |
| 335 |
<P> |
| 336 |
See the <B>include_server</B>(1) manual for more information on |
| 337 |
symptoms and causes of violations of distcc-pump mode assumptions.<BR> |
| 338 |
<H2> |
| 339 |
<A NAME=TOC_10> |
| 340 |
HOW DISTCC-GSSAPI MODE WORKS</A> |
| 341 |
</H2> |
| 342 |
<BR> |
| 343 |
In this mode distcc will use the GSS-API framework to access the |
| 344 |
currently configured security mechanism and perform mutual authentication |
| 345 |
with the daemon.<BR> |
| 346 |
<H2> |
| 347 |
<A NAME=TOC_11> |
| 348 |
OPTION SUMMARY</A> |
| 349 |
</H2> |
| 350 |
Most options passed to distcc are interpreted as compiler options. |
| 351 |
The following options are understood by distcc itself. If any |
| 352 |
of these options are specified, distcc will not invoke the compiler.<BR> |
| 353 |
<DL> |
| 354 |
<DT> |
| 355 |
<B>--help</B> |
| 356 |
</DT> |
| 357 |
<DD> |
| 358 |
Displays summary instructions.<BR> |
| 359 |
</DD> |
| 360 |
</DL> |
| 361 |
<P> |
| 362 |
<DL> |
| 363 |
<DT> |
| 364 |
<B>--version</B> |
| 365 |
</DT> |
| 366 |
<DD> |
| 367 |
Displays the distcc client version.<BR> |
| 368 |
</DD> |
| 369 |
</DL> |
| 370 |
<P> |
| 371 |
<DL> |
| 372 |
<DT> |
| 373 |
<B>--show-hosts</B> |
| 374 |
</DT> |
| 375 |
<DD> |
| 376 |
Displays the host list that distcc would use. See the Host Specifications |
| 377 |
section.<BR> |
| 378 |
</DD> |
| 379 |
</DL> |
| 380 |
<P> |
| 381 |
<DL> |
| 382 |
<DT> |
| 383 |
<B>--scan-includes</B> |
| 384 |
</DT> |
| 385 |
<DD> |
| 386 |
Displays the list of files that distcc would send to the remote |
| 387 |
machine, as computed by the include server. This is a conservative |
| 388 |
(over-)approximation of the files that would be read by the C |
| 389 |
compiler. This option only works in pump mode. See the "How |
| 390 |
Distcc-pump Mode Works" section for details on how this is |
| 391 |
computed.<BR> |
| 392 |
</DD> |
| 393 |
</DL> |
| 394 |
<UL> |
| 395 |
The list output by <B>distcc --scan-includes</B> will contain |
| 396 |
one entry per line. Each line contains a category followed by |
| 397 |
a path. The category is one of FILE, SYMLINK, DIRECTORY, or SYSTEMDIR:<BR> |
| 398 |
<DL> |
| 399 |
<DT> |
| 400 |
<BR> |
| 401 |
</DT> |
| 402 |
<DD> |
| 403 |
<B>FILE</B> indicates a source file or header file that would |
| 404 |
be sent to the distcc server host.<BR> |
| 405 |
</DD> |
| 406 |
<DT> |
| 407 |
<BR> |
| 408 |
</DT> |
| 409 |
<DD> |
| 410 |
<B>SYMLINK</B> indicates a symbolic link that would be sent to |
| 411 |
the distcc server host.<BR> |
| 412 |
</DD> |
| 413 |
<DT> |
| 414 |
<BR> |
| 415 |
</DT> |
| 416 |
<DD> |
| 417 |
<B>DIRECTORY</B> indicates a directory that may be needed in order |
| 418 |
to compile the source file. For example, a directory "foo" |
| 419 |
may be needed because of an include of the form #include "foo/../bar.h". |
| 420 |
Such directories would be created on the distcc server host.<BR> |
| 421 |
</DD> |
| 422 |
<DT> |
| 423 |
<BR> |
| 424 |
</DT> |
| 425 |
<DD> |
| 426 |
<B>SYSTEMDIR</B> indicates a system include directory, i.e. a |
| 427 |
directory which is on the compiler's default include path, such |
| 428 |
as "/usr/include"; such directories are assumed to be |
| 429 |
present on the distcc server host, and so would not be sent to |
| 430 |
the distcc server host.<BR> |
| 431 |
</DD> |
| 432 |
</DL> |
| 433 |
</UL> |
| 434 |
<DL> |
| 435 |
<DT> |
| 436 |
<B>-j</B> |
| 437 |
</DT> |
| 438 |
<DD> |
| 439 |
Displays distcc's concurrency level, as calculated from the host |
| 440 |
list; it is the maximum number of outstanding jobs issued by this |
| 441 |
client to all servers. By default this will be four times the |
| 442 |
number of hosts in the host list, unless the /LIMIT option was |
| 443 |
used in the host list. See the Host Specifications section.<BR> |
| 444 |
</DD> |
| 445 |
</DL> |
| 446 |
<P> |
| 447 |
<DL> |
| 448 |
<DT> |
| 449 |
<B>--show-principal</B> |
| 450 |
</DT> |
| 451 |
<DD> |
| 452 |
Displays the name of the distccd security principal extracted |
| 453 |
from the environment. <B> This option is only available if distcc |
| 454 |
was compiled with</B> <B> the --with-auth configure option.</B><BR> |
| 455 |
</DD> |
| 456 |
</DL> |
| 457 |
<H2> |
| 458 |
<A NAME=TOC_12> |
| 459 |
INSTALLING DISTCC</A> |
| 460 |
</H2> |
| 461 |
There are three different ways to call distcc, to suit different |
| 462 |
circumstances:<BR> |
| 463 |
<UL> |
| 464 |
<P> |
| 465 |
distcc can be installed under the name of the real compiler, to |
| 466 |
intercept calls to it and run them remotely. This "masqueraded" |
| 467 |
compiler has the widest compatibility with existing source trees, |
| 468 |
and is convenient when you want to use distcc for all compilation. |
| 469 |
The fact that distcc is being used is transparent to the makefiles.<BR> |
| 470 |
<P> |
| 471 |
distcc can be prepended to compiler command lines, such as "distcc |
| 472 |
cc -c hello.c" or CC="distcc gcc". This is convenient |
| 473 |
when you want to use distcc for only some compilations or to try |
| 474 |
it out, but can cause trouble with some makefiles or versions |
| 475 |
of libtool that assume $CC does not contain a space.<BR> |
| 476 |
<P> |
| 477 |
Finally, distcc can be used directly as a compiler. "cc" |
| 478 |
is always used as the name of the real compiler in this "implicit" |
| 479 |
mode. This can be convenient for interactive use when "explicit" |
| 480 |
mode does not work but is not really recommended for new use.<BR> |
| 481 |
</UL> |
| 482 |
<P> |
| 483 |
Remember that you should not use two methods for calling distcc |
| 484 |
at the same time. If you are using a masquerade directory, don't |
| 485 |
change CC and/or CXX, just put the directory early on your PATH. |
| 486 |
If you're not using a masquerade directory, you'll need to either |
| 487 |
change CC and/or CXX, or modify the makefile(s) to call distcc |
| 488 |
explicitly.<BR> |
| 489 |
<H2> |
| 490 |
<A NAME=TOC_13> |
| 491 |
MASQUERADING</A> |
| 492 |
</H2> |
| 493 |
The basic idea is to create a "masquerade directory" |
| 494 |
which contains links from the name of the real compiler to the |
| 495 |
distcc binary. This directory is inserted early on the PATH, |
| 496 |
so that calls to the compiler are intercepted and distcc is run |
| 497 |
instead. distcc then removes itself from the PATH to find the |
| 498 |
real compiler.<BR> |
| 499 |
<P> |
| 500 |
For example:<BR> |
| 501 |
<P> |
| 502 |
<UL> |
| 503 |
# mkdir /usr/lib/distcc/bin<BR> |
| 504 |
# cd /usr/lib/distcc/bin<BR> |
| 505 |
# ln -s ../../../bin/distcc gcc<BR> |
| 506 |
# ln -s ../../../bin/distcc cc<BR> |
| 507 |
# ln -s ../../../bin/distcc g++<BR> |
| 508 |
# ln -s ../../../bin/distcc c++<BR> |
| 509 |
</UL> |
| 510 |
<P> |
| 511 |
Then, to use distcc, a user just needs to put the directory /usr/lib/distcc/bin |
| 512 |
early in the PATH, and have set a host list in DISTCC_HOSTS or |
| 513 |
a file. distcc will handle the rest.<BR> |
| 514 |
<P> |
| 515 |
Note that this masquerade directory must occur on the PATH earlier |
| 516 |
than the directory that contains the actual compilers of the same |
| 517 |
names, and that any auxiliary programs that these compilers call |
| 518 |
(such as as or ld) must also be found on the PATH in a directory |
| 519 |
after the masquerade directory since distcc calls out to the real |
| 520 |
compiler with a PATH value that has all directory up to and including |
| 521 |
the masquerade directory trimmed off.<BR> |
| 522 |
<P> |
| 523 |
It is possible to get a "recursion error" in masquerade |
| 524 |
mode, which means that distcc is somehow finding itself again, |
| 525 |
not the real compiler. This can indicate that you have two masquerade |
| 526 |
directories on the PATH, possibly because of having two distcc |
| 527 |
installations in different locations. It can also indicate that |
| 528 |
you're trying to mix "masqueraded" and "explicit" |
| 529 |
operation.<BR> |
| 530 |
<P> |
| 531 |
Recursion errors can be avoided by using shell scripts instead |
| 532 |
of links. For example, in /usr/lib/distcc/bin create a file cc |
| 533 |
which contains:<BR> |
| 534 |
<P> |
| 535 |
<UL> |
| 536 |
#!/bin/sh<BR> |
| 537 |
distcc /usr/bin/gcc "$@"<BR> |
| 538 |
</UL> |
| 539 |
<P> |
| 540 |
In this way, we are not dependent on distcc having to locate the |
| 541 |
real gcc by investigating the PATH variable. Instead, the compiler |
| 542 |
location is explicitly provided.<BR> |
| 543 |
<H2> |
| 544 |
<A NAME=TOC_14> |
| 545 |
USING DISTCC WITH CCACHE</A> |
| 546 |
</H2> |
| 547 |
ccache is a program that speeds software builds by caching the |
| 548 |
results of compilations. ccache is normally called before distcc, |
| 549 |
so that results are retrieved from a normal cache. Some experimentation |
| 550 |
may be required for idiosyncratic makefiles to make everything |
| 551 |
work together.<BR> |
| 552 |
<P> |
| 553 |
The most reliable method is to set<BR> |
| 554 |
<DL> |
| 555 |
<DT> |
| 556 |
<BR> |
| 557 |
</DT> |
| 558 |
<DD> |
| 559 |
<B>CCACHE_PREFIX="distcc"</B><BR> |
| 560 |
</DD> |
| 561 |
</DL> |
| 562 |
<P> |
| 563 |
This tells ccache to run distcc as a wrapper around the real compiler. |
| 564 |
ccache still uses the real compiler to detect compiler upgrades.<BR> |
| 565 |
<P> |
| 566 |
ccache can then be run using either a masquerade directory <I> |
| 567 |
or</I> by setting<BR> |
| 568 |
<DL> |
| 569 |
<DT> |
| 570 |
<BR> |
| 571 |
</DT> |
| 572 |
<DD> |
| 573 |
<B>CC="ccache gcc"</B><BR> |
| 574 |
</DD> |
| 575 |
</DL> |
| 576 |
<P> |
| 577 |
As of version 2.2, ccache does not cache compilation from preprocessed |
| 578 |
source and so will never get a cache hit if it is run from distccd |
| 579 |
or distcc. It must be run only on the client side and before |
| 580 |
distcc to be any use.<BR> |
| 581 |
distcc's pump mode is not compatible with ccache.<BR> |
| 582 |
<H2> |
| 583 |
<A NAME=TOC_15> |
| 584 |
HOST SPECIFICATIONS</A> |
| 585 |
</H2> |
| 586 |
A "host list" tells distcc which machines to use for |
| 587 |
compilation. In order, distcc looks in the <B> $DISTCC_HOSTS</B> |
| 588 |
environment variable, the user's <B> $DISTCC_DIR/hosts</B> file, |
| 589 |
and the system-wide host file. If no host list can be found, |
| 590 |
distcc emits a warning and compiles locally.<BR> |
| 591 |
<P> |
| 592 |
The host list is a simple whitespace separated list of host specifications. |
| 593 |
The simplest and most common form is a host names, such as<BR> |
| 594 |
<P> |
| 595 |
<UL> |
| 596 |
<B>localhost red green blue</B><BR> |
| 597 |
</UL> |
| 598 |
<P> |
| 599 |
distcc prefers hosts towards the start of the list, so machines |
| 600 |
should be listed in descending order of speed. In particular, |
| 601 |
when only a single compilation can be run (such as from a configure |
| 602 |
script), the first machine listed is used (but see <I> --randomize</I> |
| 603 |
below).<BR> |
| 604 |
<P> |
| 605 |
Placing <I> localhost</I> at the right point in the list is important |
| 606 |
to getting good performance. Because overhead for running jobs |
| 607 |
locally is low, localhost should normally be first. However, |
| 608 |
it is important that the client have enough cycles free to run |
| 609 |
the local jobs and the distcc client. If the client is slower |
| 610 |
than the volunteers, or if there are many volunteers, then the |
| 611 |
client should be put later in the list or not at all. As a general |
| 612 |
rule, if the aggregate CPU speed of the client is less than one |
| 613 |
fifth of the total, then the client should be left out of the |
| 614 |
list.<BR> |
| 615 |
<P> |
| 616 |
If you have a large shared build cluster and a single shared hosts |
| 617 |
file, the above rules would cause the first few machines in the |
| 618 |
hosts file to be tried first even though they are likely to be |
| 619 |
busier than machines later in the list. To avoid this, place |
| 620 |
the keyword <I> --randomize</I> into the host list. This will |
| 621 |
cause the host list to be randomized, which should improve performance |
| 622 |
slightly for large build clusters.<BR> |
| 623 |
<P> |
| 624 |
There are two special host names <B> --localslots</B> and <B> |
| 625 |
--localslots_cpp</B> which are useful for adjusting load on the |
| 626 |
local machine. The <B> --localslots</B> host specifies how many |
| 627 |
jobs that cannot be run remotely that can be run concurrently |
| 628 |
on the local machine, while <B> --localslots_cpp</B> controls |
| 629 |
how many preprocessors will run in parallel on the local machine. |
| 630 |
Tuning these values can improve performance. Linking on large |
| 631 |
projects can take large amounts of memory. Running parallel linkers, |
| 632 |
which cannot be executed remotely, may force the machine to swap, |
| 633 |
which reduces performance over just running the jobs in sequence |
| 634 |
without swapping. Getting the number of parallel preprocessors |
| 635 |
just right allows you to use larger parallel factors with make, |
| 636 |
since the local machine now has some mechanism for measuring local |
| 637 |
resource usage.<BR> |
| 638 |
<P> |
| 639 |
Finally there is the host entry<BR> |
| 640 |
<P> |
| 641 |
Performance depends on the details of the source and makefiles |
| 642 |
used for the project, and the machine and network speeds. Experimenting |
| 643 |
with different settings for the host list and <B> -j</B> factor |
| 644 |
may improve performance.<BR> |
| 645 |
<P> |
| 646 |
The syntax is<BR> |
| 647 |
<P> |
| 648 |
DISTCC_HOSTS = HOSTSPEC ...<BR> |
| 649 |
HOSTSPEC = LOCAL_HOST | SSH_HOST | TCP_HOST | OLDSTYLE_TCP_HOST<BR> |
| 650 |
| GLOBAL_OPTION<BR> |
| 651 |
| ZEROCONF<BR> |
| 652 |
LOCAL_HOST = localhost[/LIMIT]<BR> |
| 653 |
| --localslots=<int><BR> |
| 654 |
| --localslots_cpp=<int><BR> |
| 655 |
SSH_HOST = [USER]@HOSTID[/LIMIT][:COMMAND][OPTIONS]<BR> |
| 656 |
TCP_HOST = HOSTID[:PORT][/LIMIT][OPTIONS]<BR> |
| 657 |
OLDSTYLE_TCP_HOST = HOSTID[/LIMIT][:PORT][OPTIONS]<BR> |
| 658 |
HOSTID = HOSTNAME | IPV4 | IPV6<BR> |
| 659 |
OPTIONS = ,OPTION[OPTIONS]<BR> |
| 660 |
OPTION = lzo | cpp | auth<BR> |
| 661 |
GLOBAL_OPTION = --randomize<BR> |
| 662 |
ZEROCONF = +zeroconf<BR> |
| 663 |
<P> |
| 664 |
Here are some individual examples of the syntax:<BR> |
| 665 |
<DL> |
| 666 |
<DT> |
| 667 |
<B>localhost</B> |
| 668 |
</DT> |
| 669 |
<DD> |
| 670 |
The literal word "localhost" is interpreted specially |
| 671 |
to cause compilations to be directly executed, rather than passed |
| 672 |
to a daemon on the local machine. If you do want to connect to |
| 673 |
a daemon on the local machine for testing, then give the machine's |
| 674 |
IP address or real hostname. (This will be slower.)<BR> |
| 675 |
</DD> |
| 676 |
<DT> |
| 677 |
<B>IPV6</B> |
| 678 |
</DT> |
| 679 |
<DD> |
| 680 |
A literal IPv6 address enclosed in square brackets, such as <B> |
| 681 |
[::1]</B><BR> |
| 682 |
</DD> |
| 683 |
<DT> |
| 684 |
<B>IPV4</B> |
| 685 |
</DT> |
| 686 |
<DD> |
| 687 |
A literal IPv4 address, such as <B> 10.0.0.1</B><BR> |
| 688 |
</DD> |
| 689 |
<DT> |
| 690 |
<B>HOSTNAME</B> |
| 691 |
</DT> |
| 692 |
<DD> |
| 693 |
A hostname to be looked up using the resolver.<BR> |
| 694 |
</DD> |
| 695 |
<DT> |
| 696 |
<B>:PORT</B> |
| 697 |
</DT> |
| 698 |
<DD> |
| 699 |
Connect to a specified decimal port number, rather than the default |
| 700 |
of 3632.<BR> |
| 701 |
</DD> |
| 702 |
<DT> |
| 703 |
<B>@HOSTID</B> |
| 704 |
</DT> |
| 705 |
<DD> |
| 706 |
Connect to the host over SSH, rather than TCP. Options for the |
| 707 |
SSH connection can be set in <B> ~/.ssh/config</B><BR> |
| 708 |
</DD> |
| 709 |
<DT> |
| 710 |
<B>USER@</B> |
| 711 |
</DT> |
| 712 |
<DD> |
| 713 |
Connect to the host over SSH as a specified username.<BR> |
| 714 |
</DD> |
| 715 |
<DT> |
| 716 |
<B>:COMMAND</B> |
| 717 |
</DT> |
| 718 |
<DD> |
| 719 |
Connect over SSH, and use a specified path to find the distccd |
| 720 |
server. This is normally only needed if for some reason you can't |
| 721 |
install distccd into a directory on the default PATH for SSH connections. |
| 722 |
Use this if you get errors like "distccd: command not found" |
| 723 |
in SSH mode.<BR> |
| 724 |
</DD> |
| 725 |
<DT> |
| 726 |
<B>/LIMIT</B> |
| 727 |
</DT> |
| 728 |
<DD> |
| 729 |
A decimal limit can be added to any host specification to restrict |
| 730 |
the number of jobs that this client will send to the machine. |
| 731 |
The limit defaults to four per host (two for localhost), but may |
| 732 |
be further restricted by the server. You should only need to |
| 733 |
increase this for servers with more than two processors.<BR> |
| 734 |
</DD> |
| 735 |
<DT> |
| 736 |
<B>,lzo</B> |
| 737 |
</DT> |
| 738 |
<DD> |
| 739 |
Enables LZO compression for this TCP or SSH host.<BR> |
| 740 |
</DD> |
| 741 |
<DT> |
| 742 |
<B>,cpp</B> |
| 743 |
</DT> |
| 744 |
<DD> |
| 745 |
Enables distcc-pump mode for this host. Note: the build command |
| 746 |
must be wrapped in the pump script in order to start the include |
| 747 |
server.<BR> |
| 748 |
</DD> |
| 749 |
<DT> |
| 750 |
<B>,auth</B> |
| 751 |
</DT> |
| 752 |
<DD> |
| 753 |
Enables GSSAPI-based mutual authentication for this host.<BR> |
| 754 |
</DD> |
| 755 |
<DT> |
| 756 |
<B>--randomize</B> |
| 757 |
</DT> |
| 758 |
<DD> |
| 759 |
Randomize the order of the host list before execution.<BR> |
| 760 |
</DD> |
| 761 |
<DT> |
| 762 |
<B>+zeroconf</B> |
| 763 |
</DT> |
| 764 |
<DD> |
| 765 |
<B>This option is only available if distcc was compiled with Avahi |
| 766 |
support enabled at configure time.</B> When this special entry |
| 767 |
is present in the hosts list, distcc will use Avahi Zeroconf DNS |
| 768 |
Service Discovery (DNS-SD) to locate any available distccd servers |
| 769 |
on the local network. This avoids the need to explicitly list |
| 770 |
the host names or IP addresses of the distcc server machines. |
| 771 |
The distccd servers must have been started with the "--zeroconf" |
| 772 |
option to distccd. An important caveat is that in the current |
| 773 |
implementation, pump mode (",cpp") and compression (",lzo") |
| 774 |
will never be used for hosts located via zeroconf.<BR> |
| 775 |
</DD> |
| 776 |
</DL> |
| 777 |
<P> |
| 778 |
Here is an example demonstrating some possibilities:<BR> |
| 779 |
<P> |
| 780 |
<UL> |
| 781 |
<B> localhost/2 @bigman/16:/opt/bin/distccd oldmachine:4200/1</B><BR> |
| 782 |
<B> # cartman is down</B><BR> |
| 783 |
<B> distant/3,lzo</B><BR> |
| 784 |
</UL> |
| 785 |
<P> |
| 786 |
Comments are allowed in host specifications. Comments start with |
| 787 |
a hash/pound sign (<B>#</B>) and run to the end of the line.<BR> |
| 788 |
<P> |
| 789 |
If a host in the list is not reachable distcc will emit a warning |
| 790 |
and ignore that host for about one minute.<BR> |
| 791 |
<H2> |
| 792 |
<A NAME=TOC_16> |
| 793 |
COMPRESSION</A> |
| 794 |
</H2> |
| 795 |
The <B> lzo</B> host option specifies that LZO compression should |
| 796 |
be used for data transfer, including preprocessed source, object |
| 797 |
code and error messages. Compression is usually economical on |
| 798 |
networks slower than 100Mbps, but results may vary depending on |
| 799 |
the network, processors and source tree.<BR> |
| 800 |
<P> |
| 801 |
Enabling compression makes the distcc client and server use more |
| 802 |
CPU time, but less network traffic. The added CPU time is insignificant |
| 803 |
for pump mode. The compression ratio is typically 4:1 for source |
| 804 |
and 2:1 for object code.<BR> |
| 805 |
<P> |
| 806 |
Using compression requires both client and server to use at least |
| 807 |
release 2.9 of distcc. No server configuration is required: the |
| 808 |
server always responds with compressed replies to compressed requests.<BR> |
| 809 |
<P> |
| 810 |
Pump mode requires the servers to have the lzo host option on.<BR> |
| 811 |
<H2> |
| 812 |
<A NAME=TOC_17> |
| 813 |
SEARCH PATHS</A> |
| 814 |
</H2> |
| 815 |
<BR> |
| 816 |
<P> |
| 817 |
If the compiler name is an absolute path, it is passed verbatim |
| 818 |
to the server and the compiler is run from that directory. For |
| 819 |
example:<BR> |
| 820 |
<P> |
| 821 |
<UL> |
| 822 |
<B>distcc /usr/local/bin/gcc-3.1415 -c hello.c</B><BR> |
| 823 |
</UL> |
| 824 |
<P> |
| 825 |
If the compiler name is not absolute, or not fully qualified, |
| 826 |
distccd's PATH is searched. When distcc is run from a masquerade |
| 827 |
directory, only the base name of the compiler is used. The client's |
| 828 |
PATH is used only to run the preprocessor and has no effect on |
| 829 |
the server's path.<BR> |
| 830 |
<H2> |
| 831 |
<A NAME=TOC_18> |
| 832 |
TIMEOUTS</A> |
| 833 |
</H2> |
| 834 |
<BR> |
| 835 |
<P> |
| 836 |
Both the distcc client and server impose timeouts on transfer |
| 837 |
of data across the network. This is intended to detect hosts |
| 838 |
which are down or unreachable, and to prevent compiles hanging |
| 839 |
indefinitely if a server is disconnected while in use. If a client-side |
| 840 |
timeout expires, the job will be re-run locally.<BR> |
| 841 |
<P> |
| 842 |
The timeouts are not configurable at present.<BR> |
| 843 |
<H2> |
| 844 |
<A NAME=TOC_19> |
| 845 |
DIAGNOSTICS</A> |
| 846 |
</H2> |
| 847 |
Error messages or warnings from local or remote compilers are |
| 848 |
passed through to diagnostic output on the client.<BR> |
| 849 |
<P> |
| 850 |
distcc can supply extensive debugging information when the verbose |
| 851 |
option is used. This is controlled by the <B> DISTCC_VERBOSE</B> |
| 852 |
environment variable on the client, and the <B> --verbose</B> |
| 853 |
option on the server. For troubleshooting, examine both the client |
| 854 |
and server error messages.<BR> |
| 855 |
<H2> |
| 856 |
<A NAME=TOC_20> |
| 857 |
EXIT CODES</A> |
| 858 |
</H2> |
| 859 |
The exit code of distcc is normally that of the compiler: zero |
| 860 |
for successful compilation and non-zero otherwise.<BR> |
| 861 |
<P> |
| 862 |
distcc distinguishes between "genuine" errors such as |
| 863 |
a syntax error in the source, and "accidental" errors |
| 864 |
such as a networking problem connecting to a volunteer. In the |
| 865 |
case of accidental errors, distcc will retry the compilation locally |
| 866 |
unless the DISTCC_FALLBACK option has been disabled.<BR> |
| 867 |
<P> |
| 868 |
If the compiler exits with a signal, distcc returns an exit code |
| 869 |
of 128 plus the signal number.<BR> |
| 870 |
<P> |
| 871 |
distcc internal errors cause an exit code between 100 and 127. |
| 872 |
In particular<BR> |
| 873 |
<DL> |
| 874 |
<DT> |
| 875 |
100 |
| 876 |
</DT> |
| 877 |
<DD> |
| 878 |
General distcc failure.<BR> |
| 879 |
</DD> |
| 880 |
<DT> |
| 881 |
101 |
| 882 |
</DT> |
| 883 |
<DD> |
| 884 |
Bad arguments.<BR> |
| 885 |
</DD> |
| 886 |
<DT> |
| 887 |
102 |
| 888 |
</DT> |
| 889 |
<DD> |
| 890 |
Bind failed.<BR> |
| 891 |
</DD> |
| 892 |
<DT> |
| 893 |
103 |
| 894 |
</DT> |
| 895 |
<DD> |
| 896 |
Connect failed.<BR> |
| 897 |
</DD> |
| 898 |
<DT> |
| 899 |
104 |
| 900 |
</DT> |
| 901 |
<DD> |
| 902 |
Compiler crashed.<BR> |
| 903 |
</DD> |
| 904 |
<DT> |
| 905 |
105 |
| 906 |
</DT> |
| 907 |
<DD> |
| 908 |
Out of memory.<BR> |
| 909 |
</DD> |
| 910 |
<DT> |
| 911 |
106 |
| 912 |
</DT> |
| 913 |
<DD> |
| 914 |
Bad Host SPEC<BR> |
| 915 |
</DD> |
| 916 |
<DT> |
| 917 |
107 |
| 918 |
</DT> |
| 919 |
<DD> |
| 920 |
I/O Error<BR> |
| 921 |
</DD> |
| 922 |
<DT> |
| 923 |
108 |
| 924 |
</DT> |
| 925 |
<DD> |
| 926 |
Truncated.<BR> |
| 927 |
</DD> |
| 928 |
<DT> |
| 929 |
109 |
| 930 |
</DT> |
| 931 |
<DD> |
| 932 |
Protocol Error.<BR> |
| 933 |
</DD> |
| 934 |
<DT> |
| 935 |
110 |
| 936 |
</DT> |
| 937 |
<DD> |
| 938 |
The given compiler was not found on the remote host. Check that |
| 939 |
$CC is set appropriately and that it's installed in a directory |
| 940 |
on the search path for distccd.<BR> |
| 941 |
</DD> |
| 942 |
<DT> |
| 943 |
111 |
| 944 |
</DT> |
| 945 |
<DD> |
| 946 |
Recursive call to distcc.<BR> |
| 947 |
</DD> |
| 948 |
<DT> |
| 949 |
112 |
| 950 |
</DT> |
| 951 |
<DD> |
| 952 |
Failed to discard privileges.<BR> |
| 953 |
</DD> |
| 954 |
<DT> |
| 955 |
113 |
| 956 |
</DT> |
| 957 |
<DD> |
| 958 |
Network access denied.<BR> |
| 959 |
</DD> |
| 960 |
<DT> |
| 961 |
114 |
| 962 |
</DT> |
| 963 |
<DD> |
| 964 |
In use by another process.<BR> |
| 965 |
</DD> |
| 966 |
<DT> |
| 967 |
115 |
| 968 |
</DT> |
| 969 |
<DD> |
| 970 |
No such file.<BR> |
| 971 |
</DD> |
| 972 |
<DT> |
| 973 |
116 |
| 974 |
</DT> |
| 975 |
<DD> |
| 976 |
No hosts defined and fallbacks disabled.<BR> |
| 977 |
</DD> |
| 978 |
<DT> |
| 979 |
118 |
| 980 |
</DT> |
| 981 |
<DD> |
| 982 |
Timeout.<BR> |
| 983 |
</DD> |
| 984 |
<DT> |
| 985 |
119 |
| 986 |
</DT> |
| 987 |
<DD> |
| 988 |
GSS-API - Catchall error code for GSS-API related errors.<BR> |
| 989 |
</DD> |
| 990 |
</DL> |
| 991 |
<H2> |
| 992 |
<A NAME=TOC_21> |
| 993 |
FILES</A> |
| 994 |
</H2> |
| 995 |
If $DISTCC_HOSTS is not set, distcc reads a host list from either |
| 996 |
<B>$DISTCC_DIR/hosts</B> or a system-wide configuration file set |
| 997 |
at compile time. The file locations are shown in the output from |
| 998 |
<B>distcc --help</B><BR> |
| 999 |
<P> |
| 1000 |
distcc creates a number of temporary and lock files underneath |
| 1001 |
the temporary directory.<BR> |
| 1002 |
<H2> |
| 1003 |
<A NAME=TOC_22> |
| 1004 |
ENVIRONMENT VARIABLES</A> |
| 1005 |
</H2> |
| 1006 |
distcc's behaviour is controlled by a number of environment variables. |
| 1007 |
For most cases nothing need be set if the host list is stored |
| 1008 |
in a file.<BR> |
| 1009 |
<DL> |
| 1010 |
<DT> |
| 1011 |
<B>DISTCC_HOSTS</B> |
| 1012 |
</DT> |
| 1013 |
<DD> |
| 1014 |
Space-separated list of volunteer host specifications.<BR> |
| 1015 |
</DD> |
| 1016 |
<DT> |
| 1017 |
<B>DISTCC_VERBOSE</B> |
| 1018 |
</DT> |
| 1019 |
<DD> |
| 1020 |
If set to 1, distcc produces explanatory messages on the standard |
| 1021 |
error stream or in the log file. This can be helpful in debugging |
| 1022 |
problems. Bug reports should include verbose output.<BR> |
| 1023 |
</DD> |
| 1024 |
<DT> |
| 1025 |
<B>DISTCC_LOG</B> |
| 1026 |
</DT> |
| 1027 |
<DD> |
| 1028 |
Log file to receive messages from distcc itself, rather than stderr.<BR> |
| 1029 |
</DD> |
| 1030 |
<DT> |
| 1031 |
<B>DISTCC_FALLBACK</B> |
| 1032 |
</DT> |
| 1033 |
<DD> |
| 1034 |
By default distcc will compile locally if it fails to distribute |
| 1035 |
a job to the intended machine, or if no host list can be found. |
| 1036 |
If this variable is set to 0 then fallbacks are disabled and those |
| 1037 |
compilations will simply fail. Note that this does not affect |
| 1038 |
jobs which must always be local such as linking.<BR> |
| 1039 |
</DD> |
| 1040 |
<DT> |
| 1041 |
<B>DISTCC_BACKOFF_PERIOD</B> |
| 1042 |
</DT> |
| 1043 |
<DD> |
| 1044 |
Specifies how long (in seconds) distcc will avoid trying to use |
| 1045 |
a particular compilation server after that server yields a compile |
| 1046 |
failure. By default set to 60 seconds. To disable the backoff |
| 1047 |
behavior altogether, set this to 0.<BR> |
| 1048 |
</DD> |
| 1049 |
<DT> |
| 1050 |
<B>DISTCC_IO_TIMEOUT</B> |
| 1051 |
</DT> |
| 1052 |
<DD> |
| 1053 |
Specifies how long (in seconds) distcc will wait before deciding |
| 1054 |
a distributed job has timed out. If a distributed job is expected |
| 1055 |
to takes a long time, consider increasing this value so the job |
| 1056 |
does not time out and fallback to a local compile. By default |
| 1057 |
set to 300 seconds.<BR> |
| 1058 |
</DD> |
| 1059 |
<DT> |
| 1060 |
<B>DISTCC_PAUSE_TIME_MSEC</B> |
| 1061 |
</DT> |
| 1062 |
<DD> |
| 1063 |
Specifies how long (in milliseconds) distcc will pause when all |
| 1064 |
compilation servers are in use. By default set to 1000 milliseconds |
| 1065 |
(1 second). Setting this to a smaller value (e.g. 10 milliconds) |
| 1066 |
may improve throughput for some configurations, at the expense |
| 1067 |
of increased CPU load on the distcc client machine.<BR> |
| 1068 |
</DD> |
| 1069 |
<DT> |
| 1070 |
<B>DISTCC_SAVE_TEMPS</B> |
| 1071 |
</DT> |
| 1072 |
<DD> |
| 1073 |
If set to 1, temporary files are not deleted after use. Good |
| 1074 |
for debugging, or if your disks are too empty.<BR> |
| 1075 |
</DD> |
| 1076 |
<DT> |
| 1077 |
<B>DISTCC_TCP_CORK</B> |
| 1078 |
</DT> |
| 1079 |
<DD> |
| 1080 |
If set to 0, disable use of "TCP corks", even if they're |
| 1081 |
present on this system. Using corks normally helps pack requests |
| 1082 |
into fewer packets and aids performance. This should normally |
| 1083 |
be left enabled.<BR> |
| 1084 |
</DD> |
| 1085 |
<DT> |
| 1086 |
<B>DISTCC_SSH</B> |
| 1087 |
</DT> |
| 1088 |
<DD> |
| 1089 |
Specifies the command used for opening SSH connections. Defaults |
| 1090 |
to "ssh" but may be set to a different connection command |
| 1091 |
such as "lsh" or "tsocks-ssh" that accepts |
| 1092 |
a similar command line. The command is not split into words and |
| 1093 |
is not executed through the shell.<BR> |
| 1094 |
</DD> |
| 1095 |
<DT> |
| 1096 |
<B>DISTCC_SKIP_LOCAL_RETRY</B> |
| 1097 |
</DT> |
| 1098 |
<DD> |
| 1099 |
If set, when a remote compile fails, distcc will no longer try |
| 1100 |
to recompile that file locally.<BR> |
| 1101 |
</DD> |
| 1102 |
<DT> |
| 1103 |
<B>DISTCC_DIR</B> |
| 1104 |
</DT> |
| 1105 |
<DD> |
| 1106 |
Per-user configuration directory to store lock files and state |
| 1107 |
files. By default <B> ~/.distcc/</B> is used.<BR> |
| 1108 |
</DD> |
| 1109 |
<DT> |
| 1110 |
<B>TMPDIR</B> |
| 1111 |
</DT> |
| 1112 |
<DD> |
| 1113 |
Directory for temporary files such as preprocessor output. By |
| 1114 |
default /tmp/ is used.<BR> |
| 1115 |
</DD> |
| 1116 |
<DT> |
| 1117 |
<B>UNCACHED_ERR_FD</B> |
| 1118 |
</DT> |
| 1119 |
<DD> |
| 1120 |
If set and if DISTCC_LOG is not set, distcc errors are written |
| 1121 |
to the file descriptor identified by this variable. This variable |
| 1122 |
is intended mainly for automatic use by ccache, which sets it |
| 1123 |
to avoid caching transient errors such as network problems.<BR> |
| 1124 |
</DD> |
| 1125 |
<DT> |
| 1126 |
<B>DISTCC_ENABLE_DISCREPANCY_EMAIL</B> |
| 1127 |
</DT> |
| 1128 |
<DD> |
| 1129 |
If set, distcc sends an email when a compilation failed remotely, |
| 1130 |
but succeeded locally. Built-in heuristics prevent some such |
| 1131 |
discrepancy email from being sent if the problem is that a local |
| 1132 |
file changed between the failing remote compilation and the succeeding |
| 1133 |
local compilation.<BR> |
| 1134 |
</DD> |
| 1135 |
<DT> |
| 1136 |
<B>DISTCC_MAX_DISCREPANCY</B> |
| 1137 |
</DT> |
| 1138 |
<DD> |
| 1139 |
The maximum number of remote compilation failures allowed in pump |
| 1140 |
mode before distcc switches to plain distcc mode. By default set |
| 1141 |
to 1.<BR> |
| 1142 |
</DD> |
| 1143 |
<DT> |
| 1144 |
<B>DCC_EMAILLOG_WHOM_TO_BLAME</B> |
| 1145 |
</DT> |
| 1146 |
<DD> |
| 1147 |
The email address for discrepancy email; the default is "distcc-pump-errors".<BR> |
| 1148 |
</DD> |
| 1149 |
<DT> |
| 1150 |
<B>DISTCC_PRINCIPAL</B> |
| 1151 |
</DT> |
| 1152 |
<DD> |
| 1153 |
If set, specifies the name of the principal that distccd runs |
| 1154 |
under, and is used to authenticate the server to the client. <B> |
| 1155 |
This environment variable is only used if distcc was compiled |
| 1156 |
with</B> <B> the --with-auth configure option and the ,auth per |
| 1157 |
host option is specified.</B><BR> |
| 1158 |
</DD> |
| 1159 |
</DL> |
| 1160 |
<H2> |
| 1161 |
<A NAME=TOC_23> |
| 1162 |
CROSS COMPILING</A> |
| 1163 |
</H2> |
| 1164 |
Cross compilation means building programs to run on a machine |
| 1165 |
with a different processor, architecture, or operating system |
| 1166 |
to where they were compiled. distcc supports cross compilation, |
| 1167 |
including teams of mixed-architecture machines, although some |
| 1168 |
changes to the compilation commands may be required.<BR> |
| 1169 |
<P> |
| 1170 |
The compilation command passed to distcc must be one that will |
| 1171 |
execute properly on every volunteer machine to produce an object |
| 1172 |
file of the appropriate type. If the machines have different |
| 1173 |
processors, then simply using <B> distcc cc</B> will probably |
| 1174 |
not work, because that will normally invoke the volunteer's native |
| 1175 |
compiler.<BR> |
| 1176 |
<P> |
| 1177 |
Machines with the same CPU but different operating systems may |
| 1178 |
not necessarily generate compatible .o files.<BR> |
| 1179 |
<P> |
| 1180 |
Several different gcc configurations can be installed side-by-side |
| 1181 |
on any machine. If you build gcc from source, you should use |
| 1182 |
the <B> --program-suffix configuration</B> options to cause it |
| 1183 |
to be installed with a name that encodes the gcc version and the |
| 1184 |
target platform.<BR> |
| 1185 |
<P> |
| 1186 |
The recommended convention for the gcc name is <I> TARGET-gcc-VERSION</I> |
| 1187 |
such as <B> i686-linux-gcc-3.2</B> . GCC 3.3 will install itself |
| 1188 |
under this name, in addition to <I> TARGET-gcc</I> and, if it's |
| 1189 |
native, <I> gcc-VERSION</I> and <I> gcc</I> .<BR> |
| 1190 |
<P> |
| 1191 |
The compiler must be installed under the same name on the client |
| 1192 |
and on every volunteer machine.<BR> |
| 1193 |
<H2> |
| 1194 |
<A NAME=TOC_24> |
| 1195 |
BUGS</A> |
| 1196 |
</H2> |
| 1197 |
If you think you have found a distcc bug, please see the file |
| 1198 |
<I>reporting-bugs.txt</I> in the documentation directory for information |
| 1199 |
on how to report it.<BR> |
| 1200 |
<P> |
| 1201 |
Some makefiles have missing or extra dependencies that cause incorrect |
| 1202 |
or slow parallel builds. Recursive make is inefficient and can |
| 1203 |
leave processors unnecessarily idle for long periods. (See <I> |
| 1204 |
Recursive Make Considered Harmful</I> by Peter Miller.) Makefile |
| 1205 |
bugs are the most common cause of trees failing to build under |
| 1206 |
distcc. Alternatives to Make such as <I> SCons</I> can give much |
| 1207 |
faster builds for some projects.<BR> |
| 1208 |
<P> |
| 1209 |
Using different versions of gcc can cause confusing build problems |
| 1210 |
because the header files and binary interfaces have changed over |
| 1211 |
time, and some distributors have included incompatible patches |
| 1212 |
without changing the version number. distcc does not protect |
| 1213 |
against using incompatible versions. Compiler errors about link |
| 1214 |
problems or declarations in system header files are usually due |
| 1215 |
to mismatched or incorrectly installed compilers.<BR> |
| 1216 |
<P> |
| 1217 |
gcc's <B> -MD</B> option can produce output in the wrong directory |
| 1218 |
if the source and object files are in different directories and |
| 1219 |
the <B> -MF</B> option is not used. There is no perfect solution |
| 1220 |
because of incompatible changes between gcc versions. Explicitly |
| 1221 |
specifying the dependency output file with <B> -MF</B> will fix |
| 1222 |
the problem.<BR> |
| 1223 |
<P> |
| 1224 |
TCP mode connections should only be used on trusted networks.<BR> |
| 1225 |
<P> |
| 1226 |
Including slow machines in the list of volunteer hosts can slow |
| 1227 |
the build down.<BR> |
| 1228 |
<P> |
| 1229 |
When distcc or ccache is used on NFS, the filesystem must be exported |
| 1230 |
with the <B> no_subtree_check</B> option to allow reliable renames |
| 1231 |
between directories.<BR> |
| 1232 |
<P> |
| 1233 |
The compiler can be invoked with a command line <B> gcc hello.c</B> |
| 1234 |
to both compile and link. distcc doesn't split this into separate |
| 1235 |
parts, but rather runs the whole thing locally.<BR> |
| 1236 |
<P> |
| 1237 |
distcc-pump mode reverts to plain distcc mode for source files |
| 1238 |
that contain includes with absolute paths (either directly or |
| 1239 |
in an included file).<BR> |
| 1240 |
<P> |
| 1241 |
Due to limitations in gcc, gdb may not be able to automatically |
| 1242 |
find the source files for programs built using distcc in some |
| 1243 |
circumstances. The gdb <B> directory</B> command can be used. |
| 1244 |
For distcc's plain (non-pump) mode, this is fixed in gcc 3.4 and |
| 1245 |
later. For pump mode, the fix in gcc 3.4 does not suffice; we've |
| 1246 |
worked around the gcc limitation by rewriting the object files |
| 1247 |
that gcc produces, but this is only done for ELF object files, |
| 1248 |
but not for other object file formats.<BR> |
| 1249 |
<P> |
| 1250 |
The .o files produced by discc in pump mode will be different |
| 1251 |
from those produced locally: for non-ELF files, the debug information |
| 1252 |
will specify compile directories of the server. The code itself |
| 1253 |
should be identical.<BR> |
| 1254 |
<P> |
| 1255 |
For the ELF-format, distcc rewrites the .o files to correct compile |
| 1256 |
directory path information. While the resulting .o files are |
| 1257 |
not bytewise identical to what would have been produced by compiling |
| 1258 |
on the local client (due to different padding, etc), they should |
| 1259 |
be functionally identical.<BR> |
| 1260 |
<P> |
| 1261 |
In distcc-pump mode, the include server is unable to handle certain |
| 1262 |
very complicated computed includes as found in parts of the Boost |
| 1263 |
library. The include server will time out and distcc will revert |
| 1264 |
to plain mode.<BR> |
| 1265 |
<P> |
| 1266 |
In distcc-pump mode, certain assumptions are made that source |
| 1267 |
and header files do not change during the build. See discussion |
| 1268 |
in section DISTCC DISCREPANCY SYMPTOMS of <B>include_server</B>(1().<BR> |
| 1269 |
Other known bugs may be documented on <I> http://code.google.com/p/distcc/</I><BR> |
| 1270 |
<H2> |
| 1271 |
<A NAME=TOC_25> |
| 1272 |
AUTHOR</A> |
| 1273 |
</H2> |
| 1274 |
distcc was written by Martin Pool <[email protected]>, |
| 1275 |
with the co-operation of many scholars including Wayne Davison, |
| 1276 |
Frerich Raabe, Dimitri Papadopoulos and others noted in the NEWS |
| 1277 |
file. Please report bugs to <[email protected]>. |
| 1278 |
See <B>pump</B>(1) for the authors of pump mode.<BR> |
| 1279 |
<H2> |
| 1280 |
<A NAME=TOC_26> |
| 1281 |
LICENCE</A> |
| 1282 |
</H2> |
| 1283 |
You are free to use distcc. distcc (including this manual) may |
| 1284 |
be copied, modified or distributed only under the terms of the |
| 1285 |
GNU General Public Licence version 2 or later. distcc comes with |
| 1286 |
absolutely no warrany. A copy of the GPL is included in the file |
| 1287 |
COPYING.<BR> |
| 1288 |
<H2> |
| 1289 |
<A NAME=TOC_27> |
| 1290 |
SEE ALSO</A> |
| 1291 |
</H2> |
| 1292 |
<B>distccd</B>(1), <B>pump</B>(1), <B>include_server</B>(1), <B>gcc</B>(1), |
| 1293 |
<B>make</B>(1), and <B>ccache</B>(1). <I> http://code.google.com/p/distcc/</I> |
| 1294 |
<I>https://ccache.dev/</I><BR> |
| 1295 |
</BODY> |
| 1296 |
</HTML> |