/[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.40 Revision 1.43
1<?xml version='1.0' encoding='UTF-8'?> 1<?xml version='1.0' encoding='UTF-8'?>
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/2.5 --> 5<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6 6
7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v 1.40 2011/11/27 18:25:28 swift Exp $ --> 7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v 1.43 2012/07/24 12:12:52 swift Exp $ -->
8 8
9<sections> 9<sections>
10 10
11<abstract> 11<abstract>
12Discover the features Portage has, such as support for distributed compiling, 12Discover the features Portage has, such as support for distributed compiling,
13ccache and more. 13ccache and more.
14</abstract> 14</abstract>
15 15
16<version>4</version> 16<version>7</version>
17<date>2011-11-27</date> 17<date>2012-07-24</date>
18 18
19<section> 19<section>
20<title>Portage Features</title> 20<title>Portage Features</title>
21<body> 21<body>
22 22
23<p> 23<p>
24Portage has several additional features that makes your Gentoo experience even 24Portage has several additional features that makes your Gentoo experience even
25better. Many of these features rely on certain software tools that improve 25better. Many of these features rely on certain software tools that improve
26performance, reliability, security, ... 26performance, reliability, security, ...
27</p> 27</p>
28 28
29<p> 29<p>
30To enable or disable certain Portage features you need to edit 30To enable or disable certain Portage features you need to edit
31<path>/etc/make.conf</path>'s <c>FEATURES</c> variable which contains the 31<path>/etc/portage/make.conf</path>'s <c>FEATURES</c> variable which contains
32various feature keywords, separated by white space. In several cases you 32the various feature keywords, separated by white space. In several cases you
33will also need to install the additional tool on which the feature relies. 33will also need to install the additional tool on which the feature relies.
34</p> 34</p>
35 35
36<p> 36<p>
37Not all features that Portage supports are listed here. For a full overview, 37Not all features that Portage supports are listed here. For a full overview,
38please consult the <path>make.conf</path> man page: 38please consult the <path>make.conf</path> man page:
39</p> 39</p>
40 40
41<pre caption="Consulting the make.conf man page"> 41<pre caption="Consulting the make.conf man page">
42$ <i>man make.conf</i> 42$ <i>man make.conf</i>
43</pre> 43</pre>
44 44
45<p> 45<p>
46To find out what FEATURES are default set, run <c>emerge --info</c> and search 46To find out what FEATURES are default set, run <c>emerge --info</c> and search
47for the FEATURES variable or grep it out: 47for the FEATURES variable or grep it out:
85variable. However, if you don't use Gnome and would still like to have the 85variable. However, if you don't use Gnome and would still like to have the
86monitor then you should put 'gtk' in your USE variable. 86monitor then you should put 'gtk' in your USE variable.
87</p> 87</p>
88 88
89<pre caption="Installing distcc"> 89<pre caption="Installing distcc">
90# <i>emerge distcc</i> 90# <i>emerge distcc</i>
91</pre> 91</pre>
92 92
93</body> 93</body>
94</subsection> 94</subsection>
95<subsection> 95<subsection>
96<title>Activating Portage Support</title> 96<title>Activating Portage Support</title>
97<body> 97<body>
98 98
99<p> 99<p>
100Add <c>distcc</c> to the FEATURES variable inside <path>/etc/make.conf</path>. 100Add <c>distcc</c> to the FEATURES variable inside <path>/etc/portage/make.conf</path>.
101Next, edit the MAKEOPTS variable to your liking. A known guideline is to fill in 101Next, edit the MAKEOPTS variable to your liking. A known guideline is to fill in
102"-jX" with X the number of CPUs that run <c>distccd</c> (including the current 102"-jX" with X the number of CPUs that run <c>distccd</c> (including the current
103host) plus one, but you might have better results with other numbers. 103host) plus one, but you might have better results with other numbers.
104</p> 104</p>
105 105
106<p> 106<p>
107Now run <c>distcc-config</c> and enter the list of available distcc servers. For 107Now run <c>distcc-config</c> and enter the list of available distcc servers. For
108a simple example we assume that the available DistCC servers are 192.168.1.102 108a simple example we assume that the available DistCC servers are 192.168.1.102
109(the current host), 192.168.1.103 and 192.168.1.104 (two "remote" hosts): 109(the current host), 192.168.1.103 and 192.168.1.104 (two "remote" hosts):
110</p> 110</p>
111 111
112<pre caption="Configuring distcc to use three available distcc servers"> 112<pre caption="Configuring distcc to use three available distcc servers">
113# <i>distcc-config --set-hosts "192.168.1.102 192.168.1.103 192.168.1.104"</i> 113# <i>distcc-config --set-hosts "192.168.1.102 192.168.1.103 192.168.1.104"</i>
114</pre> 114</pre>
115 115
138much slower than a normal compilation. Subsequent recompiles should be faster. 138much slower than a normal compilation. Subsequent recompiles should be faster.
139ccache is only helpful if you will be recompiling the same application many 139ccache is only helpful if you will be recompiling the same application many
140times; thus it's mostly only useful for software developers. 140times; thus it's mostly only useful for software developers.
141</p> 141</p>
142 142
143<p> 143<p>
144If you are interested in the ins and outs of ccache, please visit the 144If you are interested in the ins and outs of ccache, please visit the
145<uri link="http://ccache.samba.org">ccache homepage</uri>. 145<uri link="http://ccache.samba.org">ccache homepage</uri>.
146</p> 146</p>
147 147
148<warn> 148<warn>
149<c>ccache</c> is known to cause numerous compilation failures. Sometimes ccache 149<c>ccache</c> is known to cause numerous compilation failures. Sometimes ccache
150will retain stale code objects or corrupted files, which can lead to packages 150will retain stale code objects or corrupted files, which can lead to packages
151that cannot be emerged. If this happens (if you receive errors like "File not 151that cannot be emerged. If this happens (if you receive errors like "File not
152recognized: File truncated"), try recompiling the application with ccache 152recognized: File truncated"), try recompiling the application with ccache
153disabled (<c>FEATURES="-ccache"</c> in <path>/etc/make.conf</path>) 153disabled (<c>FEATURES="-ccache"</c> in <path>/etc/portage/make.conf</path>)
154<e>before</e> reporting a bug. Unless you are doing development work, <e>do not 154<e>before</e> reporting a bug. Unless you are doing development work, <e>do not
155enable ccache</e>. 155enable ccache</e>.
156</warn> 156</warn>
157 157
158</body> 158</body>
159</subsection> 159</subsection>
160<subsection> 160<subsection>
161<title>Installing ccache</title> 161<title>Installing ccache</title>
162<body> 162<body>
163 163
164<p> 164<p>
165To install <c>ccache</c>, run <c>emerge ccache</c>: 165To install <c>ccache</c>, run <c>emerge ccache</c>:
166</p> 166</p>
167 167
168<pre caption="Installing ccache"> 168<pre caption="Installing ccache">
169# <i>emerge ccache</i> 169# <i>emerge ccache</i>
170</pre> 170</pre>
171 171
172</body> 172</body>
173</subsection> 173</subsection>
174<subsection> 174<subsection>
175<title>Activating Portage Support</title> 175<title>Activating Portage Support</title>
176<body> 176<body>
177 177
178<p> 178<p>
179Open <path>/etc/make.conf</path> and add <c>ccache</c> to the FEATURES variable. 179Open <path>/etc/portage/make.conf</path> and add <c>ccache</c> to the FEATURES
180Next, add a new variable called CCACHE_SIZE and set it to "2G": 180variable. Next, add a new variable called CCACHE_SIZE and set it to "2G":
181</p> 181</p>
182 182
183<pre caption="Editing CCACHE_SIZE in /etc/make.conf"> 183<pre caption="Editing CCACHE_SIZE in /etc/portage/make.conf">
184CCACHE_SIZE="2G" 184CCACHE_SIZE="2G"
185</pre> 185</pre>
186 186
187<p> 187<p>
188To check if ccache functions, ask ccache to provide you with its statistics. 188To check if ccache functions, ask ccache to provide you with its statistics.
189Because Portage uses a different ccache home directory, you need to set the 189Because Portage uses a different ccache home directory, you need to set the
190<c>CCACHE_DIR</c> variable as well: 190<c>CCACHE_DIR</c> variable as well:
191</p> 191</p>
192 192
193<pre caption="Viewing ccache statistics"> 193<pre caption="Viewing ccache statistics">
194# <i>CCACHE_DIR="/var/tmp/ccache" ccache -s</i> 194# <i>CCACHE_DIR="/var/tmp/ccache" ccache -s</i>
195</pre> 195</pre>
196 196
197<p> 197<p>
198The <path>/var/tmp/ccache</path> location is Portage' default ccache home 198The <path>/var/tmp/ccache</path> location is Portage' default ccache home
199directory; if you want to alter this setting you can set the <c>CCACHE_DIR</c> 199directory; if you want to alter this setting you can set the <c>CCACHE_DIR</c>
200variable in <path>/etc/make.conf</path>. 200variable in <path>/etc/portage/make.conf</path>.
201</p> 201</p>
202 202
203<p> 203<p>
204However, if you would run <c>ccache</c>, it would use the default location of 204However, if you would run <c>ccache</c>, it would use the default location of
205<path>${HOME}/.ccache</path>, which is why you needed to set the 205<path>${HOME}/.ccache</path>, which is why you needed to set the
206<c>CCACHE_DIR</c> variable when asking for the (Portage) ccache statistics. 206<c>CCACHE_DIR</c> variable when asking for the (Portage) ccache statistics.
207</p> 207</p>
208 208
209</body> 209</body>
210</subsection> 210</subsection>
211<subsection> 211<subsection>
212<title>Using ccache for non-Portage C Compiling</title> 212<title>Using ccache for non-Portage C Compiling</title>
213<body> 213<body>
214 214
215<p> 215<p>
258</p> 258</p>
259 259
260</body> 260</body>
261</subsection> 261</subsection>
262<subsection> 262<subsection>
263<title>Installing Prebuilt Packages</title> 263<title>Installing Prebuilt Packages</title>
264<body> 264<body>
265 265
266<p> 266<p>
267Although Gentoo doesn't provide one, you can create a central repository where 267Although Gentoo doesn't provide one, you can create a central repository where
268you store prebuilt packages. If you want to use this repository, you need to 268you store prebuilt packages. If you want to use this repository, you need to
269make Portage aware of it by having the PORTAGE_BINHOST variable point to 269make Portage aware of it by having the PORTAGE_BINHOST variable point to
270it. For instance, if the prebuilt packages are on ftp://buildhost/gentoo: 270it. For instance, if the prebuilt packages are on ftp://buildhost/gentoo:
271</p> 271</p>
272 272
273<pre caption="Setting PORTAGE_BINHOST in /etc/make.conf"> 273<pre caption="Setting PORTAGE_BINHOST in /etc/portage/make.conf">
274PORTAGE_BINHOST="ftp://buildhost/gentoo" 274PORTAGE_BINHOST="ftp://buildhost/gentoo"
275</pre> 275</pre>
276 276
277<p> 277<p>
278When you want to install a prebuilt package, add the <c>--getbinpkg</c> option 278When you want to install a prebuilt package, add the <c>--getbinpkg</c> option
279to the emerge command alongside of the <c>--usepkg</c> option. The former tells 279to the emerge command alongside of the <c>--usepkg</c> option. The former tells
280emerge to download the prebuilt package from the previously defined server 280emerge to download the prebuilt package from the previously defined server
281while the latter asks emerge to try to install the prebuilt package first before 281while the latter asks emerge to try to install the prebuilt package first before
282fetching the sources and compiling it. 282fetching the sources and compiling it.
283</p> 283</p>
284 284
285<p> 285<p>
286For instance, to install <c>gnumeric</c> with prebuilt packages: 286For instance, to install <c>gnumeric</c> with prebuilt packages:
287</p> 287</p>
288 288
300</pre> 300</pre>
301 301
302</body> 302</body>
303</subsection> 303</subsection>
304</section> 304</section>
305<section> 305<section>
306<title>Fetching Files</title> 306<title>Fetching Files</title>
307<subsection> 307<subsection>
308<title>Parallel fetch</title> 308<title>Parallel fetch</title>
309<body> 309<body>
310 310
311<p> 311<p>
312When you are emerging a series of packages, Portage can fetch the source files 312When you are emerging a series of packages, Portage can fetch the source files
313for the next package in the list even while it is compiling another package, 313for the next package in the list even while it is compiling another package,
314thus shortening compile times. To make use of this capability, add 314thus shortening compile times. To make use of this capability, add
315"parallel-fetch" to your FEATURES. 315"parallel-fetch" to your FEATURES. Note that this is on by default, so you
316shouldn't need to specifically enable it.
316</p> 317</p>
317 318
318</body> 319</body>
319</subsection> 320</subsection>
320<subsection> 321<subsection>
321<title>Userfetch</title> 322<title>Userfetch</title>
322<body> 323<body>
323 324
324<p> 325<p>
325When Portage is run as root, FEATURES="userfetch" will allow Portage to drop 326When Portage is run as root, FEATURES="userfetch" will allow Portage to drop
326root privileges while fetching package sources. This is a small security 327root privileges while fetching package sources. This is a small security
327improvement. 328improvement.
328</p> 329</p>
329 330
330</body> 331</body>
334<title>Pulling Validated Portage Tree Snapshots</title> 335<title>Pulling Validated Portage Tree Snapshots</title>
335<body> 336<body>
336 337
337<p> 338<p>
338As an administrator, you can opt to only update your local Portage tree with a 339As an administrator, you can opt to only update your local Portage tree with a
339cryptographically validated Portage tree snapshot as released by the Gentoo 340cryptographically validated Portage tree snapshot as released by the Gentoo
340infrastructure. This ensures that no rogue rsync mirror is adding unwanted code 341infrastructure. This ensures that no rogue rsync mirror is adding unwanted code
341or packages in the tree you are downloading. 342or packages in the tree you are downloading.
342</p> 343</p>
343 344
344<p> 345<p>
345To configure Portage, first create a truststore in which you download and accept 346To configure Portage, first create a truststore in which you download and accept
346the keys of the Gentoo Infrastructure responsible for signing the Portage tree 347the keys of the Gentoo Infrastructure responsible for signing the Portage tree
347snapshots. Of course, if you want to, you can validate this GPG key as per the 348snapshots. Of course, if you want to, you can validate this GPG key as per the
348<uri link="/doc/en/gnupg-user.xml#doc_chap2_sect4">proper guidelines</uri> 349<uri link="/doc/en/gnupg-user.xml#doc_chap2_sect4">proper guidelines</uri>
349(like checking the key fingerprint <c>AE54 54F9 67B5 6AB0 9AE1 6064 0838 350(like checking the key fingerprint). You can find the list of GPG keys used by
350C26E 239C 75C4</c> for key <c>0x239C75C4</c> or <c>DCD0 5B71 EAB9 4199 527F 44AC 351the release engineering team on their <uri
351DB6B 8C1F 96D8 BF6D</c> for key <c>0x96D8BF6D</c>). 352link="/proj/en/releng/index.xml">project page</uri>.
352</p> 353</p>
353 354
354<!-- Key 0x239C75C4 is superceded by 0x96D8BF6D, but keep it in the documents 355<!-- Key 0x239C75C4 is superceded by 0x96D8BF6D, but keep it in the documents
355 for a while to ensure continuity --> 356 for a while to ensure continuity -->
356 357
357<pre caption="Creating a truststore for Portage"> 358<pre caption="Creating a truststore for Portage">
358# <i>mkdir -p /etc/portage/gpg</i> 359# <i>mkdir -p /etc/portage/gpg</i>
359# <i>chmod 0700 /etc/portage/gpg</i> 360# <i>chmod 0700 /etc/portage/gpg</i>
361<comment>(... Substitute the keys with those mentioned on the release engineering site ...)</comment>
360# <i>gpg --homedir /etc/portage/gpg --keyserver subkeys.pgp.net --recv-keys 0x239C75C4 0x96D8BF6D</i> 362# <i>gpg --homedir /etc/portage/gpg --keyserver subkeys.pgp.net --recv-keys 0x239C75C4 0x96D8BF6D</i>
361# <i>gpg --homedir /etc/portage/gpg --edit-key 0x239C75C4 trust</i> 363# <i>gpg --homedir /etc/portage/gpg --edit-key 0x239C75C4 trust</i>
362# <i>gpg --homedir /etc/portage/gpg --edit-key 0x96D8BF6D trust</i> 364# <i>gpg --homedir /etc/portage/gpg --edit-key 0x96D8BF6D trust</i>
363</pre> 365</pre>
364 366
365<p> 367<p>
366Next, edit <path>/etc/make.conf</path> and enable support for validating the 368Next, edit <path>/etc/portage/make.conf</path> and enable support for validating
367signed Portage tree snapshots (using <c>FEATURES="webrsync-gpg"</c>) and 369the signed Portage tree snapshots (using <c>FEATURES="webrsync-gpg"</c>) and
368disabling updating the Portage tree using the regular <c>emerge --sync</c> 370disabling updating the Portage tree using the regular <c>emerge --sync</c>
369method. 371method.
370</p> 372</p>
371 373
372<pre caption="Updating Portage for signed tree validation"> 374<pre caption="Updating Portage for signed tree validation">
373FEATURES="webrsync-gpg" 375FEATURES="webrsync-gpg"
374PORTAGE_GPG_DIR="/etc/portage/gpg" 376PORTAGE_GPG_DIR="/etc/portage/gpg"
375SYNC="" 377SYNC=""
376</pre> 378</pre>
377 379
378<p> 380<p>
379That's it. Next time you run <c>emerge-webrsync</c>, only the snapshots with 381That's it. Next time you run <c>emerge-webrsync</c>, only the snapshots with
380a valid signature will be expanded on your file system. 382a valid signature will be expanded on your file system.
381</p> 383</p>
382 384

Legend:
Removed from v.1.40  
changed lines
  Added in v.1.43

  ViewVC Help
Powered by ViewVC 1.1.20