/[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.1 Revision 1.39
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.39 2006/12/24 17:54:01 nightmorph Exp $ -->
4
3<guide link="/doc/en/distcc.xml"> 5<guide link="/doc/en/distcc.xml">
4 6
5<title>Gentoo Distcc Documentation</title> 7<title>Gentoo Distcc Documentation</title>
6 8
7<author title="Author"> 9<author title="Author">
8 <mail link="lisa@gentoo.org">Lisa M. Seelye</mail> 10 <mail link="lisa@gentoo.org">Lisa Seelye</mail>
11</author>
12<author title="Editor">
13 <mail link="vapier@gentoo.org">Mike Frysinger</mail>
14</author>
15<author title="Editor">
16 <mail link="erwin@gentoo.org">Erwin</mail>
17</author>
18<author title="Editor">
19 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
20</author>
21<author title="Editor">
22 <mail link="pylon@gentoo.org">Lars Weiler</mail>
9</author> 23</author>
10<author title="Reviewer"> 24<author title="Reviewer">
11 <mail link="swift@gentoo.org">Sven Vermeulen</mail> 25 <mail link="blubber@gentoo.org">Tiemo Kieft</mail>
12</author> 26</author>
13<version>1.0</version>
14<date>5th of August 2003</date>
15 27
28<abstract>
29This document serves as a HOWTO for using distcc with Gentoo.
30</abstract>
31
32<!-- The content of this document is licensed under the CC-BY-SA license -->
33<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
16<license/> 34<license/>
17 35
18<abstract> 36<version>1.18</version>
19This document serves as a HOWTO for using distcc with gentoo. 37<date>2006-12-24</date>
20</abstract>
21 38
22<chapter> 39<chapter>
23<title>Introduction</title> 40<title>Introduction</title>
24<section> 41<section>
25<title>What is distcc?</title> 42<title>What is distcc?</title>
26<body> 43<body>
44
27<p> 45<p>
28Distcc is a program designed to distribute compiling tasks across a 46Distcc is a program designed to distribute compiling tasks across a network to
29network to participating hosts. It is comprised of a server, <c>distccd</c> 47participating hosts. It is comprised of a server, <c>distccd</c>, and a client
30and a client program, <c>distcc</c>. Distcc can work transparently with 48program, <c>distcc</c>. Distcc can work transparently with <uri
31<uri link="http://ccache.samba.org">ccache</uri> and Portage with a little 49link="http://ccache.samba.org">ccache</uri>, Portage, and Automake with a
32set up. 50little setup.
33</p> 51</p>
34 52
35</body> 53</body>
36</section>
37
38<section> 54</section>
39<title>Dependancies</title> 55<section>
56<title>Using distcc to bootstrap</title>
40<body> 57<body>
41<pre caption="Distcc Dependancies"> 58
42&gt;=sys-apps/portage-2.0.46-r11 59<p>
43&gt;=sys-devel/gcc-config-1.3.1 60If you are planning on using distcc to help you bootstrap a Gentoo
44&gt;sys-apps/shadow 61installation, make sure you read the section <uri link="#bootstrapping">Using
45<codenote>(As of version 2.8) And the following optional dependancies when you have <c>gtk</c> in your <c>USE</c> flags</codenote> 62distcc to Bootstrap</uri>, which is situated further down in this document.
46&gt;=x11-libs/gtk+-2.2.1
47</pre> 63</p>
48 64
49</body> 65</body>
50</section> 66</section>
51</chapter> 67</chapter>
52 68
53<chapter> 69<chapter>
54<title>Setup</title> 70<title>Setup</title>
55<section> 71<section>
72<title>Dependencies</title>
73<body>
74
75<p>
76In order to use Distcc, all of the computers on your network need to have the
77same GCC versions. For example, mixing 3.3.x (where the x varies) is okay, but
78mixing 3.3.x with 3.2.x <b>may</b> result in compilation errors or runtime
79errors.
80</p>
81
82</body>
83</section>
84<section>
85<title>Installing Distcc</title>
86<body>
87
88<p>
89There are a couple of options you should be aware of before you start
90installing distcc.
91</p>
92
93<p>
94Distcc ships with a graphical monitor to monitor tasks that your computer is
95sending away for compilation. If you use Gnome then put 'gnome' in your USE
96flags. However, if you don't use Gnome and would still like to have the
97monitor then you should put 'gtk' in your USE flags.
98</p>
99
100<pre caption="Installing distcc">
101# <i>emerge distcc</i>
102</pre>
103
104<impo>
105Remember, you must be sure to install distcc on all of your participating
106machines.
107</impo>
108
109</body>
110</section>
111<section>
56<title>Setting up Portage to use Distcc</title> 112<title>Setting up Portage to use Distcc</title>
57<body> 113<body>
58 114
59<p> 115<p>
60Setting up distcc is very easy to do with Portage. Follow these simple 116Setting up Portage to use distcc is easy. Execute the following steps on
61steps on each computer you want to use distcc on: 117each system that should participate in the distributed compiling:
62</p> 118</p>
63 119
64<pre caption="Integrating Distcc and Portage"> 120<pre caption="Integrating Distcc and Portage">
65# <i>emerge distcc</i> 121# <i>emerge distcc</i>
66# <i>nano -w /etc/make.conf</i> 122# <i>nano -w /etc/make.conf</i>
67<codenote>Edit your FEATURES flags to include &quot;distcc&quot;</codenote> 123<comment>(Set N to a suitable number for your particular setup)</comment>
124<comment>(A common strategy is setting N as twice the number of total CPUs + 1
125available)</comment>
126MAKEOPTS="-jN"
127<comment>(Add distcc to your FEATURES)</comment>
128FEATURES="distcc"
68</pre> 129</pre>
69 130
131</body>
132</section>
133<section>
134<title>Specifying Participating Hosts</title>
135<body>
136
70<p> 137<p>
71Next you have to specify what hosts you want to use. To do this you can
72use the <i>distcc-config</i> command to set that list of hosts. Here is an 138Use the <c>distcc-config</c> command to set the list of hosts. Here is an
73example of some hosts that might be in your list: 139example of some hosts that might be in your list:
74</p> 140</p>
75 141
76<pre caption="Examples of host definitions"> 142<pre caption="Examples of host definitions">
77192.168.0.1 192.168.0.2 192.168.0.3 143192.168.0.1 192.168.0.2 192.168.0.3
78192.168.0.1/2 192.168.0.2 192.168.0.3/10 144192.168.0.1/2 192.168.0.2 192.168.0.3/10
79192.168.0.1:4000/2 192.168.0.2/1 192.168.0.3:3632/4 145192.168.0.1:4000/2 192.168.0.2/1 192.168.0.3:3632/4
80@192.168.0.1 @192.168.0.2:/usr/bin/distccd 192.168.0.3 146@192.168.0.1 @192.168.0.2:/usr/bin/distccd 192.168.0.3
147<comment>(There are also several other methods of setting up hosts. See the
148distcc manpage for more details.)</comment>
149<comment>If you wish to compile on the local machine you should put 'localhost'
150in the hosts list. Conversely if you do not wish to use the local machine to
151compile (which is often the case) omit it from the hosts list. On a slow
152machine using localhost may actually slow things down. Make sure to test your
153settings for performance.</comment>
81</pre> 154</pre>
82 155
83<p> 156<p>
84It may all look complicated, but in most cases a variant of line 1 157It may all look complicated, but in most cases a variant of line 1 or 2 will
85or 2 will work. An explanation of each line is: Line 1 is just a 158work.
86space-delimited list of hosts that will use default everything.
87Line 2 is a list of hosts that specifies the maximum number of jobs (by
88use of the /N) to send that host at any given time. Since most people
89won't be using lines 3 or 4, I'll point you to the <uri
90link="http://distcc.samba.org/man/distcc_1.html">distcc docs</uri> for
91more information.
92</p>
93
94<p> 159</p>
95The final step to integrating distcc into Portage is to re-open your 160
96<path>/etc/make.conf</path> and edit <c>MAKE_OPTS</c> to include <c>-jN</c>
97(where N is an integer). Typically you will want to set this to the total
98number of processors in your network plus one.
99</p> 161<p>
100 162Since most people won't be using lines 3 or 4, I'll <uri
101<pre caption="Final steps in make.conf"> 163link="http://distcc.samba.org/man/distcc_1.html">refer to</uri> the distcc
102# <i>nano -w /etc/make.conf</i> 164docs (man distcc) for more information.
103MAKE_OPTS=-jN
104</pre> 165</p>
105 166
106</body> 167<p>
107</section> 168For instance, to set the first line in the previous example:
169</p>
108 170
171<pre caption="Sample command to set the hosts">
172# <i>/usr/bin/distcc-config --set-hosts "192.168.0.1 192.168.0.2 192.168.0.3"</i>
173</pre>
174
175<p>
176Edit <path>/etc/conf.d/distccd</path> to your needs and be sure to set the
177<c>--allow</c> directive to allow only hosts you trust. For added security,
178you should also use the <c>--listen</c> directive to tell the distcc daemon
179what IP to listen on (for multi-homed systems). More information on distcc
180security can be found at <uri
181link="http://distcc.samba.org/security.html">Distcc Security Design</uri>.
182</p>
183
184<impo>
185It is important to use --allow and --listen. Please read the distccd manpage
186or the above security document for more information.
187</impo>
188
189
190<p>
191Now start the distcc daemon on all the participating computers:
192</p>
193
194<pre caption="Starting the distcc daemon">
195<comment>(Add distccd to the default runlevel)</comment>
196# <i>rc-update add distccd default</i>
197<comment>(Start the distcc daemon)</comment>
198# <i>/etc/init.d/distccd start</i>
199</pre>
200
201</body>
202</section>
109<section> 203<section>
110<title>Setting up Distcc to Work With Automake</title> 204<title>Setting up Distcc to Work With Automake</title>
111<body> 205<body>
112 206
113<p> 207<p>
114This is in some cases easier than the Portage setup. What you have to do 208This is, in some cases, easier than the Portage setup. What you have to do is
115is update your <c>PATH</c> environment variable to include 209update your <c>PATH</c> variable to include <path>/usr/lib/distcc/bin</path>
116<path>/usr/lib/distcc/bin</path> before the directory where gcc is 210in front of the directory that contains <c>gcc</c> (<path>/usr/bin</path>).
117situated (<path>/usr/bin</path>). However, there is a caveat. If you use 211However, there is a caveat. If you use ccache you have to put distcc after
118ccache you have to put distcc after the ccache part. Like so: 212the ccache part:
119</p> 213</p>
120 214
121<pre caption="Setting your path"> 215<pre caption="Setting your path">
122# <i>export PATH="/usr/lib/ccache/bin:/usr/lib/distcc/bin:${PATH}"</i> 216# <i>export PATH="/usr/lib/ccache/bin:/usr/lib/distcc/bin:${PATH}"</i>
217<comment>(You can put this in your ~/.bashrc or equivalent file to have the PATH
218set every time you log in)</comment>
123</pre> 219</pre>
124 220
125<p> 221<p>
126Then, as you would normally type <c>make</c>, you would type <c>make -jN</c> 222Then, as you would normally type <c>make</c>, you would type <c>make -jN</c>
127(where N is an integer). A safe number to use for N varies on your network 223(where N is an integer). The value of N depends on your network and the types
128and the types of computers you are using to compile. For me, I have a dual 224of computers you are using to compile. Test your own settings to find the
129processor P3 and a K6-2/400 that compile everything for my desktop (a 1200MHz 225number that yields the best performance.
130Athlon Thunderbird) and I use -j5. Test your own settings to find the right
131number.
132</p> 226</p>
133 227
134</body> 228</body>
135</section> 229</section>
136</chapter> 230</chapter>
137 231
138<chapter> 232<chapter>
139<title>Cross-Compiling</title> 233<title>Cross-Compiling</title>
140<section> 234<section>
141<title>A Note on Cross-Compiling</title>
142<body> 235<body>
143 236
144<p> 237<p>
145Cross-compiling is using one architecture to build programs for another 238Cross-compiling is using one architecture to build programs for another
146architecture. This can be as simple as using an Athlon (i686) to build a 239architecture. This can be as simple as using an Athlon (i686) to build a
147program for a K6-2 (i586), or using a Sparc to build a program for a ppc. 240program for a K6-2 (i586), or using a Sparc to build a program for a ppc. This
241is documented in our <uri link="/doc/en/cross-compiling-distcc.xml">DistCC
242Cross-compiling Guide</uri>.
148</p> 243</p>
149 244
150</body> 245</body>
151</section>
152
153<section> 246</section>
154<title>A Personal Note on Cross-compiling</title> 247</chapter>
248
249<chapter id="bootstrapping">
250<title>Using Distcc to Bootstrap</title>
251<section>
252<title>Step 1: Configure Portage</title>
253<body>
254<!--
255Note that this will need to become a link to the old 2005.1 networked handbooks
256once the 2006.0 handbooks are released. Until then, the link can stay.
257-->
258<p>
259Boot your new box with a Gentoo Linux LiveCD and follow the <uri
260link="/doc/en/handbook/handbook-x86.xml?part=1">installation instructions</uri>
261up until the bootstrapping part. (See the <uri
262link="/doc/en/faq.xml#stage12">Gentoo FAQ</uri> for more information about
263bootstrapping.) Then configure Portage to use distcc:
264</p>
265
266<pre caption="Preliminary Setup">
267# <i>nano -w /etc/make.conf</i>
268<comment>(Add distcc to the FEATURES</comment>
269FEATURES="distcc"
270<comment>(Modify MAKEOPTS to include -jN, where N is twice the number of CPUs
271+1 available)</comment>
272MAKEOPTS="-jN"
273</pre>
274
275<pre caption="Setting your path">
276# <i>export PATH="/usr/lib/ccache/bin:/usr/lib/distcc/bin:${PATH}"</i>
277</pre>
278
155<body> 279</body>
280</section>
281<section>
282<title>Step 2: Getting Distcc</title>
283<body>
156 284
157<p>
158I'd love to be able to help out on the Gentoo Cross-compiling effort, but
159I don't have any non-x86 machines. I can create things that work
160<e>in theory</e>, but I have to rely on other people to test what I write.
161That works to an extent, but it's tough. ;-)
162</p> 285<p>
163 286Before the installation of distcc, a user called distcc must be added to the
287<path>/etc/passwd</path>:
164<p> 288</p>
165In the near future I hope to acquire a Sparc of some type to put Gentoo 289
166on so I can play around in-house. 290<pre caption="Create user distcc">
291# <i>echo "distcc:x:240:2:distccd:/dev/null:/bin/false" &gt;&gt;/etc/passwd</i>
292</pre>
293
294<impo>
295It is important to note that adding users like this is very bad. We only do
296it here because there is no <c>useradd</c> utility (which you normally use for
297adding users) yet at this stage of installation.
298</impo>
299
167</p> 300<p>
301Install distcc:
302</p>
303
304<pre caption="Getting Distcc on the new box">
305# <i>USE='-*' emerge --nodeps sys-devel/distcc</i>
306</pre>
307
308</body>
309</section>
310<section>
311<title>Step 3: Setting Up Distcc</title>
312<body>
313
314<p>
315Run <c>distcc-config --install</c> to setup distcc:
316</p>
317
318<pre caption="Final distcc setup">
319<comment>(Substitute host1, host2, ... with the IP number(s) of the
320participating hosts)</comment>
321# <i>/usr/bin/distcc-config --set-hosts "localhost host1 host2 host3 ..."</i>
322<comment>An example: <i>/usr/bin/distcc-config --set-hosts "localhost
323192.168.0.4 192.168.0.6"</i></comment>
324</pre>
325
326<p>
327Distcc is now set up to bootstrap! Continue with the official installation
328instructions and <e>do not forget</e> to re-emerge distcc after <c>emerge
329system</c>. This is to make sure that all of the dependencies you want are
330installed as well.
331</p>
332
333<note>
334During bootstrap and <c>emerge system</c> distcc may not appear to be used.
335This is expected as some ebuilds do not work well with distcc, so they
336intentionally disable it.
337</note>
168 338
169</body> 339</body>
170</section> 340</section>
171</chapter> 341</chapter>
172 342
173<chapter> 343<chapter>
174<title>Known Problems With Distcc</title> 344<title>Troubleshooting</title>
175
176<section>
177<title>Portage Doesn't Work With Distcc</title>
178<body>
179
180<p>
181This heading is a misnomer, really. The only thing that doens't work is
182the monitoring programs (<c>distccmon-text</c> and <c>distccmon-gnome</c>)
183with the standard distcc source. The reason for this is that distcc relies
184on the <c>TMPDIR</c> environment variable, but Portage reassigns that.
185</p>
186
187<p>
188The solution to this is a patch that changes the dependancy to
189<c>DISTCC_TMPDIR</c>. The patch is automatically applied to distcc.
190If you don't want to use <path>/tmp</path> (the default) you can reassign
191<c>DISTCC_TMPDIR</c>.
192</p>
193
194<p>
195You may also notice that distcc does not work with some packages.
196This can be a result of several things, such as an error in the .ebuild
197(Using <c>make</c> instead of <c>emake</c>) or an error in the program's
198Makefile, which the next section addresses.
199</p>
200
201</body>
202</section> 345<section>
346<title>Some Packages Don't Use Distcc</title>
347<body>
348
349<p>
350As you emerge various packages, you'll notice that some of them aren't being
351distributed (and aren't being built in parallel). This may happen because the
352package's Makefile doesn't support parallel operations or the maintainer of the
353ebuild has explicitly disabled parallel operations due to a known problem.
354</p>
355
356<p>
357Sometimes distcc might cause a package to fail to compile. If this happens
358for you, please <uri link="http://bugs.gentoo.org">report</uri> it to us.
359</p>
360
361</body>
203<section> 362</section>
204<title>Mozilla and XFree</title> 363<section>
364<title>Mixed GCC Versions</title>
205<body> 365<body>
206 366
207<p>
208As you emerge various packages, you'll notice that they aren't being
209distributed (and indeed aren't being built in parallel). This is because
210the developers of Mozilla and XFree .ebuilds disabled parallel building
211because it is known to cause problems. This isn't necessarily a distcc
212problem.
213</p> 367<p>
214 368If you have different GCC versions on your hosts, there will likely be very
369weird problems. The solution is to make certain all hosts have the same GCC
370version.
215<p> 371</p>
216That isn't to say that sometimes distcc will cause a package to fail 372
217to compile.
218</p> 373<p>
374Recent Portage updates have made Portage use <c>${CHOST}-gcc</c> instead of
375<c>gcc</c>. This means that if you're mixing i686 machines with other types
376(i386, i586) you will run into problems. A workaround for this may be to
377<c>export CC='gcc' CXX='c++'</c> or to put it in <path>/etc/make.conf</path>.
378</p>
379
380<impo>
381Doing this explicitly redefines some behaviour of Portage and may have some
382weird results in the future. Only do this if you're mixing CHOSTs.
383</impo>
384
219 385
220</body> 386</body>
221</section> 387</section>
222</chapter> 388</chapter>
223 389
226<section> 392<section>
227<title>Distcc Monitors</title> 393<title>Distcc Monitors</title>
228<body> 394<body>
229 395
230<p> 396<p>
231Distcc ships with two monitors. The text-based one is always built and 397Distcc ships with two monitors. The text-based one is always built and is
232is called <c>distccmon-text</c>. Running it for the first time can be a 398called <c>distccmon-text</c>. Running it for the first time can be a bit
233bit confusing, but it is really quite easy to use. If you run the program 399confusing, but it is really quite easy to use. If you run the program with no
234with no parameter it will run once. However, if you pass it a number it 400parameter it will run once. However, if you pass it a number it will update
235will update every N seconds, where N is the argument you passed. 401every N seconds, where N is the argument you passed.
236</p>
237
238<p> 402</p>
403
404<p>
239The other monitor is only turned on if you enabled <c>gtk</c> in your 405The other monitor is only turned on if you enabled <c>gtk</c> or <c>gnome</c>
240<c>USE</c> flags. This one is GTK+ based and runs in an X environment, and 406in your <c>USE</c> flags. This one is GTK+ based, runs in an X environment
241it is quite lovely. 407and it is quite lovely. For Gentoo the GUI monitor has been called
242</p> 408<c>distccmon-gui</c> for less confusion. Elsewhere it may be referred to as
243 409<c>distccmon-gnome</c>.
244<p>
245There is a caveat to using these programs. If you want to monitor any
246emerge, you have to start the monitor like so:
247</p> 410</p>
248 411
249<pre caption="Starting the monitors"> 412<pre caption="Starting the monitors">
250# <i>sudo -u portage distccmon-text N</i> 413# <i>distccmon-text N</i>
251<codenote>Or you can start the graphical monitor...</codenote> 414<comment>(Or)</comment>
252# <i>sudo -u portage distccmon-gnome</i> 415# <i>distccmon-gui</i>
416<comment>To monitor Portage's distcc usage you can use:</comment>
417# <i>DISTCC_DIR="/var/tmp/portage/.distcc/" distccmon-text N</i>
418<comment>(Or)</comment>
419# <i>DISTCC_DIR="/var/tmp/portage/.distcc/" distccmon-gui</i>
253</pre> 420</pre>
254 421
255</body> 422<impo>
256</section> 423If your distcc directory is elsewhere, change the DISTCC_DIR variable
257</chapter> 424accordingly.
425</impo>
258 426
259<chapter> 427</body>
260<title>Future Plans for Distcc and Gentoo</title>
261<section> 428</section>
262<title>distcc-subnetscan</title>
263<body>
264
265<p>
266<c>distcc-subnetscan</c> is a perl program in development that will scan a
267subnet for hosts that have a participating distcc daemon. Even this will
268be enhanced to test if the daemon on a remote host will conform to a
269specific <c>CHOST</c> setting to make cross-compiling easier.
270</p>
271
272<p>
273The perl script is being kept at <uri link="http://dev.gentoo.org/~lisa/distcc/distcc-subnetscan/distcc-subnetscan.pl">right here</uri>
274until a more formal home can be found.
275</p>
276
277</body>
278</section>
279
280<section>
281<title>distcc-config</title>
282<body>
283
284<p>
285<c>distcc-config</c>, the userland configuration tool for distcc is out of
286date. Soon it will be rewritten to be brought up with the current version
287of distcc.
288</p>
289
290</body>
291</section>
292</chapter> 429</chapter>
293
294</guide> 430</guide>

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.39

  ViewVC Help
Powered by ViewVC 1.1.20