diff options
| author | Craig Silverstein <csilvers@khanacademy.org> | 2008-06-07 01:10:55 +0000 |
|---|---|---|
| committer | Craig Silverstein <csilvers@khanacademy.org> | 2008-06-07 01:10:55 +0000 |
| commit | 6aa68894ae232051950b5ec74ac871f8c5c4b1d1 (patch) | |
| tree | 41acedd22d8eaf2d79c7feb02a27fdf8cef12dd4 | |
| parent | 4ebbff11402cd292f4a7ada4be4b5cdd01c2e060 (diff) | |
| download | distcc-git-6aa68894ae232051950b5ec74ac871f8c5c4b1d1.tar.gz | |
Update from the empty file.
| -rw-r--r-- | doc/web/man/distcc_1.html | 1022 |
1 files changed, 1022 insertions, 0 deletions
diff --git a/doc/web/man/distcc_1.html b/doc/web/man/distcc_1.html index e69de29..bac83ad 100644 --- a/doc/web/man/distcc_1.html +++ b/doc/web/man/distcc_1.html @@ -0,0 +1,1022 @@ +<HTML> +<!-- this file was generated by troffcvt and tc2html --> +<HEAD> +<TITLE> +distcc manual page +</TITLE> +</HEAD> +<BODY> +<H1> +distcc manual page<BR> +</H1> +<P> +<H2> +Table of Contents +</H2> +<!-- INSERT TOC HERE, MAYBE --> +<!-- TOC BEGIN --> +<UL> +<LI> +<A HREF=#TOC_1> NAME</A> +<LI> +<A HREF=#TOC_2> SYNOPSIS</A> +<LI> +<A HREF=#TOC_3> DESCRIPTION</A> +<LI> +<A HREF=#TOC_4> QUICKSTART</A> +<LI> +<A HREF=#TOC_5> QUICKSTART FOR DISTCC-PUMP MODE</A> +<LI> +<A HREF=#TOC_6> HOW PLAIN (NON-PUMP) DISTCC WORKS</A> +<LI> +<A HREF=#TOC_7> HOW DISTCC-PUMP MODE WORKS</A> +<LI> +<A HREF=#TOC_8> OPTION SUMMARY</A> +<LI> +<A HREF=#TOC_9> INSTALLING DISTCC</A> +<LI> +<A HREF=#TOC_10> MASQUERADING</A> +<LI> +<A HREF=#TOC_11> USING DISTCC WITH CCACHE</A> +<LI> +<A HREF=#TOC_12> HOST SPECIFICATIONS</A> +<LI> +<A HREF=#TOC_13> COMPRESSION</A> +<LI> +<A HREF=#TOC_14> SEARCH PATHS</A> +<LI> +<A HREF=#TOC_15> TIMEOUTS</A> +<LI> +<A HREF=#TOC_16> DIAGNOSTICS</A> +<LI> +<A HREF=#TOC_17> EXIT CODES</A> +<LI> +<A HREF=#TOC_18> FILES</A> +<LI> +<A HREF=#TOC_19> ENVIRONMENT VARIABLES</A> +<LI> +<A HREF=#TOC_20> CROSS COMPILING</A> +<LI> +<A HREF=#TOC_21> BUGS</A> +<LI> +<A HREF=#TOC_22> AUTHOR</A> +<LI> +<A HREF=#TOC_23> LICENCE</A> +<LI> +<A HREF=#TOC_24> SEE ALSO</A> +</UL> +<!-- TOC END --> +<BR> +<H2> +<A NAME=TOC_1> +NAME</A> +</H2> +distcc - distributed C/C++/ObjC compiler with distcc-pump extensions<BR> +<H2> +<A NAME=TOC_2> +SYNOPSIS</A> +</H2> +<B>distcc</B> <I> <compiler> [COMPILER OPTIONS]</I><BR> +<P> +<B>distcc</B> <I> [COMPILER OPTIONS]</I><BR> +<P> +<B><compiler></B> <I> [COMPILER OPTIONS]</I><BR> +<P> +<B>distcc</B> <I> [DISTCC OPTIONS]</I><BR> +<H2> +<A NAME=TOC_3> +DESCRIPTION</A> +</H2> +distcc distributes compilation of C code across several machines +on a network. distcc should always generate the same results +as a local compile, it is simple to install and use, and it is +often much faster than a local compile.<BR> +<P> +This version incorporates plain distcc as well as an enhancement +called pump mode or distcc-pump.<BR> +<P> +For each job, distcc in plain mode sends the complete preprocessed +source code and compiler arguments across the network from the +client to a compilation server. In pump mode, distcc sends the +source code and recursively included header files, so that both +preprocessing and compilation can take place on the compilation +servers. This speeds up the delivery of compilations by up to +an order of magnitude over plain distcc.<BR> +<P> +Compilation is driven by a client machine, which is typically +the developer's workstation or laptop. The distcc client runs +on this machine, as does make, the preprocessor (if distcc's pump +mode is not used), the linker, and other stages of the build process. +Any number of volunteer machines act as compilation servers and +help the client to build the program, by running the <B> distccd(1)</B> +daemon, C compiler and assembler as required.<BR> +<P> +distcc can run across either TCP sockets (on port 3632 by default), +or through a tunnel command such as ssh(1). For TCP connections +the volunteers must run the distccd(1) daemon either directly +or from inetd. For SSH connections distccd must be installed but +should <B> not</B> be listening for connections.<BR> +<P> +TCP connections should only be used on secure networks because +there is no user authentication or protection of source or object +code. SSH connections are typically 25% slower because of processor +overhead for encryption, although this can vary greatly depending +on CPUs, network and the program being built.<BR> +<P> +distcc is intended to be used with GNU Make's <B> -j</B> option, +which runs several compiler processes concurrently. distcc spreads +the jobs across both local and remote CPUs. Because distcc is +able to distribute most of the work across the network, a higher +concurrency level can be used than for local builds. As a rule +of thumb, the <B> -j</B> value should be set to about twice the +total number of available server CPUs but subject to client limitations. +This setting allows for maximal interleaving of tasks being blocked +waiting for disk or network IO. Note that distcc can also work +with other build control tools, such as SCons, where similar concurrency +settings must be adjusted.<BR> +<P> +The <B> -j</B> setting, especially for large values of -j, must +take into account the CPU load on the client. Additional measures +may be needed to curtail the client load. For example, concurrent +linking should be severely curtailed using auxiliary locks. The +effect of other build activity, such as Java compilation when +building mixed code, should be considered. The <B> --localslots_cpp</B> +parameter is by default set to 16. This limits the number of concurrent +processes that do preprocessing in plain distcc (non-pump) mode. +Therefore, larger <B> -j</B> values than 16 may be used without +overloading a single-CPU client due to preprocessing. Such large +values may speed up parts of the build that do not involve C compilations, +but they may not be useful to distcc efficiency in plain mode.<BR> +<P> +In contrast, using pump mode and say 40 servers, a setting of +<B>-j80</B> or larger may be appropriate even for single-CPU clients.<BR> +<P> +It is strongly recommended that you install the same compiler +version on all machines participating in a build. Incompatible +compilers may cause mysterious compile or link failures.<BR> +<H2> +<A NAME=TOC_4> +QUICKSTART</A> +</H2> +<BR> +<DL> +<DT> +1 +</DT> +<DD> +For each machine, download distcc, unpack, and install.<BR> +</DD> +<DT> +2 +</DT> +<DD> +On each of the servers, run <B> distccd --daemon</B> with <B> +--allow</B> options to restrict access.<BR> +</DD> +<DT> +3 +</DT> +<DD> +Put the names of the servers in your environment:<BR> +</DD> +</DL> +<UL> +$ export DISTCC_HOSTS='localhost red green blue'<BR> +</UL> +<DL> +<DT> +4 +</DT> +<DD> +Build!<BR> +</DD> +</DL> +<UL> +$ make -j8 CC=distcc<BR> +</UL> +<H2> +<A NAME=TOC_5> +QUICKSTART FOR DISTCC-PUMP MODE</A> +</H2> +Proceed as above, but in Step 3, specify that the remote hosts +are to carry the burden of preprocessing and that the files sent +over the network should be compressed:<BR> +<P> +<UL> +$ export DISTCC_HOSTS='--randomize localhost red,cpp,lzo green,cpp,lzo +blue,cpp,lzo'<BR> +</UL> +<P> +The <B> --randomize</B> option enforces a uniform usage of compile +servers. While you will get some benefit from distcc's pump mode +with only a few servers, you get increasing benefit with more +server CPUs (up to the hundreds!). Wrap your build inside the +pump command, here assuming 10 servers:<BR> +<P> +<UL> +$ pump make -j20 CC=distcc<BR> +</UL> +<H2> +<A NAME=TOC_6> +HOW PLAIN (NON-PUMP) DISTCC WORKS</A> +</H2> +distcc only ever runs the compiler and assembler remotely. With +plain distcc, the preprocessor must always run locally because +it needs to access various header files on the local machine which +may not be present, or may not be the same, on the volunteer. +The linker similarly needs to examine libraries and object files, +and so must run locally.<BR> +<P> +The compiler and assembler take only a single input file (the +preprocessed source) and produce a single output (the object file). +distcc ships these two files across the network and can therefore +run the compiler/assembler remotely.<BR> +<P> +Fortunately, for most programs running the preprocessor is relatively +cheap, and the linker is called relatively infrequent, so most +of the work can be distributed.<BR> +<P> +distcc examines its command line to determine which of these phases +are being invoked, and whether the job can be distributed.<BR> +<P> +<H2> +<A NAME=TOC_7> +HOW DISTCC-PUMP MODE WORKS</A> +</H2> +In pump mode, distcc runs the prepreprocessor remotely too. To +do so, the preprocessor must have access to all the files that +it would have accessed if had been running locally. In pump mode, +therefore, distcc gathers all of the recursively included headers, +except the ones that are part of the compiler installation, and +sends them along with the source file to the compilation server.<BR> +<P> +In distcc-pump mode, the server unpacks the set of all source +files in a temporary directory, which contains a directory tree +that mirrors the part of the file system that is relevant to preprocessing, +including symbolic links.<BR> +<P> +The compiler is then run from the path in the temporary directory +that corresponds to the current working directory on the client. +To find and transmit the many hundreds of files that are often +part of a single compilation, pump mode uses an incremental include +analysis algorithm. The include server is a Python program that +implements this algorithm. The pump command starts the include +server so that throughout the build it can answer include queries +by distcc commands.<BR> +<P> +The include server uses static analysis of the macro language +to deal with conditional compilation and computed includes. It +uses the property that when a given header file has already been +analyzed for includes, it is not necessary to do so again if all +the include options (-I's) are unchanged (along with other conditions).<BR> +<P> +For large builds, header files are included, on average, hundreds +of times each. With distcc-pump mode each such file is analyzed +only a few times, perhaps just once, instead of being preprocessed +hundreds of times. Also, each source or header file is now compressed +only once, because the include server memoizes the compressed +files. As a result, the time used for preparing compilations +may drop by up to an order of magnitude over the preprocessing +of plain distcc.<BR> +<P> +Because distcc in pump mode is able to push out files up to about +ten times faster, build speed may increase 3X or more for large +builds compared to plain distcc mode.<BR> +<P> +Using pump mode requires both client and servers to use release +3.0 or later of distcc and distccd (respectively).<BR> +<P> +Note that the incremental include analysis of distc-pump mode +rests on the fundamental assumption that source and header files +do not change during the build process. A few complex build systems, +such as that for Linux kernel 2.6, do not quite satisfy this requirement. +To overcome such issues, and other corner cases such as absolute +filepaths in includes, see the include_server(1) man page.<BR> +<P> +<P> +<H2> +<A NAME=TOC_8> +OPTION SUMMARY</A> +</H2> +Most options passed to distcc are interpreted as compiler options. +The following options are understood by distcc itself:<BR> +<DL> +<DT> +<B>--help</B> +</DT> +<DD> +Displays summary instructions.<BR> +</DD> +<DT> +<B>--version</B> +</DT> +<DD> +Displays the distcc client version.<BR> +</DD> +<DT> +<B>--show-hosts</B> +</DT> +<DD> +Displays the host list that distcc would use. See the Host Specifications +section.<BR> +</DD> +<DT> +<B>-j</B> +</DT> +<DD> +Displays distcc's concurrency level, as calculated from the host +list; it is the maximum number of outstanding jobs issued by this +client to all servers By default this will be four times the number +of hosts in the host list, unless the /LIMIT option was used in +the host list. See the Host Specifications section.<BR> +</DD> +</DL> +<H2> +<A NAME=TOC_9> +INSTALLING DISTCC</A> +</H2> +There are three different ways to call distcc, to suit different +circumstances:<BR> +<UL> +<P> +distcc can be installed under the name of the real compiler, to +intercept calls to it and run them remotely. This "masqueraded" +compiler has the widest compatibility with existing source trees, +and is convenient when you want to use distcc for all compilation. +The fact that distcc is being used is transparent to the makefiles.<BR> +<P> +distcc can be prepended to compiler command lines, such as "distcc +cc -c hello.c" or CC="distcc gcc". This is convenient +when you want to use distcc for only some compilations or to try +it out, but can cause trouble with some makefiles or versions +of libtool that assume $CC does not contain a space.<BR> +<P> +Finally, distcc can be used directly as a compiler. "cc" +is always used as the name of the real compiler in this "implicit" +mode. This can be convenient for interactive use when "explicit" +mode does not work but is not really recommended for new use.<BR> +</UL> +<P> +Remember that you should not use two methods for calling distcc +at the same time. If you are using a masquerade directory, don't +change CC and/or CXX, just put the directory early on your PATH. +If you're not using a masquerade directory, you'll need to either +change CC and/or CXX, or modify the makefile(s) to call distcc +explicitly.<BR> +<H2> +<A NAME=TOC_10> +MASQUERADING</A> +</H2> +The basic idea is to create a "masquerade directory" +which contains links from the name of the real compiler to the +distcc binary. This directory is inserted early on the PATH, +so that calls to the compiler are intercepted and distcc is run +instead. distcc then removes itself from the PATH to find the +real compiler.<BR> +<P> +For example:<BR> +<P> +<UL> +# mkdir /usr/lib/distcc/bin<BR> +# cd /usr/lib/distcc/bin<BR> +# ln -s ../../../bin/distcc gcc<BR> +# ln -s ../../../bin/distcc cc<BR> +# ln -s ../../../bin/distcc g++<BR> +# ln -s ../../../bin/distcc c++<BR> +</UL> +<P> +Then, to use distcc, a user just needs to put the directory /usr/lib/distcc/bin +early in the PATH, and have set a host list in DISTCC_HOSTS or +a file. distcc will handle the rest.<BR> +<P> +Note that this masquerade directory must occur on the PATH earlier +than the directory that contains the actual compilers of the same +names, and that any auxiliary programs that these compilers call +(such as as or ld) must also be found on the PATH in a directory +after the masquerade directory since distcc calls out to the real +compiler with a PATH value that has all directory up to and including +the masquerade directory trimmed off.<BR> +<P> +It is possible to get a "recursion error" in masquerade +mode, which means that distcc is somehow finding itself again, +not the real compiler. This can indicate that you have two masquerade +directories on the PATH, possibly because of having two distcc +installations in different locations. It can also indicate that +you're trying to mix "masqueraded" and "explicit" +operation.<BR> +<P> +Recursion errors can be avoided by using shell scripts instead +of links. For example, in /usr/lib/distcc/bin create a file cc +which contains:<BR> +<P> +<UL> +#!/bin/sh<BR> +distcc /usr/bin/gcc "$@"<BR> +</UL> +<P> +In this way, we are not dependent on distcc having to locate the +real gcc by investigating the PATH variable. Instead, the compiler +location is explicitly provided.<BR> +<P> +<H2> +<A NAME=TOC_11> +USING DISTCC WITH CCACHE</A> +</H2> +ccache is a program that speeds software builds by caching the +results of compilations. ccache is normally called before distcc, +so that results are retrieved from a normal cache. Some experimentation +may be required for idiosyncratic makefiles to make everything +work together.<BR> +<P> +The most reliable method is to set<BR> +<DL> +<DT> +<P> +<BR> +</DT> +<DD> +<B>CCACHE_PREFIX="distcc"</B><BR> +</DD> +</DL> +<P> +This tells ccache to run distcc as a wrapper around the real compiler. +ccache still uses the real compiler to detect compiler upgrades.<BR> +<P> +ccache can then be run using either a masquerade directory <I> +or</I> by setting<BR> +<DL> +<DT> +<P> +<BR> +</DT> +<DD> +<B>CC="ccache gcc"</B><BR> +</DD> +</DL> +<P> +As of version 2.2, ccache does not cache compilation from preprocessed +source and so will never get a cache hit if it is run from distccd +or distcc. It must be run only on the client side and before +distcc to be any use.<BR> +<P> +distcc's pump mode is not compatible with ccache.<BR> +<H2> +<A NAME=TOC_12> +HOST SPECIFICATIONS</A> +</H2> +A "host list" tells distcc which machines to use for +compilation. In order, distcc looks in the <B> $DISTCC_HOSTS</B> +environment variable, the user's <B> $DISTCC_DIR/hosts</B> file, +and the system-wide host file. If no host list can be found, +distcc emits a warning and compiles locally.<BR> +<P> +The host list is a simple whitespace separated list of host specifications. +The simplest and most common form is a host names, such as<BR> +<P> +<UL> +<B>localhost red green blue</B><BR> +</UL> +<P> +distcc prefers hosts towards the start of the list, so machines +should be listed in descending order of speed. In particular, +when only a single compilation can be run (such as from a configure +script), the first machine listed is used (but see <I> --randomize</I> +below).<BR> +<P> +Placing <I> localhost</I> at the right point in the list is important +to getting good performance. Because overhead for running jobs +locally is low, localhost should normally be first. However, +it is important that the client have enough cycles free to run +the local jobs and the distcc client. If the client is slower +than the volunteers, or if there are many volunteers, then the +client should be put later in the list or not at all. As a general +rule, if the aggregate CPU speed of the client is less than one +fifth of the total, then the client should be left out of the +list.<BR> +<P> +If you have a large shared build cluster and a single shared hosts +file, the above rules would cause the first few machines in the +hosts file to be tried first even though they are likely to be +busier than machines later in the list. To avoid this, place +the keyword <I> --randomize</I> into the host list. This will +cause the host list to be randomized, which should improve performance +slightly for large build clusters.<BR> +<P> +There are two special host names <B> --localslots</B> and <B> +--localslots_cpp</B> which are useful for adjusting load on the +local machine. The <B> --localslots</B> host specifies how many +jobs that cannot be run remotely that can be run concurrently +on the local machine, while <B> --localslots_cpp</B> controls +how many preprocessors will run in parallel on the local machine. +Tuning these values can improve performance. Linking on large +projects can take large amounts of memory. Running parallel linkers, +which cannot be executed remotely, may force the machine to swap, +which reduces performance over just running the jobs in sequence +without swapping. Getting the number of parallel preprocessors +just right allows you to use larger parallel factors with make, +since the local machine now has some machanism for measuring local +resource usage.<BR> +<P> +Finally there is the host entry<BR> +<P> +Performance depends on the details of the source and makefiles +used for the project, and the machine and network speeds. Experimenting +with different settings for the host list and -j factor may improve +performance.<BR> +<P> +The syntax is<BR> +<P> + DISTCC_HOSTS = HOSTSPEC ...<BR> + HOSTSPEC = LOCAL_HOST | SSH_HOST | TCP_HOST | OLDSTYLE_TCP_HOST<BR> + | GLOBAL_OPTION<BR> + | ZEROCONF<BR> + LOCAL_HOST = localhost[/LIMIT]<BR> + | --localslots=<int><BR> + | --localslots_cpp=<int><BR> + SSH_HOST = [USER]@HOSTID[/LIMIT][:COMMAND][OPTIONS]<BR> + TCP_HOST = HOSTID[:PORT][/LIMIT][OPTIONS]<BR> + OLDSTYLE_TCP_HOST = HOSTID[/LIMIT][:PORT][OPTIONS]<BR> + HOSTID = HOSTNAME | IPV4<BR> + OPTIONS = ,OPTION[OPTIONS]<BR> + OPTION = lzo | cpp<BR> + GLOBAL_OPTION = --randomize<BR> + ZEROCONF = +zeroconf<BR> +<P> +Here are some individual examples of the syntax:<BR> +<DL> +<DT> +<B>localhost</B> +</DT> +<DD> +The literal word "localhost" is interpreted specially +to cause compilations to be directly executed, rather than passed +to a daemon on the local machine. If you do want to connect to +a daemon on the local machine for testing, then give the machine's +IP address or real hostname. (This will be slower.)<BR> +</DD> +<DT> +<B>IPV4</B> +</DT> +<DD> +A literal IPv4 address, such as <B> 10.0.0.1</B><BR> +</DD> +<DT> +<B>HOSTNAME</B> +</DT> +<DD> +A hostname to be looked up using the resolver.<BR> +</DD> +<DT> +<B>:PORT</B> +</DT> +<DD> +Connect to a specified decimal port number, rather than the default +of 3632.<BR> +</DD> +<DT> +<B>@HOSTID</B> +</DT> +<DD> +Connect to the host over SSH, rather than TCP. Options for the +SSH connection can be set in <B> ~/.ssh/config</B><BR> +</DD> +<DT> +<B>USER@</B> +</DT> +<DD> +Connect to the host over SSH as a specified username.<BR> +</DD> +<DT> +<B>:COMMAND</B> +</DT> +<DD> +Connect over SSH, and use a specified path to find the distccd +server. This is normally only needed if for some reason you can't +install distccd into a directory on the default PATH for SSH connections. +Use this if you get errors like "distccd: command not found" +in SSH mode.<BR> +</DD> +<DT> +<B>/LIMIT</B> +</DT> +<DD> +A decimal limit can be added to any host specification to restrict +the number of jobs that this client will send to the machine. +The limit defaults to four per host (two for localhost), but may +be further restricted by the server. You should only need to +increase this for servers with more than two processors.<BR> +</DD> +<DT> +<B>,lzo</B> +</DT> +<DD> +Enables LZO compression for this TCP or SSH host.<BR> +</DD> +<DT> +<B>,cpp</B> +</DT> +<DD> +Enables distcc-pump mode for this host. Note: the build command +must be wrapped in the pump script in order to start the include +server.<BR> +</DD> +<DT> +<B>--randomize</B> +</DT> +<DD> +Randomize the order of the host list before execution.<BR> +</DD> +<DT> +<B>+zeroconf</B> +</DT> +<DD> +<B>This option is only available if distcc was compiled with Avahi +support enabled at configure time.</B> When this special entry +is present in the hosts list, distcc will use Avahi Zeroconf DNS +Service Discovery (DNS-SD) to locate any available distccd servers +on the local network. This avoids the need to explicitly list +the host names or IP addresses of the distcc server machines. +The distccd servers must have been started with the "--zeroconf" +option to distccd. An important caveat is that in the current +implementation, pump mode (",cpp") and compression (",lzo") +will never be used for hosts located via zeroconf.<BR> +</DD> +</DL> +<P> +Here is an example demonstrating some possibilities:<BR> +<P> +<UL> +<B> localhost/2 @bigman/16:/opt/bin/distccd oldmachine:4200/1</B><BR> +<B> # cartman is down</B><BR> +<B> distant/3,lzo</B><BR> +</UL> +<P> +Comments are allowed in host specifications. Comments start with +a hash/pound sign (<B>#</B>) and run to the end of the line.<BR> +<P> +If a host in the list is not reachable distcc will emit a warning +and ignore that host for about one minute.<BR> +<H2> +<A NAME=TOC_13> +COMPRESSION</A> +</H2> +The <B> lzo</B> host option specifies that LZO compression should +be used for data transfer, including preprocessed source, object +code and error messages. Compression is usually economical on +networks slower than 100Mbps, but results may vary depending on +the network, processors and source tree.<BR> +<P> +Enabling compression makes the distcc client and server use more +CPU time, but less network traffic. The added CPU time is insignificant +for pump mode. The compression ratio is typically 4:1 for source +and 2:1 for object code.<BR> +<P> +Using compression requires both client and server to use at least +release 2.9 of distcc. No server configuration is required: the +server always responds with compressed replies to compressed requests.<BR> +<P> +Pump mode requires the servers to have the lzo host option on.<BR> +<H2> +<A NAME=TOC_14> +SEARCH PATHS</A> +</H2> +<BR> +<P> +If the compiler name is an absolute path, it is passed verbatim +to the server and the compiler is run from that directory. For +example:<BR> +<P> +<UL> +<B>distcc /usr/local/bin/gcc-3.1415 -c hello.c</B><BR> +</UL> +<P> +If the compiler name is not absolute, or not fully qualified, +distccd's PATH is searched. When distcc is run from a masquerade +directory, only the base name of the compiler is used. The client's +PATH is used only to run the preprocessor and has no effect on +the server's path.<BR> +<H2> +<A NAME=TOC_15> +TIMEOUTS</A> +</H2> +<BR> +<P> +Both the distcc client and server impose timeouts on transfer +of data across the network. This is intended to detect hosts +which are down or unreachable, and to prevent compiles hanging +indefinitely if a server is disconnected while in use. If a client-side +timeout expires, the job will be re-run locally.<BR> +<P> +The timeouts are not configurable at present.<BR> +<H2> +<A NAME=TOC_16> +DIAGNOSTICS</A> +</H2> +Error messages or warnings from local or remote compilers are +passed through to diagnostic output on the client.<BR> +<P> +distcc can supply extensive debugging information when the verbose +option is used. This is controlled by the <B> DISTCC_VERBOSE</B> +environment variable on the client, and the <B> --verbose</B> +option on the server. For troubleshooting, examine both the client +and server error messages.<BR> +<H2> +<A NAME=TOC_17> +EXIT CODES</A> +</H2> +The exit code of distcc is normally that of the compiler: zero +for successful compilation and non-zero otherwise.<BR> +<P> +distcc distinguishes between "genuine" errors such as +a syntax error in the source, and "accidental" errors +such as a networking problem connecting to a volunteer. In the +case of accidental errors, distcc will retry the compilation locally +unless the DISTCC_FALLBACK option has been disabled.<BR> +<P> +If the compiler exits with a signal, distcc returns an exit code +of 128 plus the signal number.<BR> +<P> +distcc internal errors cause an exit code between 100 and 127. +In particular<BR> +<DL> +<DT> +100 +</DT> +<DD> +General distcc failure.<BR> +</DD> +<DT> +105 +</DT> +<DD> +Out of memory.<BR> +</DD> +<DT> +110 +</DT> +<DD> +The given compiler was not found on the remote host. Check that +$CC is set appropriately and that it's installed in a directory +on the search path for distccd.<BR> +</DD> +<DT> +111 +</DT> +<DD> +Recursive call to distcc.<BR> +</DD> +<DT> +116 +</DT> +<DD> +No hosts defined and fallbacks disabled.<BR> +</DD> +</DL> +<P> +(Others are listed in exitcode.h.)<BR> +<H2> +<A NAME=TOC_18> +FILES</A> +</H2> +If $DISTCC_HOSTS is not set, distcc reads a host list from either +<B>$DISTCC_DIR/hosts</B> or a system-wide configuration file set +at compile time. The file locations are shown in the output from +<B>distcc --help</B><BR> +<P> +distcc creates a number of temporary and lock files underneath +the temporary directory.<BR> +<H2> +<A NAME=TOC_19> +ENVIRONMENT VARIABLES</A> +</H2> +distcc's behaviour is controlled by a number of environment variables. +For most cases nothing need be set if the host list is stored +in a file.<BR> +<DL> +<DT> +<B>DISTCC_HOSTS</B> +</DT> +<DD> +Space-separated list of volunteer host specifications.<BR> +</DD> +<DT> +<B>DISTCC_VERBOSE</B> +</DT> +<DD> +If set to 1, distcc produces explanatory messages on the standard +error stream or in the log file. This can be helpful in debugging +problems. Bug reports should include verbose output.<BR> +</DD> +<DT> +<B>DISTCC_LOG</B> +</DT> +<DD> +Log file to receive messages from distcc itself, rather than stderr.<BR> +</DD> +<DT> +<B>DISTCC_FALLBACK</B> +</DT> +<DD> +By default distcc will compile locally if it fails to distribute +a job to the intended machine, or if no host list can be found. +If this variable is set to 0 then fallbacks are disabled and those +compilations will simply fail. Note that this does not affect +jobs which must always be local such as linking.<BR> +</DD> +<DT> +<B>DISTCC_SAVE_TEMPS</B> +</DT> +<DD> +If set to 1, temporary files are not deleted after use. Good +for debugging, or if your disks are too empty.<BR> +</DD> +<DT> +<B>DISTCC_TCP_CORK</B> +</DT> +<DD> +If set to 0, disable use of "TCP corks", even if they're +present on this system. Using corks normally helps pack requests +into fewer packets and aids performance. This should normally +be left enabled.<BR> +</DD> +<DT> +<B>DISTCC_SSH</B> +</DT> +<DD> +Specifies the command used for opening SSH connections. Defaults +to "ssh" but may be set to a different connection command +such as "lsh" or "tsocks-ssh" that accepts +a similar command line. The command is not split into words and +is not executed through the shell.<BR> +</DD> +<DT> +<B>DISTCC_DIR</B> +</DT> +<DD> +Per-user configuration directory to store lock files and state +files. By default <B> ~/.distcc/</B> is used.<BR> +</DD> +<DT> +<B>TMPDIR</B> +</DT> +<DD> +Directory for temporary files such as preprocessor output. By +default /tmp/ is used.<BR> +</DD> +<DT> +<B>UNCACHED_ERR_FD</B> +</DT> +<DD> +If set and if DISTCC_LOG is not set, distcc errors are written +to the file descriptor identified by this variable. This variable +is intended mainly for automatic use by ccache, which sets it +to avoid caching transient errors such as network problems.<BR> +</DD> +<DT> +<B>DISTCC_ENABLE_DISCREPANCY_EMAIL</B> +</DT> +<DD> +If set, distcc sends an email when a compilation failed remotely, +but succeeded locally. Built-in heuristics prevent some such +discrepancy email from being sent if the problem is that a local +file changed between the failing remote compilation and the succeeding +local compilation.<BR> +</DD> +<DT> +<B>DCC_EMAILLOG_WHOM_TO_BLAME</B> +</DT> +<DD> +The email address for discrepancy email; the default is "distcc-pump-errors".<BR> +</DD> +</DL> +<H2> +<A NAME=TOC_20> +CROSS COMPILING</A> +</H2> +Cross compilation means building programs to run on a machine +with a different processor, architecture, or operating system +to where they were compiled. distcc supports cross compilation, +including teams of mixed-architecture machines, although some +changes to the compilation commands may be required.<BR> +<P> +The compilation command passed to distcc must be one that will +execute properly on every volunteer machine to produce an object +file of the appropriate type. If the machines have different +processors, then simply using <B> distcc cc</B> will probably +not work, because that will normally invoke the volunteer's native +compiler.<BR> +<P> +Machines with the same CPU but different operating systems may +not necessarily generate compatible .o files.<BR> +<P> +Several different gcc configurations can be installed side-by-side +on any machine. If you build gcc from source, you should use +the <B> --program-suffix configuration</B> options to cause it +to be installed with a name that encodes the gcc version and the +target platform.<BR> +<P> +The recommended convention for the gcc name is <I> TARGET-gcc-VERSION</I> +such as <B> i686-linux-gcc-3.2</B> . GCC 3.3 will install itself +under this name, in addition to <I> TARGET-gcc</I> and, if it's +native, <I> gcc-VERSION</I> and <I> gcc</I> .<BR> +<P> +The compiler must be installed under the same name on the client +and on every volunteer machine.<BR> +<H2> +<A NAME=TOC_21> +BUGS</A> +</H2> +If you think you have found a distcc bug, please see the file +<I>reporting-bugs.txt</I> in the documentation directory for information +on how to report it.<BR> +<P> +Some makefiles have missing or extra dependencies that cause incorrect +or slow parallel builds. Recursive make is inefficient and can +leave processors unnecessarily idle for long periods. (See <I> +Recursive Make Considered Harmful</I> by Peter Miller.) Makefile +bugs are the most common cause of trees failing to build under +distcc. Alternatives to Make such as <I> SCons</I> can give much +faster builds for some projects.<BR> +<P> +Using different versions of gcc can cause confusing build problems +because the header files and binary interfaces have changed over +time, and some distributors have included incompatible patches +without changing the version number. distcc does not protect +against using incompatible versions. Compiler errors about link +problems or declarations in system header files are usually due +to mismatched or incorrectly installed compilers.<BR> +<P> +Due to limitations in gcc, gdb may not be able to automatically +find the source files for programs built using distcc in some +circumstances. The gdb <B> directory</B> command can be used. +This should be fixed in gcc 3.4.<BR> +<P> +gcc's <B> -MD</B> option can produce output in the wrong directory +if the source and object files are in different directories and +the <B> -MF</B> option is not used. There is no perfect solution +because of incompatible changes between gcc versions. Explicitly +specifying the dependency output file with <B> -MF</B> will fix +the problem.<BR> +<P> +TCP mode connections should only be used on trusted networks.<BR> +<P> +Including slow machines in the list of volunteer hosts can slow +the build down.<BR> +<P> +When distcc or ccache is used on NFS, the filesystem must be exported +with the <B> no_subtree_check</B> option to allow reliable renames +between directories.<BR> +<P> +The compiler can be invoked with a command line <B> gcc hello.c</B> +to both compile and link. distcc doesn't split this into separate +parts, but rather runs the whole thing locally.<BR> +<P> +distcc-pump mode reverts to plain distcc mode for source files +that contain includes with absolute paths (either directly or +in an included file).<BR> +<P> +The .o files produced by discc in pump mode will be different +from those produced locally: for non-ELF files, the debug information +will specify compile directories of the server. The code itself +should be identical.<BR> +<P> +For the ELF-format, distcc rewrites the .o files to correct compile +directory path information. While the resulting .o files are +not bytewise identical to what would have been produced by compiling +on the local client (due to different padding, etc), they should +be functionally identical.<BR> +<P> +In distcc-pump mode, the include server is unable to handle certain +very complicated computed includes as found in parts of the boost +library. The include server will time out and distcc will revert +to plain mode.<BR> +<P> +<P> +Other known bugs may be documented on <I> http://code.google.com/p/distcc/</I><BR> +<H2> +<A NAME=TOC_22> +AUTHOR</A> +</H2> +distcc was written by Martin Pool <mbp@sourcefrog.net>, +with the co-operation of many scholars including Wayne Davison, +Frerich Raabe, Dimitri Papadopoulos and others noted in the NEWS +file. Please report bugs to <distcc@lists.samba.org>. +See <B>pump</B>(1) for the authors of pump mode.<BR> +<H2> +<A NAME=TOC_23> +LICENCE</A> +</H2> +You are free to use distcc. distcc (including this manual) may +be copied, modified or distributed only under the terms of the +GNU General Public Licence version 2 or later. distcc comes with +absolutely no warrany. A copy of the GPL is included in the file +COPYING.<BR> +<H2> +<A NAME=TOC_24> +SEE ALSO</A> +</H2> +<B>distccd</B>(1), <B>pump</B>(1), <B>include_server</B>(1), <B>gcc</B>(1), +<B>make</B>(1), and <B>ccache</B>(1). <I> http://code.google.com/p/distcc/</I> +<I>http://ccache.samba.org/</I><BR> +</BODY> +</HTML> |