/[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 - (hide 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 swift 1.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