| 1 |
<HTML> |
| 2 |
<!-- this file was generated by troffcvt and tc2html --> |
| 3 |
<HEAD> |
| 4 |
<TITLE> |
| 5 |
pump manual page |
| 6 |
</TITLE> |
| 7 |
</HEAD> |
| 8 |
<BODY> |
| 9 |
<H1> |
| 10 |
pump 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> INVOKING LSDISTCC</A> |
| 27 |
<LI> |
| 28 |
<A HREF=#TOC_5> OPTIONS</A> |
| 29 |
<LI> |
| 30 |
<A HREF=#TOC_6> ENVIRONMENT VARIABLES</A> |
| 31 |
<LI> |
| 32 |
<A HREF=#TOC_7> EXAMPLE</A> |
| 33 |
<LI> |
| 34 |
<A HREF=#TOC_8> BUGS</A> |
| 35 |
<LI> |
| 36 |
<A HREF=#TOC_9> AUTHORS</A> |
| 37 |
<LI> |
| 38 |
<A HREF=#TOC_10> LICENCE</A> |
| 39 |
<LI> |
| 40 |
<A HREF=#TOC_11> SEE ALSO</A> |
| 41 |
</UL> |
| 42 |
<!-- TOC END --> |
| 43 |
<BR> |
| 44 |
<H2> |
| 45 |
<A NAME=TOC_1> |
| 46 |
NAME</A> |
| 47 |
</H2> |
| 48 |
pump - accelerate remote compilation with distcc<BR> |
| 49 |
<H2> |
| 50 |
<A NAME=TOC_2> |
| 51 |
SYNOPSIS</A> |
| 52 |
</H2> |
| 53 |
<B>pump</B> <I> BUILD-COMMAND [ARGS]</I> ...<B><BR> |
| 54 |
<P> |
| 55 |
</B>eval ' <B> pump</B> --startup '; <I> BUILD-COMMAND [ARGS]</I> |
| 56 |
... ; <B> pump</B> --shutdown<B><BR> |
| 57 |
<H2> |
| 58 |
<A NAME=TOC_3> |
| 59 |
</B>DESCRIPTION</A> |
| 60 |
</H2> |
| 61 |
<B>pump</B> is part of distcc. It is used for distcc's pump mode. |
| 62 |
Distcc's pump mode accelerates remote compilation with distcc |
| 63 |
by also distributing preprocessing to the servers.<BR> |
| 64 |
<P> |
| 65 |
For a detailed description of pump mode, including most notably |
| 66 |
some <B> important restrictions,</B> see the <B>distcc(1)</B> |
| 67 |
man page, in particular the <B> HOW PUMP-MODE WORKS</B> section |
| 68 |
and the <B> RESTRICTIONS ON PUMP MODE</B> section.<BR> |
| 69 |
<P> |
| 70 |
The simplest usage is the form<BR> |
| 71 |
<UL> |
| 72 |
<B>pump</B> <I> COMMAND [ARG]</I> ...<BR> |
| 73 |
</UL> |
| 74 |
This will start an include server for distcc's "pump" |
| 75 |
mode; optionally run <B> lsdistcc</B> to compute the distcc host |
| 76 |
list; set some auxiliary environment variables; change PATH to |
| 77 |
use the distcc client in the same directory as the "pump" |
| 78 |
script; execute <I> COMMAND</I> with the specified <I> ARG(s)</I> |
| 79 |
; and then shut down the include server. The <I> COMMAND</I> is |
| 80 |
typically a parallel build command, such as "make -j80", |
| 81 |
that will do many concurrent invocations of distcc.<BR> |
| 82 |
<P> |
| 83 |
An alternative way of invoking <B> pump</B> is to explicitly invoke |
| 84 |
"pump --startup" to start the include server and "pump |
| 85 |
--shutdown" to stop the include server. The "pump --startup" |
| 86 |
command will start up the include server, and will print out some |
| 87 |
environment variable settings. These environment variables are |
| 88 |
used to communicate between the pump-mode "distcc" client |
| 89 |
and the include server, and to communicate between "pump |
| 90 |
--startup" and "pump --shutdown". The caller of |
| 91 |
"pump --startup" is responsible for setting those environment |
| 92 |
variables before invoking "distcc" or "pump --shutdown".<BR> |
| 93 |
<P> |
| 94 |
For example:<BR> |
| 95 |
<UL> |
| 96 |
eval 'pump --startup'<BR> |
| 97 |
make -j80<BR> |
| 98 |
pump --shutdown<BR> |
| 99 |
</UL> |
| 100 |
<P> |
| 101 |
Note that distcc's pump-mode assumes that sources files will not |
| 102 |
be<BR> |
| 103 |
modified during the lifetime of the include server, so modifying |
| 104 |
source files during a build may cause inconsistent results.<BR> |
| 105 |
<H2> |
| 106 |
<A NAME=TOC_4> |
| 107 |
INVOKING LSDISTCC</A> |
| 108 |
</H2> |
| 109 |
When invoked in either the simple " <B> pump</B> <I> COMMAND |
| 110 |
[ARG]</I> ... " form, or as " <B> pump --startup</B> |
| 111 |
", the <B> pump</B> script will invoke <B> lsdistcc</B> |
| 112 |
whenever DISTCC_POTENTIAL_HOSTS is set and DISTCC_HOSTS isn't. |
| 113 |
It will pass the value of DISTCC_POTENTIAL_HOSTS to <B> lsdistcc</B> |
| 114 |
and use the output of <B> lsdistcc</B> to set DISTCC_HOSTS.<BR> |
| 115 |
<H2> |
| 116 |
<A NAME=TOC_5> |
| 117 |
OPTIONS</A> |
| 118 |
</H2> |
| 119 |
<BR> |
| 120 |
<DL> |
| 121 |
<DT> |
| 122 |
<B>--help</B> |
| 123 |
</DT> |
| 124 |
<DD> |
| 125 |
Displays summary instructions.<BR> |
| 126 |
</DD> |
| 127 |
<DT> |
| 128 |
<B>--startup</B> |
| 129 |
</DT> |
| 130 |
<DD> |
| 131 |
Starts an include server, and outputs the environment variable |
| 132 |
settings needed for <B>distcc(1)</B> or <B> pump --shutdown</B> |
| 133 |
to access it.<BR> |
| 134 |
</DD> |
| 135 |
<DT> |
| 136 |
<B>--shutdown</B> |
| 137 |
</DT> |
| 138 |
<DD> |
| 139 |
Shuts down an include server started up by <B> pump --startup.</B><BR> |
| 140 |
</DD> |
| 141 |
</DL> |
| 142 |
<H2> |
| 143 |
<A NAME=TOC_6> |
| 144 |
ENVIRONMENT VARIABLES</A> |
| 145 |
</H2> |
| 146 |
The following environment variables are all optional.<BR> |
| 147 |
<DL> |
| 148 |
<DT> |
| 149 |
<B>DISTCC_LOCATION</B> |
| 150 |
</DT> |
| 151 |
<DD> |
| 152 |
The location of the distcc bin directory, which is normally inferred |
| 153 |
from the link-resolved dirname of argv[0]. If this location is |
| 154 |
in fact the bin directory inside an installation (as will be the |
| 155 |
case when the pump script in the installation executes), then |
| 156 |
Python executables and distcc itself will be retrieved from the |
| 157 |
parent directory of the location.<BR> |
| 158 |
</DD> |
| 159 |
<DT> |
| 160 |
<B>DISTCC_MAX_DISCREPANCY</B> |
| 161 |
</DT> |
| 162 |
<DD> |
| 163 |
see the <B>distcc(1)</B> man page.<BR> |
| 164 |
</DD> |
| 165 |
<DT> |
| 166 |
<B>DISTCC_POTENTIAL_HOSTS</B> |
| 167 |
</DT> |
| 168 |
<DD> |
| 169 |
The distcc servers that will be queried by lsdistcc in order to |
| 170 |
produce a value for DISTCC_HOSTS. This value may be unset or null. |
| 171 |
In such cases, lsdistcc will not be invoked, and distcc will use |
| 172 |
DISTCC_HOSTS or the distcc hosts configuration file, as described |
| 173 |
in the "Host Specifications" section of <B>distcc(1).</B><BR> |
| 174 |
</DD> |
| 175 |
<DT> |
| 176 |
<B>DISTCC_HOSTS</B> |
| 177 |
</DT> |
| 178 |
<DD> |
| 179 |
This variable is passed through to distcc but only if DISTCC_POTENTIAL_HOSTS |
| 180 |
is not set.<BR> |
| 181 |
</DD> |
| 182 |
<DT> |
| 183 |
<B>LSDISTCC_ARGS</B> |
| 184 |
</DT> |
| 185 |
<DD> |
| 186 |
Extra arguments to pass to lsdistcc. See <B> lsdistcc --help</B> |
| 187 |
for more details.<BR> |
| 188 |
</DD> |
| 189 |
<DT> |
| 190 |
<B>INCLUDE_SERVER_ARGS |
| 191 |
</DT> |
| 192 |
<DD> |
| 193 |
Extra arguments to pass to the include server.<BR> |
| 194 |
</DD> |
| 195 |
<DT> |
| 196 |
</B><B>PYTHONOPTIMIZE |
| 197 |
</DT> |
| 198 |
<DD> |
| 199 |
If set to "", then Python optimization is disabled.<BR> |
| 200 |
</DD> |
| 201 |
</DL> |
| 202 |
<H2> |
| 203 |
<A NAME=TOC_7> |
| 204 |
</B>EXAMPLE</A> |
| 205 |
</H2> |
| 206 |
<B>pump make -j20</B><BR> |
| 207 |
<H2> |
| 208 |
<A NAME=TOC_8> |
| 209 |
BUGS</A> |
| 210 |
</H2> |
| 211 |
If you think you have found a distcc bug, please see the file |
| 212 |
<I>reporting-bugs.txt</I> in the documentation directory for information |
| 213 |
on how to report it.<BR> |
| 214 |
<H2> |
| 215 |
<A NAME=TOC_9> |
| 216 |
AUTHORS</A> |
| 217 |
</H2> |
| 218 |
The pump script and distcc's pump mode were written by Nils Klarlund, |
| 219 |
Manos Renieris, Fergus Henderson, and Craig Silverstein. Please |
| 220 |
report bugs to <[email protected]>.<BR> |
| 221 |
<H2> |
| 222 |
<A NAME=TOC_10> |
| 223 |
LICENCE</A> |
| 224 |
</H2> |
| 225 |
<B>pump</B> is part of distcc. You are free to use distcc. distcc |
| 226 |
(including this manual) may be copied, modified or distributed |
| 227 |
only under the terms of the GNU General Public Licence version |
| 228 |
2 or later. distcc comes with absolutely no warranty. A copy |
| 229 |
of the GPL is included in the file COPYING.<BR> |
| 230 |
<H2> |
| 231 |
<A NAME=TOC_11> |
| 232 |
SEE ALSO</A> |
| 233 |
</H2> |
| 234 |
<B>distcc</B>(1), <B>distccd</B>(1), <B>include_server</B>(1), |
| 235 |
<B>gcc</B>(1), and <B>make</B>(1)<BR> |
| 236 |
</BODY> |
| 237 |
</HTML> |