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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (show annotations) (download) (as text)
Wed Aug 6 08:23:17 2003 UTC (11 years, 4 months ago) by swift
Branch: MAIN
File MIME type: application/xml
New Application Guide: DistCC

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 <guide link="/doc/en/distcc.xml">
4
5 <title>Gentoo Distcc Documentation</title>
6
7 <author title="Author">
8 <mail link="lisa@gentoo.org">Lisa M. Seelye</mail>
9 </author>
10 <author title="Reviewer">
11 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
12 </author>
13 <version>1.0</version>
14 <date>5th of August 2003</date>
15
16 <license/>
17
18 <abstract>
19 This document serves as a HOWTO for using distcc with gentoo.
20 </abstract>
21
22 <chapter>
23 <title>Introduction</title>
24 <section>
25 <title>What is distcc?</title>
26 <body>
27 <p>
28 Distcc is a program designed to distribute compiling tasks across a
29 network to participating hosts. It is comprised of a server, <c>distccd</c>
30 and a client program, <c>distcc</c>. Distcc can work transparently with
31 <uri link="http://ccache.samba.org">ccache</uri> and Portage with a little
32 set up.
33 </p>
34
35 </body>
36 </section>
37
38 <section>
39 <title>Dependancies</title>
40 <body>
41 <pre caption="Distcc Dependancies">
42 &gt;=sys-apps/portage-2.0.46-r11
43 &gt;=sys-devel/gcc-config-1.3.1
44 &gt;sys-apps/shadow
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>
46 &gt;=x11-libs/gtk+-2.2.1
47 </pre>
48
49 </body>
50 </section>
51 </chapter>
52
53 <chapter>
54 <title>Setup</title>
55 <section>
56 <title>Setting up Portage to use Distcc</title>
57 <body>
58
59 <p>
60 Setting up distcc is very easy to do with Portage. Follow these simple
61 steps on each computer you want to use distcc on:
62 </p>
63
64 <pre caption="Integrating Distcc and Portage">
65 # <i>emerge distcc</i>
66 # <i>nano -w /etc/make.conf</i>
67 <codenote>Edit your FEATURES flags to include &quot;distcc&quot;</codenote>
68 </pre>
69
70 <p>
71 Next you have to specify what hosts you want to use. To do this you can
72 use the <i>distcc-config</i> command to set that list of hosts. Here is an
73 example of some hosts that might be in your list:
74 </p>
75
76 <pre caption="Examples of host definitions">
77 192.168.0.1 192.168.0.2 192.168.0.3
78 192.168.0.1/2 192.168.0.2 192.168.0.3/10
79 192.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
81 </pre>
82
83 <p>
84 It may all look complicated, but in most cases a variant of line 1
85 or 2 will work. An explanation of each line is: Line 1 is just a
86 space-delimited list of hosts that will use default everything.
87 Line 2 is a list of hosts that specifies the maximum number of jobs (by
88 use of the /N) to send that host at any given time. Since most people
89 won't be using lines 3 or 4, I'll point you to the <uri
90 link="http://distcc.samba.org/man/distcc_1.html">distcc docs</uri> for
91 more information.
92 </p>
93
94 <p>
95 The final step to integrating distcc into Portage is to re-open your
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
98 number of processors in your network plus one.
99 </p>
100
101 <pre caption="Final steps in make.conf">
102 # <i>nano -w /etc/make.conf</i>
103 MAKE_OPTS=-jN
104 </pre>
105
106 </body>
107 </section>
108
109 <section>
110 <title>Setting up Distcc to Work With Automake</title>
111 <body>
112
113 <p>
114 This is in some cases easier than the Portage setup. What you have to do
115 is update your <c>PATH</c> environment variable to include
116 <path>/usr/lib/distcc/bin</path> before the directory where gcc is
117 situated (<path>/usr/bin</path>). However, there is a caveat. If you use
118 ccache you have to put distcc after the ccache part. Like so:
119 </p>
120
121 <pre caption="Setting your path">
122 # <i>export PATH="/usr/lib/ccache/bin:/usr/lib/distcc/bin:${PATH}"</i>
123 </pre>
124
125 <p>
126 Then, 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
128 and the types of computers you are using to compile. For me, I have a dual
129 processor P3 and a K6-2/400 that compile everything for my desktop (a 1200MHz
130 Athlon Thunderbird) and I use -j5. Test your own settings to find the right
131 number.
132 </p>
133
134 </body>
135 </section>
136 </chapter>
137
138 <chapter>
139 <title>Cross-Compiling</title>
140 <section>
141 <title>A Note on Cross-Compiling</title>
142 <body>
143
144 <p>
145 Cross-compiling is using one architecture to build programs for another
146 architecture. This can be as simple as using an Athlon (i686) to build a
147 program for a K6-2 (i586), or using a Sparc to build a program for a ppc.
148 </p>
149
150 </body>
151 </section>
152
153 <section>
154 <title>A Personal Note on Cross-compiling</title>
155 <body>
156
157 <p>
158 I'd love to be able to help out on the Gentoo Cross-compiling effort, but
159 I 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.
161 That works to an extent, but it's tough. ;-)
162 </p>
163
164 <p>
165 In the near future I hope to acquire a Sparc of some type to put Gentoo
166 on so I can play around in-house.
167 </p>
168
169 </body>
170 </section>
171 </chapter>
172
173 <chapter>
174 <title>Known Problems With Distcc</title>
175
176 <section>
177 <title>Portage Doesn't Work With Distcc</title>
178 <body>
179
180 <p>
181 This heading is a misnomer, really. The only thing that doens't work is
182 the monitoring programs (<c>distccmon-text</c> and <c>distccmon-gnome</c>)
183 with the standard distcc source. The reason for this is that distcc relies
184 on the <c>TMPDIR</c> environment variable, but Portage reassigns that.
185 </p>
186
187 <p>
188 The solution to this is a patch that changes the dependancy to
189 <c>DISTCC_TMPDIR</c>. The patch is automatically applied to distcc.
190 If you don't want to use <path>/tmp</path> (the default) you can reassign
191 <c>DISTCC_TMPDIR</c>.
192 </p>
193
194 <p>
195 You may also notice that distcc does not work with some packages.
196 This 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
198 Makefile, which the next section addresses.
199 </p>
200
201 </body>
202 </section>
203 <section>
204 <title>Mozilla and XFree</title>
205 <body>
206
207 <p>
208 As you emerge various packages, you'll notice that they aren't being
209 distributed (and indeed aren't being built in parallel). This is because
210 the developers of Mozilla and XFree .ebuilds disabled parallel building
211 because it is known to cause problems. This isn't necessarily a distcc
212 problem.
213 </p>
214
215 <p>
216 That isn't to say that sometimes distcc will cause a package to fail
217 to compile.
218 </p>
219
220 </body>
221 </section>
222 </chapter>
223
224 <chapter>
225 <title>Distcc Extras</title>
226 <section>
227 <title>Distcc Monitors</title>
228 <body>
229
230 <p>
231 Distcc ships with two monitors. The text-based one is always built and
232 is called <c>distccmon-text</c>. Running it for the first time can be a
233 bit confusing, but it is really quite easy to use. If you run the program
234 with no parameter it will run once. However, if you pass it a number it
235 will update every N seconds, where N is the argument you passed.
236 </p>
237
238 <p>
239 The other monitor is only turned on if you enabled <c>gtk</c> in your
240 <c>USE</c> flags. This one is GTK+ based and runs in an X environment, and
241 it is quite lovely.
242 </p>
243
244 <p>
245 There is a caveat to using these programs. If you want to monitor any
246 emerge, you have to start the monitor like so:
247 </p>
248
249 <pre caption="Starting the monitors">
250 # <i>sudo -u portage distccmon-text N</i>
251 <codenote>Or you can start the graphical monitor...</codenote>
252 # <i>sudo -u portage distccmon-gnome</i>
253 </pre>
254
255 </body>
256 </section>
257 </chapter>
258
259 <chapter>
260 <title>Future Plans for Distcc and Gentoo</title>
261 <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
267 subnet for hosts that have a participating distcc daemon. Even this will
268 be enhanced to test if the daemon on a remote host will conform to a
269 specific <c>CHOST</c> setting to make cross-compiling easier.
270 </p>
271
272 <p>
273 The perl script is being kept at <uri link="http://dev.gentoo.org/~lisa/distcc/distcc-subnetscan/distcc-subnetscan.pl">right here</uri>
274 until 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
286 date. Soon it will be rewritten to be brought up with the current version
287 of distcc.
288 </p>
289
290 </body>
291 </section>
292 </chapter>
293
294 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20