/[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.4 Revision 1.5
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.4 2003/09/13 07:47:57 erwin Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/distcc.xml,v 1.5 2003/09/18 09:33:41 swift 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
24 24
25<author title="Reviewer"> 25<author title="Reviewer">
26 <mail link="blubber@gentoo.org">Tiemo Kieft</mail> 26 <mail link="blubber@gentoo.org">Tiemo Kieft</mail>
27</author> 27</author>
28 28
29<version>1.1</version> 29<version>1.2</version>
30<date>September 13, 2003</date> 30<date>September 17, 2003</date>
31 31
32<abstract>This document serves as a HOWTO for using distcc with Gentoo.</abstract> 32<abstract>This document serves as a HOWTO for using distcc with Gentoo.</abstract>
33 33
34<chapter> 34<chapter>
35 <title>Introduction</title> 35 <title>Introduction</title>
45 <body> 45 <body>
46 <pre caption="Distcc dependencies"> 46 <pre caption="Distcc dependencies">
47&gt;=sys-apps/portage-2.0.46-r11 47&gt;=sys-apps/portage-2.0.46-r11
48&gt;=sys-devel/gcc-config-1.3.1 48&gt;=sys-devel/gcc-config-1.3.1
49sys-apps/shadow 49sys-apps/shadow
50<codenote>(As of version 2.8) And the following optional dependencies when you have <i>gtk</i> in your <i>USE</i> flags</codenote> 50<codenote>Distcc has the following optional dependencies when you have gtk in your USE flags (As of version 2.8)</codenote>
51&gt;=x11-libs/gtk+-2.2.1 51&gt;=x11-libs/gtk+-2.2.1
52 </pre> 52 </pre>
53 </body> 53 </body>
54 </section> 54 </section>
55</chapter> 55</chapter>
61 <body> 61 <body>
62 <p>Setting up distcc is very easy to do with Portage. Follow these simple steps on each computer you want to use distcc on:</p> 62 <p>Setting up distcc is very easy to do with Portage. Follow these simple steps on each computer you want to use distcc on:</p>
63 <pre caption="Integrating Distcc and Portage"> 63 <pre caption="Integrating Distcc and Portage">
64# <i>emerge distcc</i> 64# <i>emerge distcc</i>
65# <i>nano -w /etc/make.conf</i> 65# <i>nano -w /etc/make.conf</i>
66</pre>
66<codenote>Edit your FEATURES flags to include &quot;distcc&quot;</codenote> 67 <note>Edit your FEATURES flags to include &quot;distcc&quot;</note>
67 </pre> 68 <note>Set <c>DISTCC_DIR=${PORTAGE_TMPDIR}/portage/.distcc</c></note>
69 <note>You should also uncomment the DISTCC_TMPDIR line.</note>
70
68 71
69 <p>Next you have to specify what hosts you want to use. To do this you can use the <c>distcc-config</c> command to set the list of hosts. Here is an example of some hosts that might be in your list:</p> 72 <p>Next you have to specify what hosts you want to use. To do this you can use the <c>distcc-config</c> command to set the list of hosts. Here is an example of some hosts that might be in your list:</p>
70 <pre caption="Examples of host definitions"> 73 <pre caption="Examples of host definitions">
71192.168.0.1 192.168.0.2 192.168.0.3 74192.168.0.1 192.168.0.2 192.168.0.3
72192.168.0.1/2 192.168.0.2 192.168.0.3/10 75192.168.0.1/2 192.168.0.2 192.168.0.3/10
77 <p>A sample command to set the hosts (for line 1) is:</p> 80 <p>A sample command to set the hosts (for line 1) is:</p>
78 <pre caption="Sample command to set the hosts"> 81 <pre caption="Sample command to set the hosts">
79# <i>/usr/bin/distcc-config --set-hosts "192.168.0.1 192.168.0.2 192.168.0.3"</i> 82# <i>/usr/bin/distcc-config --set-hosts "192.168.0.1 192.168.0.2 192.168.0.3"</i>
80 </pre> 83 </pre>
81 84
82 <p>The final step to integrating distcc into Portage is to re-open your <path>/etc/make.conf</path> and edit <c>MAKE_OPTS</c> to include <c>-jN</c> (where N is an integer). Typically you will want to set this to the total number of processors in your network plus one.</p> 85 <p>The final step to integrating distcc into Portage is to re-open your <path>/etc/make.conf</path> and edit <c>MAKEOPTS</c> to include <c>-jN</c> (where N is an integer). Typically you will want to set this to the total number of processors in your network plus one.</p>
83 <pre caption="Final steps in make.conf"> 86 <pre caption="Final steps in make.conf">
84# <i>nano -w /etc/make.conf</i> 87# <i>nano -w /etc/make.conf</i>
85MAKE_OPTS=-jN 88MAKEOPTS=-jN
86 </pre> 89 </pre>
90 <impo>Don't forget to start the distcc daemon! <c>/etc/init.d/distccd start</c></impo>
87 </body> 91 </body>
88 </section> 92 </section>
89 <section> 93 <section>
90 <title>Setting up Distcc to Work With Automake</title> 94 <title>Setting up Distcc to Work With Automake</title>
91 <body> 95 <body>
92 <p>This is in some cases easier than the Portage setup. What you have to do is update your <c>PATH</c> envvar to include <path>/usr/lib/distcc/bin</path> before where gcc (<path>/usr/bin</path>). However, there is a caveat. If you use ccache you have to put distcc after the ccache part. Like so:</p> 96 <p>This is in some cases easier than the Portage setup. What you have to do is update your <c>PATH</c> environment variable to include <path>/usr/lib/distcc/bin</path> before where gcc (<path>/usr/bin</path>). However, there is a caveat. If you use ccache you have to put distcc after the ccache part. Like so:</p>
93 <pre caption="Setting your path"> 97 <pre caption="Setting your path">
94# <i>export PATH="/usr/lib/ccache/bin:/usr/lib/distcc/bin:${PATH}"</i> 98# <i>export PATH="/usr/lib/ccache/bin:/usr/lib/distcc/bin:${PATH}"</i>
95 </pre> 99 </pre>
96 <p>Then, as you would normally type <c>make</c>, you would type <c>make -jN</c> (where N is an integer). A safe number to use for N varries on your network and the types of computers you are using to compile. For me, I have a dual processor P3 and a K6-2/400 that compile everything for my desktop (a 1200MHz Athlon Thunderbird) and I use -j5. Test your own settings to find the right number.</p> 100 <p>Then, as you would normally type <c>make</c>, you would type <c>make -jN</c> (where N is an integer). A safe number to use for N varries on your network and the types of computers you are using to compile. For me, I have a dual processor P3 and a K6-2/400 that compile everything for my desktop (a 1200MHz Athlon Thunderbird) and I use -j5. Test your own settings to find the right number.</p>
97 </body> 101 </body>
109 <section> 113 <section>
110 <title>A Personal Note on Cross-compiling</title> 114 <title>A Personal Note on Cross-compiling</title>
111 <body> 115 <body>
112 <p>I'd love to be able to help out on the Gentoo Cross-compiling effort, but I don't have any non-x86 machines. I can create things that work <e>in theory</e>, but I have to rely on other people to test what I write. That works to an extent, but it's tough. ;-)</p> 116 <p>I'd love to be able to help out on the Gentoo Cross-compiling effort, but I don't have any non-x86 machines. I can create things that work <e>in theory</e>, but I have to rely on other people to test what I write. That works to an extent, but it's tough. ;-)</p>
113 <p>In the near future I hope to acquire a Sparc of some type to put Gentoo on so I can play around in-house.</p> 117 <p>In the near future I hope to acquire a Sparc of some type to put Gentoo on so I can play around in-house.</p>
114 </body>
115 </section>
116</chapter>
117
118<chapter>
119 <title>Known Problems With Distcc</title>
120 <section>
121 <title>Portage Doesn't Work With Distcc</title>
122 <body>
123 <p>This heading is a misnomer, really. The only thing that doesn't work is the monitoring programs (<c>distccmon-text</c> and <c>distccmon-gnome</c>) with the standard distcc source. The reason for this is that distcc relies on the <c>TMPDIR</c> envvar, but Portage reassigns that.</p>
124 <p>The solution to this is a patch that changes the dependency to <c>DISTCC_TMPDIR</c>. The patch is automatically applied to distcc. If you don't want to use <path>/tmp</path> (the default) you can reassign <c>DISTCC_TMPDIR</c>.</p>
125 <p>You may also notice that Distcc does not work with some packages. This can be a result of several things, such as an error in the .ebuild (Using <c>make</c> instead of <c>emake</c>) or an error in the program's Makefile, which the next section addresses.</p>
126 </body>
127 </section>
128 <section>
129 <title>Mozilla and Xfree</title>
130 <body>
131 <p>As you emerge various packages, you'll notice that they aren't being distributed (and indeed aren't being built in parallel). This is because the developers of Mozilla and Xfree .ebuilds disabled parallel building because it is known to cause problems. This isn't necessarily a distcc problem.</p>
132 <p>That isn't to say that sometimes distcc will cause a package to fail to compile.</p>
133 </body> 118 </body>
134 </section> 119 </section>
135</chapter> 120</chapter>
136 121
137<chapter> 122<chapter>
157 <body> 142 <body>
158 <impo>Do not forget to start sshd and reset the root password for the LiveCD!</impo> 143 <impo>Do not forget to start sshd and reset the root password for the LiveCD!</impo>
159 <p>Next, you have to boot your new box with a Gentoo Linux LiveCD and follow all of the steps up until the bootstrapping. Then proceed with a little preliminary setup on the new box.</p> 144 <p>Next, you have to boot your new box with a Gentoo Linux LiveCD and follow all of the steps up until the bootstrapping. Then proceed with a little preliminary setup on the new box.</p>
160 <pre caption="Preliminary Setup"> 145 <pre caption="Preliminary Setup">
161<codenote>Here we add distcc to FEATURES</codenote> 146<codenote>Here we add distcc to FEATURES</codenote>
162# <i>echo "FEATURES=\"\${FEATURES} distcc\"" >> /etc/make.conf</i> 147# <i>echo "FEATURES=\"\${FEATURES} distcc\"" &gt;&gt; /etc/make.conf</i>
163<codenote>You can also use <i>nano</i> to edit <path>/etc/make.conf</path> and manually add distcc to FEATURES.</codenote> 148<codenote>You can also use <i>nano</i> to edit <path>/etc/make.conf</path> and manually add distcc to FEATURES.</codenote>
164# <i>echo "MAKEOPTS=\"\${MAKEOPTS} -jN\"" >> /etc/make.conf</i> 149# <i>echo "MAKEOPTS=\"\${MAKEOPTS} -jN\"" &gt;&gt; /etc/make.conf</i>
165<codenote>Just like above, you can use <i>nano</i> to edit <path>/etc/make.conf</path> and manually change MAKEOPTS.</codenote> 150<codenote>Just like above, you can use <i>nano</i> to edit <path>/etc/make.conf</path> and manually change MAKEOPTS.</codenote>
166 </pre> 151 </pre>
167 <p>Then add the distcc user to your <path>/etc/passwd</path>:</p> 152 <p>Then add the distcc user to your <path>/etc/passwd</path>:</p>
168 <pre caption="Add the distcc user to /etc/passwd"> 153 <pre caption="Add the distcc user to /etc/passwd">
169# <i>echo "distcc:x:240:2:distccd:/dev/null:/bin/false" >>/etc/passwd</i> 154# <i>echo "distcc:x:240:2:distccd:/dev/null:/bin/false" &gt;&gt;/etc/passwd</i>
170<codenote>Do not forget the `<i>&gt;&gt;</i>'</codenote> 155<codenote>Do not forget the `<i>&gt;&gt;</i>'</codenote>
171 </pre> 156 </pre>
172 </body> 157 </body>
173 </section> 158 </section>
174 <section> 159 <section>
199 <body> 184 <body>
200 <p>Now set up distcc itself...</p> 185 <p>Now set up distcc itself...</p>
201 <pre caption="Final distcc setup"> 186 <pre caption="Final distcc setup">
202# <i>/usr/bin/distcc-config --install</i> 187# <i>/usr/bin/distcc-config --install</i>
203# <i>/usr/bin/distcc-config --set-hosts "localhost host1 host2 host3 ..."</i> 188# <i>/usr/bin/distcc-config --set-hosts "localhost host1 host2 host3 ..."</i>
204 </pre> 189 </pre>
205
206 <p>distcc should be set up now to bootstrap! Continue the official install guide, and don't forget to re-emerge distcc after <c>emerge system</c>.</p> 190 <p>distcc should be set up now to bootstrap! Continue the official install guide, and don't forget to re-emerge distcc after <c>emerge system</c>.</p>
207 </body> 191 </body>
208 </section> 192 </section>
209</chapter> 193</chapter>
210 194
195<chapter>
196 <title>Known Problems With Distcc</title>
197 <section>
198 <title>Mozilla and Xfree</title>
199 <body>
200 <p>As you emerge various packages, you'll notice that they aren't being distributed (and indeed aren't being built in parallel). This is because the developers of Mozilla and Xfree .ebuilds disabled parallel building because it is known to cause problems. This isn't necessarily a distcc problem.</p>
201 <p>That isn't to say that sometimes distcc will cause a package to fail to compile.</p>
202 </body>
203 </section>
204 <section>
205 <title>A Mixture of hardened-gcc and non-hardened-gcc Hosts Will Be Faulty</title>
206 <body>
207 <p>With such a long title any explanation here is almost irrelevent. However, if you plan to use distcc across hosts that have the <uri link="http://www.gentoo.org/proj/en/hardened/etdyn-ssp.xml">PaX/hardened-gcc</uri> and some that do not, you will run into problems.</p>
208 <p>The solution requires a little foresight on your part; you have to run <c>hardened-gcc -R</c> on the host that has PaX/hardened-gcc, or you have to enable PaX protections in your kernel and <c>emerge hardened-gcc</c>. Both of which are a good thing to do since for the most part the protections offered by both packages is a good thing and is transparent to the user.</p>
209 </body>
210 </section>
211 <section>
212 <title>Mixed GCC Versions</title>
213 <body>
214 <p>If you have differing versions of GCC on your hosts, there will likely be very weird problems. The solution is to make certain all hosts have the same GCC version.</p>
215 </body>
216 </section>
217</chapter>
211 218
212<chapter> 219<chapter>
213 <title>Distcc Extras</title> 220 <title>Distcc Extras</title>
214 <section> 221 <section>
215 <title>Distcc Monitors</title> 222 <title>Distcc Monitors</title>
216 <body> 223 <body>
217 <p>Distcc ships with two monitors. The text-based one is always built, it is called <c>distccmon-text</c>. Running it for the first time can be a bit confusing, but it is really quite easy to use. If you run the program with no parameter it will run once. However, if you pass it a number it will update every N seconds, where N is the argument you passed.</p> 224 <p>Distcc ships with two monitors. The text-based one is always built, it is called <c>distccmon-text</c>. Running it for the first time can be a bit confusing, but it is really quite easy to use. If you run the program with no parameter it will run once. However, if you pass it a number it will update every N seconds, where N is the argument you passed.</p>
218 <p>The other monitor is only turned on if you enabled <c>gtk</c> in your <c>USE</c> flags. This one is GTK+ based and runs in an X environment, and it is quite lovely.</p> 225 <p>The other monitor is only turned on if you enabled <c>gtk</c> in your <c>USE</c> flags. This one is GTK+ based and runs in an X environment, and it is quite lovely.</p>
219 <p>There is a caveat to using these programs. If you want to monitor any emerge, you have to start the monitor like so:</p> 226 <p>There is a caveat to using these programs. If you want to monitor any emerge, you have to start the monitor like so:</p>
220 <pre caption="Starting the monitors"> 227 <pre caption="Starting the monitors">
221# <i>sudo -u portage distccmon-text N</i> 228# <i>DISTCC_DIR=/path/to/distccdir portage distccmon-text N</i>
222<codenote>Or you can start the graphical monitor...</codenote> 229<codenote>Or you can start the graphical monitor...</codenote>
223# <i>sudo -u portage distccmon-gnome</i> 230# <i>DISTCC_DIR=/path/to/distccdir portage distccmon-gnome</i>
224 </pre> 231 </pre>
225 <note>If you aren't using <c>userpriv</c> in your FEATURES, you 232 <note>If you aren't using Portage you do not need to specify DISTCC_DIR (i.e., just type distccmon-text N).</note>
226 should not use the '-u portage' part.</note> 233 <impo>If you are using Portage and used the above example, this will be <c>DISTCC_DIR=/var/tmp/portage/.distcc</c>.</impo>
227 </body> 234 </body>
228 </section> 235 </section>
229</chapter> 236</chapter>
230 237
231<chapter> 238<chapter>

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

  ViewVC Help
Powered by ViewVC 1.1.20