/[gentoo]/xml/htdocs/doc/en/distcc.xml
Gentoo

Diff of /xml/htdocs/doc/en/distcc.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.22 Revision 1.40
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/distcc.xml,v 1.22 2004/08/22 20:51:08 neysx Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/distcc.xml,v 1.40 2007/06/21 23:46:16 rane Exp $ -->
4 4
5<guide link="/doc/en/distcc.xml"> 5<guide link="/doc/en/distcc.xml">
6 6
7<title>Gentoo Distcc Documentation</title> 7<title>Gentoo Distcc Documentation</title>
8 8
9<author title="Author"> 9<author title="Author">
10 <mail link="lisa@gentoo.org">Lisa Seelye</mail> 10 <mail link="lisa@gentoo.org">Lisa Seelye</mail>
11</author> 11</author>
12
13<author title="Editor"> 12<author title="Editor">
14 <mail link="vapier@gentoo.org">Mike Frysinger</mail> 13 <mail link="vapier@gentoo.org">Mike Frysinger</mail>
15</author> 14</author>
16
17<author title="Editor"> 15<author title="Editor">
18 <mail link="erwin@gentoo.org">Erwin</mail> 16 <mail link="erwin@gentoo.org">Erwin</mail>
19</author> 17</author>
20
21<author title="Editor"> 18<author title="Editor">
22 <mail link="swift@gentoo.org">Sven Vermeulen</mail> 19 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
23</author> 20</author>
24
25<author title="Editor"> 21<author title="Editor">
26 <mail link="pylon@gentoo.org">Lars Weiler</mail> 22 <mail link="pylon@gentoo.org">Lars Weiler</mail>
27</author> 23</author>
28
29<author title="Reviewer"> 24<author title="Reviewer">
30 <mail link="blubber@gentoo.org">Tiemo Kieft</mail> 25 <mail link="blubber@gentoo.org">Tiemo Kieft</mail>
31</author> 26</author>
32 27
33<abstract> 28<abstract>
34This document serves as a HOWTO for using distcc with Gentoo. 29This document serves as a HOWTO for using distcc with Gentoo.
35</abstract> 30</abstract>
36 31
37<!-- The content of this document is licensed under the CC-BY-SA license --> 32<!-- The content of this document is licensed under the CC-BY-SA license -->
38<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> 33<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
39<license/> 34<license/>
40 35
41<version>1.8</version> 36<version>1.19</version>
42<date>August 22, 2004</date> 37<date>2007-06-22</date>
43 38
44<chapter> 39<chapter>
45<title>Introduction</title> 40<title>Introduction</title>
46<section> 41<section>
47<title>What is distcc?</title> 42<title>What is distcc?</title>
48<body> 43<body>
49 44
50<p> 45<p>
51Distcc is a program designed to distribute compiling tasks across a network to 46Distcc is a program designed to distribute compiling tasks across a network to
52participating hosts. It is comprised of a server, <c>distccd</c> and a client 47participating hosts. It is comprised of a server, <c>distccd</c>, and a client
53program, <c>distcc</c>. Distcc can work transparently with <uri 48program, <c>distcc</c>. Distcc can work transparently with <uri
54link="http://ccache.samba.org">ccache</uri> and Portage with a little work. 49link="http://ccache.samba.org">ccache</uri>, Portage, and Automake with a
50little setup.
55</p> 51</p>
56 52
57</body> 53</body>
58</section> 54</section>
59<section> 55<section>
60<title>Using distcc to bootstrap</title> 56<title>Using distcc to bootstrap</title>
61<body> 57<body>
62 58
63<p> 59<p>
64If you are planning on using distcc to help you bootstrap a Gentoo installation, 60If you are planning on using distcc to help you bootstrap a Gentoo
65make sure you read the part on <uri link="#bootstrapping">Using distcc to 61installation, make sure you read the section <uri link="#bootstrapping">Using
66Bootstrap</uri> which is situated further down in this document. 62distcc to Bootstrap</uri>, which is situated further down in this document.
67</p> 63</p>
68 64
69</body> 65</body>
70</section> 66</section>
71</chapter> 67</chapter>
75<section> 71<section>
76<title>Dependencies</title> 72<title>Dependencies</title>
77<body> 73<body>
78 74
79<p> 75<p>
80To start off with, to use Distcc all of the computers on your network need to 76In order to use Distcc, all of the computers on your network need to have the
81have the same GCC versions. Mixing 3.3.x (where the x varies) is okay, but 77same GCC versions. For example, mixing 3.3.x (where the x varies) is okay, but
82mixing 3.3.x and 3.2.x is not: your programs <b>will</b> have errors in it. 78mixing 3.3.x with 3.2.x <b>may</b> result in compilation errors or runtime
79errors.
83</p> 80</p>
84 81
85</body> 82</body>
86</section> 83</section>
87<section> 84<section>
88<title>Installing Distcc</title> 85<title>Installing Distcc</title>
89<body> 86<body>
90 87
91<p> 88<p>
92There are a couple of options you should know about before you start 89There are a couple of options you should be aware of before you start
93installing distcc. 90installing distcc.
94</p> 91</p>
95 92
96<p> 93<p>
97Distcc ships with a graphical monitor to monitor tasks that your computer is 94Distcc ships with a graphical monitor to monitor tasks that your computer is
102 99
103<pre caption="Installing distcc"> 100<pre caption="Installing distcc">
104# <i>emerge distcc</i> 101# <i>emerge distcc</i>
105</pre> 102</pre>
106 103
104<impo>
105Remember, you must be sure to install distcc on all of your participating
106machines.
107</impo>
108
107</body> 109</body>
108</section> 110</section>
109<section> 111<section>
110<title>Setting up Portage to use Distcc</title> 112<title>Setting up Portage to use Distcc</title>
111<body> 113<body>
112 114
113<p> 115<p>
114Setting up distcc is easy to do with Portage. Execute the following steps on 116Setting up Portage to use distcc is easy. Execute the following steps on
115each system that should participate in the distributed compiling: 117each system that should participate in the distributed compiling:
116</p> 118</p>
117 119
118<pre caption="Integrating Distcc and Portage"> 120<pre caption="Integrating Distcc and Portage">
119# <i>emerge distcc</i> 121# <i>emerge distcc distcc-config</i>
120# <i>nano -w /etc/make.conf</i> 122# <i>nano -w /etc/make.conf</i>
121<comment>(Set N to a suitable number for your particular setup)</comment> 123<comment>(Set N to a suitable number for your particular setup)</comment>
122<comment>(A common heuristic strategy is twice the number of total CPUs + 1)</comment> 124<comment>(A common strategy is setting N as twice the number of total CPUs + 1 available)</comment>
123MAKEOPTS="-jN" 125MAKEOPTS="-jN"
124<comment>(Add distcc to your FEATURES variable)</comment> 126<comment>(Add distcc to your FEATURES)</comment>
125FEATURES="distcc" 127FEATURES="distcc"
126</pre> 128</pre>
127 129
130</body>
131</section>
132<section>
133<title>Specifying Participating Hosts</title>
134<body>
135
128<p> 136<p>
129Next you have to specify what hosts you want to use. Use the
130<c>distcc-config</c> command to set the list of hosts. Here is an example of 137Use the <c>distcc-config</c> command to set the list of hosts. Here is an
131some hosts that might be in your list: 138example of some hosts that might be in your list:
132</p> 139</p>
133 140
134<pre caption="Examples of host definitions"> 141<pre caption="Examples of host definitions">
135192.168.0.1 192.168.0.2 192.168.0.3 142192.168.0.1 192.168.0.2 192.168.0.3
136192.168.0.1/2 192.168.0.2 192.168.0.3/10 143192.168.0.1/2 192.168.0.2 192.168.0.3/10
137192.168.0.1:4000/2 192.168.0.2/1 192.168.0.3:3632/4 144192.168.0.1:4000/2 192.168.0.2/1 192.168.0.3:3632/4
138@192.168.0.1 @192.168.0.2:/usr/bin/distccd 192.168.0.3 145@192.168.0.1 @192.168.0.2:/usr/bin/distccd 192.168.0.3
139<comment>(There are also several other methods of setting up hosts. See the 146<comment>(There are also several other methods of setting up hosts. See the
140distcc manpage for more details.)</comment> 147distcc manpage for more details.)</comment>
148<comment>If you wish to compile on the local machine you should put 'localhost'
149in the hosts list. Conversely if you do not wish to use the local machine to
150compile (which is often the case) omit it from the hosts list. On a slow
151machine using localhost may actually slow things down. Make sure to test your
152settings for performance.</comment>
141</pre> 153</pre>
142 154
143<p> 155<p>
144It may all look complicated, but in most cases a variant of line 1 or 2 will 156It may all look complicated, but in most cases a variant of line 1 or 2 will
145work. 157work.
146</p> 158</p>
147 159
148<ul>
149 <li>Line 1 is just a space-delimited list of hosts</li>
150 <li>
151 Line 2 is a list of hosts that specifies the maximum amount of jobs (by
152 defining the <c>/N</c> setting) to send that host at any given time
153 </li>
154</ul>
155
156<p> 160<p>
157Since most people won't be using lines 3 or 4, I'll <uri 161Since most people won't be using lines 3 or 4, I'll <uri
158link="http://distcc.samba.org/man/distcc_1.html">point you to</uri> the distcc 162link="http://distcc.samba.org/man/distcc_1.html">refer to</uri> the distcc
159docs for more information. 163docs (man distcc) for more information.
160</p> 164</p>
161 165
162<p> 166<p>
163For instance, to set the first line in the previous example: 167For instance, to set the first line in the previous example:
164</p> 168</p>
165 169
166<pre caption="Sample command to set the hosts"> 170<pre caption="Sample command to set the hosts">
167# <i>/usr/bin/distcc-config --set-hosts "192.168.0.1 192.168.0.2 192.168.0.3"</i> 171# <i>/usr/bin/distcc-config --set-hosts "192.168.0.1 192.168.0.2 192.168.0.3"</i>
168</pre> 172</pre>
173
174<p>
175Edit <path>/etc/conf.d/distccd</path> to your needs and be sure to set the
176<c>--allow</c> directive to allow only hosts you trust. For added security,
177you should also use the <c>--listen</c> directive to tell the distcc daemon
178what IP to listen on (for multi-homed systems). More information on distcc
179security can be found at <uri
180link="http://distcc.samba.org/security.html">Distcc Security Design</uri>.
181</p>
182
183<impo>
184It is important to use --allow and --listen. Please read the distccd manpage
185or the above security document for more information.
186</impo>
187
169 188
170<p> 189<p>
171Now start the distcc daemon on all the participating computers: 190Now start the distcc daemon on all the participating computers:
172</p> 191</p>
173 192
183<section> 202<section>
184<title>Setting up Distcc to Work With Automake</title> 203<title>Setting up Distcc to Work With Automake</title>
185<body> 204<body>
186 205
187<p> 206<p>
188This is in some cases easier than the Portage setup. What you have to do is 207This is, in some cases, easier than the Portage setup. What you have to do is
189update your <c>PATH</c> variable to include <path>/usr/lib/distcc/bin</path> 208update your <c>PATH</c> variable to include <path>/usr/lib/distcc/bin</path>
190in front of the directory that contains <c>gcc</c> (<path>/usr/bin</path>). 209in front of the directory that contains <c>gcc</c> (<path>/usr/bin</path>).
191However, there is a caveat. If you use ccache you have to put distcc after 210However, there is a caveat. If you use ccache you have to put distcc after
192the ccache part: 211the ccache part:
193</p> 212</p>
194 213
195<pre caption="Setting your path"> 214<pre caption="Setting your path">
196# <i>export PATH="/usr/lib/ccache/bin:/usr/lib/distcc/bin:${PATH}"</i> 215# <i>export PATH="/usr/lib/ccache/bin:/usr/lib/distcc/bin:${PATH}"</i>
216<comment>(You can put this in your ~/.bashrc or equivalent file to have the PATH
217set every time you log in)</comment>
197</pre> 218</pre>
198 219
199<p> 220<p>
200Then, as you would normally type <c>make</c>, you would type <c>make -jN</c> 221Then, as you would normally type <c>make</c>, you would type <c>make -jN</c>
201(where N is an integer). The value of N depends on your network and the types 222(where N is an integer). The value of N depends on your network and the types
202of computers you are using to compile. For me, I have a dual processor P3 and 223of computers you are using to compile. Test your own settings to find the
203a K6-2/400 that compiles everything for my desktop (a 1200MHz Athlon
204Thunderbird) and I use -j5. Test your own settings to find the number that
205yields the best performance. 224number that yields the best performance.
206</p> 225</p>
207 226
208</body> 227</body>
209</section> 228</section>
210</chapter> 229</chapter>
211 230
212<chapter> 231<chapter>
213<title>Cross-Compiling</title> 232<title>Cross-Compiling</title>
214<section> 233<section>
215<title>A Note on Cross-Compiling</title>
216<body> 234<body>
217 235
218<p> 236<p>
219Cross-compiling is using one architecture to build programs for another 237Cross-compiling is using one architecture to build programs for another
220architecture. This can be as simple as using an Athlon (i686) to build a 238architecture. This can be as simple as using an Athlon (i686) to build a
221program for a K6-2 (i586), or using a Sparc to build a program for a ppc. 239program for a K6-2 (i586), or using a Sparc to build a program for a ppc. This
222</p> 240is documented in our <uri link="/doc/en/cross-compiling-distcc.xml">DistCC
223 241Cross-compiling Guide</uri>.
224</body>
225</section>
226<section>
227<title>An Introduction to Cross-compiling</title>
228<body>
229
230<p>
231If you want to give Cross-compiling a try you can emerge the crossdev package.
232I can't support it since I didn't write it, but that's a good way to start
233cross-compiling.
234</p> 242</p>
235 243
236</body> 244</body>
237</section> 245</section>
238</chapter> 246</chapter>
239 247
240<chapter id="bootstrapping"> 248<chapter id="bootstrapping">
241<title>Using Distcc to Bootstrap</title> 249<title>Using Distcc to Bootstrap</title>
242<section> 250<section>
243<title>Step 1: Configure Portage </title> 251<title>Step 1: Configure Portage</title>
244<body> 252<body>
245 253<!--
254Note that this will need to become a link to the old 2005.1 networked handbooks
255once the 2006.0 handbooks are released. Until then, the link can stay.
256-->
246<p> 257<p>
247Boot your new box with a Gentoo Linux LiveCD and follow the <uri 258Boot your new box with a Gentoo Linux LiveCD and follow the <uri
248link="/doc/en/handbook/handbook-x86.xml?part=1">installation instructions</uri> 259link="/doc/en/handbook/handbook-x86.xml?part=1">installation instructions</uri>
260up until the bootstrapping part. (See the <uri
261link="/doc/en/faq.xml#stage12">Gentoo FAQ</uri> for more information about
249up until the bootstrapping part. Then configure Portage to use distcc: 262bootstrapping.) Then configure Portage to use distcc:
250</p> 263</p>
251 264
252<pre caption="Preliminary Setup"> 265<pre caption="Preliminary Setup">
253# <i>nano -w /etc/make.conf</i> 266# <i>nano -w /etc/make.conf</i>
254<comment>(Add distcc to the FEATURES variable)</comment> 267<comment>(Add distcc to the FEATURES</comment>
255FEATURES="distcc" 268FEATURES="distcc"
256<comment>(Modify MAKEOPTS to include -jN with N an appropriate integer)</comment> 269<comment>(Modify MAKEOPTS to include -jN, where N is twice the number of CPUs
270+1 available)</comment>
257MAKEOPTS="-jN" 271MAKEOPTS="-jN"
258</pre> 272</pre>
259 273
260<pre caption="Setting your path"> 274<pre caption="Setting your path">
261# <i>export PATH="/usr/lib/ccache/bin:/usr/lib/distcc/bin:${PATH}"</i> 275# <i>export PATH="/usr/lib/ccache/bin:/usr/lib/distcc/bin:${PATH}"</i>
266<section> 280<section>
267<title>Step 2: Getting Distcc</title> 281<title>Step 2: Getting Distcc</title>
268<body> 282<body>
269 283
270<p> 284<p>
271Before the installation of distcc, a user called distcc must be added to the
272<path>/etc/passwd</path>:
273</p>
274
275<pre caption="Create user distcc">
276# <i>echo "distcc:x:240:2:distccd:/dev/null:/bin/false" &gt;&gt; /etc/passwd</i>
277</pre>
278
279<p>
280Install distcc: 285Install distcc:
281</p> 286</p>
282 287
283<pre caption="Getting Distcc on the new box"> 288<pre caption="Getting Distcc on the new box">
284# <i>USE='-*' emerge --nodeps distcc</i> 289# <i>USE='-*' emerge --nodeps sys-devel/distcc sys-devel/distcc-config</i>
285</pre> 290</pre>
286 291
287</body> 292</body>
288</section> 293</section>
289<section> 294<section>
290<title>Step 3: Setting Up Distcc</title> 295<title>Step 3: Setting Up Distcc</title>
291<body> 296<body>
292 297
293<p> 298<p>
294Run <c>distcc-config</c> to setup distcc: 299Run <c>distcc-config --install</c> to setup distcc:
295</p> 300</p>
296 301
297<pre caption="Final distcc setup"> 302<pre caption="Final distcc setup">
298<comment>(Substitute host1, host2, ... with the IP number(s) of the participating hosts)</comment> 303<comment>(Substitute host1, host2, ... with the IP number(s) of the
304participating hosts)</comment>
299# <i>/usr/bin/distcc-config --set-hosts "localhost host1 host2 host3 ..."</i> 305# <i>/usr/bin/distcc-config --set-hosts "localhost host1 host2 host3 ..."</i>
300<comment>An example: <i>/usr/bin/distcc-config --set-hosts "localhost 192.168.0.4 192.168.0.6"</i></comment> 306<comment>An example: <i>/usr/bin/distcc-config --set-hosts "localhost
307192.168.0.4 192.168.0.6"</i></comment>
301</pre> 308</pre>
302 309
303<p> 310<p>
304distcc is now set up to bootstrap! Continue the official installation 311Distcc is now set up to bootstrap! Continue with the official installation
305instructions and <e>don't forget</e> to re-emerge distcc after <c>emerge 312instructions and <e>do not forget</e> to re-emerge distcc after <c>emerge
306system</c>. This is to make sure that all of the dependencies you want are 313system</c>. This is to make sure that all of the dependencies you want are
307installed as well. 314installed as well.
308</p> 315</p>
309 316
310<note> 317<note>
311During bootstrap and <c>emerge system</c> Distcc may not appear to be used. 318During bootstrap and <c>emerge system</c> distcc may not appear to be used.
312This is expected as some ebuilds do not work well with distcc, so they 319This is expected as some ebuilds do not work well with distcc, so they
313intentionally disable it. 320intentionally disable it.
314</note> 321</note>
315 322
316</body> 323</body>
318</chapter> 325</chapter>
319 326
320<chapter> 327<chapter>
321<title>Troubleshooting</title> 328<title>Troubleshooting</title>
322<section> 329<section>
323<title>Mozilla and Xfree</title> 330<title>Some Packages Don't Use Distcc</title>
324<body> 331<body>
325 332
326<p> 333<p>
327As you emerge various packages, you'll notice that some of them aren't being 334As you emerge various packages, you'll notice that some of them aren't being
328distributed (and aren't being built in parallel). This is because the 335distributed (and aren't being built in parallel). This may happen because the
329developers of the Mozilla and Xfree ebuilds intentionally disable parallel 336package's Makefile doesn't support parallel operations or the maintainer of the
330building because it is known to cause problems. 337ebuild has explicitly disabled parallel operations due to a known problem.
331</p> 338</p>
332 339
333<p> 340<p>
334Sometimes distcc might cause a package to fail to compile. If this happens 341Sometimes distcc might cause a package to fail to compile. If this happens
335for you, please <uri link="http://bugs.gentoo.org">report</uri> it to us. 342for you, please <uri link="http://bugs.gentoo.org">report</uri> it to us.
336</p>
337
338</body>
339</section>
340<section>
341<title>A Mixture of hardened-gcc and non-hardened-gcc Hosts Will Be Faulty</title>
342<body>
343
344<p>
345With such a long title any explanation here is almost irrelevent. However, if
346you plan to use distcc across hosts that have the <uri
347link="/proj/en/hardened/etdyn-ssp.xml">PaX/hardened-gcc</uri> and some that do
348not, you will run into problems.
349</p>
350
351<p>
352The solution requires a little foresight on your part; you have to run
353<c>hardened-gcc -R</c> on the host that has PaX/hardened-gcc, or you have to
354enable PaX protections in your kernel and <c>emerge hardened-gcc</c>. Both of
355which are a good thing to do since for the most part the protections offered
356by both packages is a good thing and is transparent to the user.
357</p> 343</p>
358 344
359</body> 345</body>
360</section> 346</section>
361<section> 347<section>
365<p> 351<p>
366If you have different GCC versions on your hosts, there will likely be very 352If you have different GCC versions on your hosts, there will likely be very
367weird problems. The solution is to make certain all hosts have the same GCC 353weird problems. The solution is to make certain all hosts have the same GCC
368version. 354version.
369</p> 355</p>
356
357<p>
358Recent Portage updates have made Portage use <c>${CHOST}-gcc</c> instead of
359<c>gcc</c>. This means that if you're mixing i686 machines with other types
360(i386, i586) you will run into problems. A workaround for this may be to
361<c>export CC='gcc' CXX='c++'</c> or to put it in <path>/etc/make.conf</path>.
362</p>
363
364<impo>
365Doing this explicitly redefines some behaviour of Portage and may have some
366weird results in the future. Only do this if you're mixing CHOSTs.
367</impo>
368
370 369
371</body> 370</body>
372</section> 371</section>
373</chapter> 372</chapter>
374 373
385parameter it will run once. However, if you pass it a number it will update 384parameter it will run once. However, if you pass it a number it will update
386every N seconds, where N is the argument you passed. 385every N seconds, where N is the argument you passed.
387</p> 386</p>
388 387
389<p> 388<p>
390The other monitor is only turned on if you enabled <c>gtk</c> or <c>gnome</c> 389The other monitor is only turned on if you enabled <c>gtk</c> or <c>gnome</c>
391in your <c>USE</c> flags. This one is GTK+ based, runs in an X environment 390in your <c>USE</c> flags. This one is GTK+ based, runs in an X environment
392and it is quite lovely. 391and it is quite lovely. For Gentoo the GUI monitor has been called
392<c>distccmon-gui</c> for less confusion. Elsewhere it may be referred to as
393<c>distccmon-gnome</c>.
393</p> 394</p>
394 395
395<pre caption="Starting the monitors"> 396<pre caption="Starting the monitors">
396# <i>distccmon-text N</i> 397# <i>distccmon-text N</i>
397<comment>(Or)</comment> 398<comment>(Or)</comment>
398# <i>distccmon-gnome</i> 399# <i>distccmon-gui</i>
399<comment>To monitor Portage's distcc usage you can use:</comment> 400<comment>To monitor Portage's distcc usage you can use:</comment>
400# <i>DISTCC_DIR=`portageq envvar DISTCC_DIR` distccmon-text N</i> 401# <i>DISTCC_DIR="/var/tmp/portage/.distcc/" distccmon-text N</i>
401<comment>(Or)</comment> 402<comment>(Or)</comment>
402# <i>DISTCC_DIR=`portageq envvar DISTCC_DIR` distccmon-gnome</i> 403# <i>DISTCC_DIR="/var/tmp/portage/.distcc/" distccmon-gui</i>
403</pre> 404</pre>
404 405
405<impo> 406<impo>
406Notice the backticks above. <c>portageq</c> is a part of Portage that will 407If your distcc directory is elsewhere, change the DISTCC_DIR variable
407return a piece of information (in this case what DISTCC_DIR is set to). For 408accordingly.
408simplicity, most users can use <c>DISTCC_DIR=/var/tmp/portage/.distcc
409distccmon-text N</c>
410</impo> 409</impo>
411 410
412</body> 411</body>
413</section> 412</section>
414</chapter> 413</chapter>

Legend:
Removed from v.1.22  
changed lines
  Added in v.1.40

  ViewVC Help
Powered by ViewVC 1.1.20