/[gentoo]/xml/htdocs/doc/en/handbook/hb-working-features.xml
Gentoo

Diff of /xml/htdocs/doc/en/handbook/hb-working-features.xml

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

Revision 1.18 Revision 1.19
2<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> 2<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3 3
4<!-- The content of this document is licensed under the CC-BY-SA license --> 4<!-- The content of this document is licensed under the CC-BY-SA license -->
5<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> 5<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
6 6
7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v 1.18 2004/09/19 21:55:58 vapier Exp $ --> 7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v 1.19 2004/10/21 10:31:20 swift Exp $ -->
8 8
9<sections> 9<sections>
10<section> 10<section>
11<title>DistCC</title> 11<title>Portage Features</title>
12<subsection> 12<body>
13<title>What is DistCC?</title> 13
14<p>
15Portage has several additional features that makes your Gentoo experience even
16better. Many of these features rely on certain software tools that improve
17performance, reliability, security, ...
18</p>
19
20<p>
21To enable or disable certain Portage features you need to edit
22<path>/etc/make.conf</path>'s <c>FEATURES</c> variable. In several cases you
23will also need to install the additional tool on which the feature relies.
24</p>
25
26<p>
27Not all features that Portage supports are listed here. For a full overview,
28please consult the <path>make.conf</path> manpage:
29</p>
30
31<pre caption="Consulting the make.conf manpage">
32$ <i>man make.conf</i>
33</pre>
34
35<p>
36To find out what FEATURES are default set, run <c>emerge info</c> and search for
37the FEATURES variable or grep it out:
38</p>
39
40<pre caption="Finding out the FEATURES that are already set">
41$ <i>emerge info | grep FEATURES</i>
42</pre>
43
14<body> 44</body>
45</section>
46<section>
47<title>Distributed Compiling</title>
48<subsection>
49<title>Using distcc</title>
50<body>
15 51
16<p> 52<p>
17<c>distcc</c> is a program to distribute compilations across several, not 53<c>distcc</c> is a program to distribute compilations across several, not
18necessarily identical, machines on a network. The <c>distcc</c> client sends all 54necessarily identical, machines on a network. The <c>distcc</c> client sends all
19necessary information to the available DistCC servers (running <c>distccd</c>) 55necessary information to the available distcc servers (running <c>distccd</c>)
20so they can compile pieces of source code for the client. The net result is a 56so they can compile pieces of source code for the client. The net result is a
21faster compilation time. 57faster compilation time.
22</p> 58</p>
23 59
24<p> 60<p>
25You can find more elaborate information about <c>distcc</c> (and information on 61You can find more information about <c>distcc</c> (and how to have it work
26how to have it work with Gentoo) in our <uri link="/doc/en/distcc.xml">Gentoo 62with Gentoo) in our <uri link="/doc/en/distcc.xml">Gentoo Distcc
27Distcc Documentation</uri>. 63Documentation</uri>.
28</p> 64</p>
29 65
30</body> 66</body>
31</subsection>
32<subsection> 67</subsection>
68<subsection>
33<title>Installing DistCC</title> 69<title>Installing distcc</title>
34<body> 70<body>
35 71
36<p> 72<p>
37Distcc ships with a graphical monitor to monitor tasks that your computer is 73Distcc ships with a graphical monitor to monitor tasks that your computer is
38sending away for compilation. If you use Gnome then put 'gnome' in your 74sending away for compilation. If you use Gnome then put 'gnome' in your USE
39<c>USE</c> setting. However, if you don't use Gnome and would still like to have 75variable. However, if you don't use Gnome and would still like to have the
40the monitor then you should put 'gtk' in your <c>USE</c> setting. 76monitor then you should put 'gtk' in your USE variable.
41</p>
42
43<p> 77</p>
44Installing distcc is, as is with all software available through Gentoo's
45Portage, extremely easy:
46</p>
47 78
48<pre caption="Installing Distcc"> 79<pre caption="Installing distcc">
49# <i>emerge distcc</i> 80# <i>emerge distcc</i>
50</pre> 81</pre>
51 82
52</body> 83</body>
53</subsection> 84</subsection>
54<subsection> 85<subsection>
55<title>Activating Portage Support</title> 86<title>Activating Portage Support</title>
56<body> 87<body>
57 88
58<p> 89<p>
59Well, if installation is easy, the rest should be easy too :) So let us quickly 90Add <c>distcc</c> to the FEATURES variable inside <path>/etc/make.conf</path>.
60activate the Portage support for <c>distcc</c>. 91Next, edit the MAKEOPTS variable to your liking. A known guideline is to fill in
61</p> 92"-jX" with X the number of CPUs that run <c>distccd</c> (including the current
62 93host) plus one, but you might have better results with other numbers.
63<p> 94</p>
64First, open <path>/etc/make.conf</path> and edit the <c>FEATURES</c> variable so 95
65it contains the <c>distcc</c> keyword. Next, edit the <c>MAKEOPTS</c> variable
66so it reads <c>-jX</c> with <c>X</c> the number of CPUs that run <c>distccd</c>
67(including the current host) plus one:
68</p> 96<p>
69
70<pre caption="Possible MAKEOPTS setting in /etc/make.conf">
71<comment># Suppose you have 2 single-CPU distccd hosts excluding this host:</comment>
72MAKEOPTS="-j4"
73</pre>
74
75<p>
76Now run <c>distcc-config</c> and enter the list of available DistCC servers. For 97Now run <c>distcc-config</c> and enter the list of available distcc servers. For
77a simple example we assume that the available DistCC servers are 98a simple example we assume that the available DistCC servers are 192.168.1.102
78<c>192.168.1.102</c> (the current host), <c>192.168.1.103</c> and 99(the current host), 192.168.1.103 and 192.168.1.104 (two "remote" hosts):
79<c>192.168.1.104</c> (two "remote" hosts):
80</p> 100</p>
81 101
82<pre caption="Configuring distcc to use three available DistCC servers"> 102<pre caption="Configuring distcc to use three available distcc servers">
83# <i>distcc-config --set-hosts "192.168.1.102 192.168.1.103 192.168.1.104"</i> 103# <i>distcc-config --set-hosts "192.168.1.102 192.168.1.103 192.168.1.104"</i>
84</pre> 104</pre>
85 105
86<p> 106<p>
87Of course, don't forget to run the <c>distccd</c> daemon too: 107Don't forget to run the <c>distccd</c> daemon as well:
88</p> 108</p>
89 109
90<pre caption="Starting the distcc daemon"> 110<pre caption="Starting the distccd daemons">
111# <i>rc-update add distccd default</i>
91# <i>/etc/init.d/distccd start</i> 112# <i>/etc/init.d/distccd start</i>
92</pre> 113</pre>
93 114
94<p>
95Congratulations, your system will now use distributed compiling! For more
96in-depth information about DistCC and Gentoo, please read our <uri
97link="/doc/en/distcc.xml">Gentoo DistCC Documentation</uri>.
98</p>
99
100</body> 115</body>
101</subsection>
102</section>
103<section>
104<title>ccache</title>
105<subsection> 116</subsection>
117</section>
118<section>
119<title>Caching Compilation</title>
120<subsection>
106<title>What is ccache?</title> 121<title>About ccache</title>
107<body> 122<body>
108 123
109<p> 124<p>
110<c>ccache</c> is a fast compiler cache. When you compile a program, it will 125<c>ccache</c> is a fast compiler cache. When you compile a program, it will
111cache intermediate results so that, whenever you recompile the same program, 126cache intermediate results so that, whenever you recompile the same program, the
112the compilation time is greatly reduced. In common compilations this can result 127compilation time is greatly reduced. In common compilations this can result in 5
113in 5 to 10 times faster compilation times. 128to 10 times faster compilation times.
114</p>
115
116<p> 129</p>
130
131<p>
117If you are interested in the ins and outs of <c>ccache</c>, please visit the 132If you are interested in the ins and outs of ccache, please visit the
118<uri link="http://ccache.samba.org">ccache homepage</uri>. 133<uri link="http://ccache.samba.org">ccache homepage</uri>.
119</p> 134</p>
120 135
121</body> 136</body>
122</subsection> 137</subsection>
123<subsection> 138<subsection>
124<title>Installing ccache</title> 139<title>Installing ccache</title>
125<body> 140<body>
126 141
127<p> 142<p>
128Installing <c>ccache</c> with Gentoo is a breeze. Just emerge it and you're done 143To install <c>ccache</c>, run <c>emerge ccache</c>:
129:)
130</p> 144</p>
131 145
132<pre caption="Installing ccache"> 146<pre caption="Installing ccache">
133# <i>emerge ccache</i> 147# <i>emerge ccache</i>
134</pre> 148</pre>
135 149
136</body> 150</body>
137</subsection> 151</subsection>
138<subsection> 152<subsection>
139<title>Tweaking ccache</title> 153<title>Activating Portage Support</title>
140<body> 154<body>
141 155
142<p> 156<p>
143Portage will automatically use ccache if it's installed. However, you can alter 157Open <path>/etc/make.conf</path> and add <c>ccache</c> to the FEATURES variable.
144the default cache size used by ccache by providing a <c>CCACHE_SIZE</c> variable 158Next, add a new variable called CCACHE_SIZE and set it to "2G":
145in <path>/etc/make.conf</path>:
146</p> 159</p>
147 160
148<pre caption="Editing CCACHE_SIZE in /etc/make.conf"> 161<pre caption="Editing CCACHE_SIZE in /etc/make.conf">
149CCACHE_SIZE="2G" 162CCACHE_SIZE="2G"
150</pre> 163</pre>
151 164
152<p> 165<p>
153As of now, Portage will use <c>ccache</c> to speed up compilations where 166To check if ccache functions, ask ccache to provide you with it's statistics:
154possible. If you are uncertain that <c>ccache</c> works, you can run <c>ccache
155-s</c> to view the <c>ccache</c> statistics:
156</p> 167</p>
157 168
158<pre caption="Viewing ccache statistics"> 169<pre caption="Viewing ccache statistics">
159# <i>ccache -s</i> 170# <i>ccache -s</i>
160</pre> 171</pre>
161 172
162</body> 173</body>
163</subsection> 174</subsection>
164<subsection> 175<subsection>
165<title>Using ccache for non-Portage C compiling</title> 176<title>Using ccache for non-Portage C Compiling</title>
166<body> 177<body>
167 178
168<p> 179<p>
169If you would like to use ccache for non-Portage compilations, add 180If you would like to use ccache for non-Portage compilations, add
170<path>/usr/lib/ccache/bin</path> to the beginning of your <c>PATH</c> variable 181<path>/usr/lib/ccache/bin</path> to the beginning of your PATH variable
171(before <path>/usr/bin</path>). This can be accomplished by editing 182(before <path>/usr/bin</path>). This can be accomplished by editing
172<path>/etc/profile</path>: 183<path>/etc/env.d/00basic</path>:
173</p>
174
175<pre caption="Editing profile">
176# <i>nano -w /etc/profile</i>
177# <i>source /etc/profile</i>
178</pre> 184</p>
179 185
186<pre caption="Editing /etc/env.d/00basic">
187PATH="/usr/local/bin:/opt/bin<i>:/usr/lib/ccache/bin</i>"
188</pre>
189
180</body> 190</body>
181</subsection>
182</section>
183<section>
184<title>Binary Packages</title>
185<subsection> 191</subsection>
186<title>Creating binary packages</title> 192</section>
187<body> 193<section>
188 194<title>Binary Package Support</title>
189<p>
190We have already discussed how to work with prebuilt packages, but how do you
191create your own prebuilt packages?
192</p>
193
194<p>
195If the package is already installed, you can use the <c>quickpkg</c> command
196which will make a tarball of the installed files. This is very useful for
197backup purposes!
198</p>
199
200<pre caption="Using quickpkg">
201# <i>quickpkg gnumeric</i>
202</pre>
203
204<p>
205If the package isn't installed yet, you can install it using <c>emerge</c> and
206ask to build a binary package too. <c>emerge</c> uses the <c>--buildpkg</c>
207option (<c>-b</c> in short) for this:
208</p>
209
210<pre caption="Installing gnumeric and building binary packages too">
211# <i>emerge --buildpkg gnumeric</i>
212</pre>
213
214<p>
215If you want Portage to do this by default, you should set the <c>buildpkg</c>
216keyword in the <c>FEATURES</c> variable declared in <path>/etc/make.conf</path>.
217</p>
218
219<pre caption="Automatically creating binary packages">
220FEATURES="buildpkg"
221</pre>
222
223<p>
224If you don't want to install the software, but only build the package, you can
225use the <c>--buildpkgonly</c> option (<c>-B</c> in short):
226</p>
227
228<pre caption="Building a binary package for gnumeric">
229# <i>emerge --buildpkgonly gnumeric</i>
230</pre>
231
232</body>
233</subsection> 195<subsection>
234</section> 196<title>Creating Prebuilt Packages</title>
235<section> 197<body>
236<title>Security Related Features</title> 198
199<p>
200Portage supports the installation of prebuilt packages. Even though Gentoo does
201not provide prebuilt packages by itself (except for the GRP snapshots) Portage
202can be made fully aware of prebuilt packages.
203</p>
204
205<p>
206To create a prebuilt package you can use <c>quickpkg</c> if the package is
207already installed on your system, or <c>emerge</c> with the <c>--buildpkg</c> or
208<c>--buildpkgonly</c> options.
209</p>
210
211<p>
212If you want Portage to create prebuilt packages of every single package you
213install, add <c>buildpkg</c> to the FEATURES variable.
214</p>
215
216<p>
217More extended support for creating prebuilt package sets can be obtained with
218<c>catalyst</c>. For more information on catalyst please read the <uri
219link="http://www.gentoo.org/proj/en/releng/catalyst/reference.xml">Catalyst
220Reference Manual</uri> and <uri
221link="http://www.gentoo.org/proj/en/releng/catalyst/catalyst-howto.xml">Catalyst
222Howto</uri>.
223</p>
224
225</body>
237<subsection> 226</subsection>
238<title>Sandbox</title>
239<body>
240
241<p>
242While building and installing packages, Portage uses a <e>sandbox</e> to protect
243your live system. This means that, as long as the package isn't installed on
244your system, the package cannot touch any file outside the sandbox. This
245ensures that Portage knows what files are created and modified by a package.
246</p>
247
248<p>
249When the package compilation is finished, Portage will "preinstall" the package
250in the sandbox, registering what files are placed and where. It will then move
251those files from the sandbox on your live system.
252</p>
253
254</body>
255</subsection> 227<subsection>
256<subsection> 228<title>Installing Prebuilt Packages</title>
257<title>User Privileges</title>
258<body>
259
260<p>
261Portage also supports building packages as non-root user (more precisely, as
262user "portage", group "portage"). This improves the security during the
263build process. You can opt to use user privileges with or without sandboxing. Of
264course, it goes without saying that user privileges and sandboxing is the most
265preferred method :)
266</p>
267
268</body> 229<body>
269</subsection>
270<subsection>
271<title>Activating sandbox and/or userpriv</title>
272<body>
273 230
274<p>
275Portage will use <c>sandbox</c> by default. If you want <c>userpriv</c>, you
276should add it to the <c>FEATURES</c> variable. Note that activating
277<c>userpriv</c> will drop <c>sandbox</c> support, unless you also activate
278<c>usersandbox</c>:
279</p> 231<p>
280 232Although Gentoo doesn't provide one, you can create a central repository where
281<pre caption="Activating userpriv and usersandbox"> 233you store prebuilt packages. If you want to use this repository, you need to
282FEATURES="userpriv usersandbox" 234make Portage aware of it by having the PORTAGE_BINHOST variable point to
283</pre> 235it. For instance, if the prebuilt packages are on ftp://buildhost/gentoo:
284
285<warn>
286Do <e>not</e> remove <c>sandbox</c> from the <c>FEATURES</c> variable!
287</warn>
288
289</body>
290</subsection>
291<subsection>
292<title>Strict Checking</title>
293<body>
294
295<p> 236</p>
296Portage can be asked to react strongly to possibly dangerous conditions (such as 237
297missing or incorrect Manifest files). To activate this strict checking, add the 238<pre caption="Setting PORTAGE_BINHOST in /etc/make.conf">
298<c>strict</c> keyword to the <c>FEATURES</c> variable: 239PORTAGE_BINHOST="ftp://buildhost/gentoo"
240</pre>
241
299</p> 242<p>
300 243When you want to install a prebuilt package, add the <c>--getbinpkg</c> option
301<pre caption="Activating strict checking"> 244to the emerge command alongside of the <c>--usepkg</c> option. The former tells
302FEATURES="strict" 245emerge to download the prebuilt package from the previously defined server
303</pre> 246while the latter asks emerge to try to install the prebuilt package first before
304 247fetching the sources and compiling it.
305</body>
306</subsection>
307<subsection>
308<title>Smart File System Permissions</title>
309<body>
310
311<p> 248</p>
312Portage can be told to automatically deal with potentially dangerous file 249
313permissions that could pose a security risk. It does this by removing the
314"group" and "other" readable bits on setuid files and removing the "other"
315readable bit on setgid files in the pre install phase. To activate the
316smart file permissions, add the <c>sfperms</c> keyword to the
317<c>FEATURES</c> variable:
318</p> 250<p>
319 251For instance, to install <c>gnumeric</c> with prebuilt packages:
320<pre caption="Activating smart file system permissions">
321FEATURES="sfperms"
322</pre>
323
324</body>
325</subsection>
326</section>
327<section>
328<title>SLOT'ed Software Titles</title>
329<subsection>
330<title>SLOT ?</title>
331<body>
332
333<p> 252</p>
334Occasionally you need to have several versions of a software title installed at 253
335the same time to satisfy your system's dependencies. Whereas most distributions 254<pre caption="Installing the gnumeric prebuilt package">
336allow this by having their packages called to the version (such as 255# <i>emerge --usepkg --getbinpkg gnumeric</i>
337<c>freetype</c> and <c>freetype2</c>) Portage uses the concept of <e>SLOT</e>s. 256</pre>
257
338</p> 258<p>
339 259More information about emerge's prebuilt package options can be found in the
260emerge manpage:
340<p> 261</p>
341A <e>SLOT</e> is a (part of a) version number that tells Portage that all
342equally named packages with a different SLOT are able to coexist on the same
343system. Portage is able to track both branches of a certain package and update
344them if updates to the respective branches are available.
345</p>
346 262
347<p> 263<pre caption="Reading the emerge manpage">
348When you perform an update Portage will only automatically unmerge the old 264$ <i>man emerge</i>
349instance of a package if it uses the same SLOT. This is why kernel sources are
350never automatically unmerged as their SLOT is the complete version.
351</p>
352
353</body>
354</subsection>
355</section>
356<section>
357<title>Other Features</title>
358<subsection>
359<title>Portage Help</title>
360<body>
361
362<p>
363There are several other keywords you can place in the <c>FEATURES</c> variable.
364Most of them are targeted towards developers and less interesting for the casual
365user. If you are interested in learning more about these features (or Portage
366generally), don't forget to read the <path>make.conf</path> manpage we provide.
367</p>
368
369<pre caption="More Portage-related information">
370# <i>man make.conf</i>
371</pre> 265</pre>
372 266
373</body> 267</body>
374</subsection> 268</subsection>
375</section> 269</section>

Legend:
Removed from v.1.18  
changed lines
  Added in v.1.19

  ViewVC Help
Powered by ViewVC 1.1.20