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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.39 - (hide annotations) (download) (as text)
Thu Oct 27 18:33:42 2011 UTC (2 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.38: +7 -4 lines
File MIME type: application/xml
As per Jan ("jkt") feedback, ensure that directory is 0700 and mention key fingerprint (currently valid, but might change in november as the key expires then)

1 swift 1.10 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3    
4 swift 1.1 <!-- The content of this document is licensed under the CC-BY-SA license -->
5 swift 1.29 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6 swift 1.1
7 swift 1.39 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-features.xml,v 1.38 2011/10/26 19:46:19 swift Exp $ -->
8 swift 1.1
9     <sections>
10 swift 1.23
11 neysx 1.33 <abstract>
12     Discover the features Portage has, such as support for distributed compiling,
13     ccache and more.
14     </abstract>
15    
16 swift 1.39 <version>3</version>
17     <date>2011-10-27</date>
18 swift 1.23
19 swift 1.1 <section>
20 swift 1.19 <title>Portage Features</title>
21     <body>
22    
23     <p>
24     Portage has several additional features that makes your Gentoo experience even
25     better. Many of these features rely on certain software tools that improve
26     performance, reliability, security, ...
27     </p>
28    
29     <p>
30     To enable or disable certain Portage features you need to edit
31 swift 1.28 <path>/etc/make.conf</path>'s <c>FEATURES</c> variable which contains the
32     various feature keywords, separated by white space. In several cases you
33 swift 1.19 will also need to install the additional tool on which the feature relies.
34     </p>
35    
36     <p>
37     Not all features that Portage supports are listed here. For a full overview,
38 swift 1.21 please consult the <path>make.conf</path> man page:
39 swift 1.19 </p>
40    
41 swift 1.21 <pre caption="Consulting the make.conf man page">
42 swift 1.19 $ <i>man make.conf</i>
43     </pre>
44    
45     <p>
46 cam 1.27 To find out what FEATURES are default set, run <c>emerge --info</c> and search
47     for the FEATURES variable or grep it out:
48 swift 1.19 </p>
49    
50     <pre caption="Finding out the FEATURES that are already set">
51 cam 1.27 $ <i>emerge --info | grep FEATURES</i>
52 swift 1.19 </pre>
53    
54     </body>
55     </section>
56     <section>
57     <title>Distributed Compiling</title>
58 swift 1.1 <subsection>
59 swift 1.19 <title>Using distcc</title>
60 swift 1.1 <body>
61    
62 swift 1.2 <p>
63 swift 1.19 <c>distcc</c> is a program to distribute compilations across several, not
64 swift 1.2 necessarily identical, machines on a network. The <c>distcc</c> client sends all
65 swift 1.19 necessary information to the available distcc servers (running <c>distccd</c>)
66     so they can compile pieces of source code for the client. The net result is a
67 swift 1.2 faster compilation time.
68     </p>
69    
70     <p>
71 swift 1.19 You can find more information about <c>distcc</c> (and how to have it work
72     with Gentoo) in our <uri link="/doc/en/distcc.xml">Gentoo Distcc
73     Documentation</uri>.
74 swift 1.2 </p>
75    
76 swift 1.1 </body>
77     </subsection>
78     <subsection>
79 swift 1.19 <title>Installing distcc</title>
80 swift 1.1 <body>
81    
82 swift 1.2 <p>
83     Distcc ships with a graphical monitor to monitor tasks that your computer is
84 swift 1.19 sending away for compilation. If you use Gnome then put 'gnome' in your USE
85     variable. However, if you don't use Gnome and would still like to have the
86     monitor then you should put 'gtk' in your USE variable.
87 swift 1.2 </p>
88    
89 swift 1.19 <pre caption="Installing distcc">
90 swift 1.2 # <i>emerge distcc</i>
91     </pre>
92    
93 swift 1.1 </body>
94     </subsection>
95     <subsection>
96     <title>Activating Portage Support</title>
97     <body>
98    
99 swift 1.2 <p>
100 swift 1.19 Add <c>distcc</c> to the FEATURES variable inside <path>/etc/make.conf</path>.
101     Next, 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
103     host) plus one, but you might have better results with other numbers.
104 swift 1.2 </p>
105    
106     <p>
107 swift 1.19 Now run <c>distcc-config</c> and enter the list of available distcc servers. For
108     a 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):
110 swift 1.2 </p>
111    
112 swift 1.19 <pre caption="Configuring distcc to use three available distcc servers">
113 swift 1.3 # <i>distcc-config --set-hosts "192.168.1.102 192.168.1.103 192.168.1.104"</i>
114     </pre>
115    
116     <p>
117 swift 1.19 Don't forget to run the <c>distccd</c> daemon as well:
118 swift 1.3 </p>
119    
120 swift 1.19 <pre caption="Starting the distccd daemons">
121     # <i>rc-update add distccd default</i>
122 swift 1.3 # <i>/etc/init.d/distccd start</i>
123     </pre>
124    
125 swift 1.1 </body>
126     </subsection>
127     </section>
128     <section>
129 swift 1.19 <title>Caching Compilation</title>
130 swift 1.1 <subsection>
131 swift 1.19 <title>About ccache</title>
132 swift 1.1 <body>
133    
134 swift 1.4 <p>
135 nightmorph 1.37 <c>ccache</c> is a fast compiler cache. When you compile a program, it will
136 swift 1.19 cache intermediate results so that, whenever you recompile the same program, the
137 nightmorph 1.37 compilation time is greatly reduced. The first time you run ccache, it will be
138     much slower than a normal compilation. Subsequent recompiles should be faster.
139     ccache is only helpful if you will be recompiling the same application many
140     times; thus it's mostly only useful for software developers.
141 swift 1.4 </p>
142    
143     <p>
144 swift 1.19 If you are interested in the ins and outs of ccache, please visit the
145 swift 1.4 <uri link="http://ccache.samba.org">ccache homepage</uri>.
146     </p>
147    
148 nightmorph 1.37 <warn>
149     <c>ccache</c> is known to cause numerous compilation failures. Sometimes ccache
150     will retain stale code objects or corrupted files, which can lead to packages
151     that cannot be emerged. If this happens (if you receive errors like "File not
152     recognized: File truncated"), try recompiling the application with ccache
153     disabled (<c>FEATURES="-ccache"</c> in <path>/etc/make.conf</path>)
154     <e>before</e> reporting a bug. Unless you are doing development work, <e>do not
155     enable ccache</e>.
156     </warn>
157    
158 swift 1.1 </body>
159     </subsection>
160     <subsection>
161 swift 1.4 <title>Installing ccache</title>
162 swift 1.1 <body>
163    
164 swift 1.4 <p>
165 swift 1.19 To install <c>ccache</c>, run <c>emerge ccache</c>:
166 swift 1.4 </p>
167    
168     <pre caption="Installing ccache">
169     # <i>emerge ccache</i>
170     </pre>
171    
172 swift 1.1 </body>
173     </subsection>
174     <subsection>
175 swift 1.19 <title>Activating Portage Support</title>
176 swift 1.1 <body>
177 swift 1.4
178     <p>
179 swift 1.19 Open <path>/etc/make.conf</path> and add <c>ccache</c> to the FEATURES variable.
180     Next, add a new variable called CCACHE_SIZE and set it to "2G":
181 swift 1.4 </p>
182    
183     <pre caption="Editing CCACHE_SIZE in /etc/make.conf">
184     CCACHE_SIZE="2G"
185     </pre>
186    
187     <p>
188 swift 1.30 To check if ccache functions, ask ccache to provide you with its statistics.
189     Because Portage uses a different ccache home directory, you need to set the
190     <c>CCACHE_DIR</c> variable as well:
191 swift 1.4 </p>
192    
193     <pre caption="Viewing ccache statistics">
194 swift 1.30 # <i>CCACHE_DIR="/var/tmp/ccache" ccache -s</i>
195 swift 1.4 </pre>
196 swift 1.1
197 swift 1.30 <p>
198     The <path>/var/tmp/ccache</path> location is Portage' default ccache home
199     directory; if you want to alter this setting you can set the <c>CCACHE_DIR</c>
200     variable in <path>/etc/make.conf</path>.
201     </p>
202    
203     <p>
204     However, 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
206     <c>CCACHE_DIR</c> variable when asking for the (Portage) ccache statistics.
207     </p>
208    
209 swift 1.1 </body>
210     </subsection>
211 swift 1.12 <subsection>
212 swift 1.19 <title>Using ccache for non-Portage C Compiling</title>
213 swift 1.12 <body>
214    
215     <p>
216     If you would like to use ccache for non-Portage compilations, add
217 nightmorph 1.32 <path>/usr/lib/ccache/bin</path> to the beginning of your PATH variable (before
218     <path>/usr/bin</path>). This can be accomplished by editing
219     <path>.bash_profile</path> in your user's home directory. Using
220     <path>.bash_profile</path> is one way to define PATH variables.
221 swift 1.12 </p>
222    
223 nightmorph 1.32 <pre caption="Editing .bash_profile">
224 nightmorph 1.35 PATH="<i>/usr/lib/ccache/bin</i>:/opt/bin:${PATH}"
225 swift 1.12 </pre>
226    
227     </body>
228     </subsection>
229 swift 1.1 </section>
230     <section>
231 swift 1.19 <title>Binary Package Support</title>
232 swift 1.1 <subsection>
233 swift 1.19 <title>Creating Prebuilt Packages</title>
234 swift 1.1 <body>
235    
236 swift 1.2 <p>
237 swift 1.19 Portage supports the installation of prebuilt packages. Even though Gentoo does
238     not provide prebuilt packages by itself (except for the GRP snapshots) Portage
239     can be made fully aware of prebuilt packages.
240 swift 1.2 </p>
241    
242     <p>
243 swift 1.19 To create a prebuilt package you can use <c>quickpkg</c> if the package is
244     already installed on your system, or <c>emerge</c> with the <c>--buildpkg</c> or
245     <c>--buildpkgonly</c> options.
246 swift 1.2 </p>
247    
248     <p>
249 swift 1.19 If you want Portage to create prebuilt packages of every single package you
250     install, add <c>buildpkg</c> to the FEATURES variable.
251 swift 1.2 </p>
252    
253     <p>
254 swift 1.19 More extended support for creating prebuilt package sets can be obtained with
255     <c>catalyst</c>. For more information on catalyst please read the <uri
256 rane 1.36 link="/proj/en/releng/catalyst/faq.xml">Catalyst Frequently Asked
257     Questions</uri>.
258 swift 1.2 </p>
259 swift 1.6
260 swift 1.5 </body>
261     </subsection>
262     <subsection>
263 swift 1.19 <title>Installing Prebuilt Packages</title>
264 swift 1.5 <body>
265    
266     <p>
267 swift 1.19 Although Gentoo doesn't provide one, you can create a central repository where
268     you store prebuilt packages. If you want to use this repository, you need to
269     make Portage aware of it by having the PORTAGE_BINHOST variable point to
270     it. For instance, if the prebuilt packages are on ftp://buildhost/gentoo:
271 swift 1.5 </p>
272    
273 swift 1.19 <pre caption="Setting PORTAGE_BINHOST in /etc/make.conf">
274     PORTAGE_BINHOST="ftp://buildhost/gentoo"
275 swift 1.5 </pre>
276    
277     <p>
278 swift 1.19 When you want to install a prebuilt package, add the <c>--getbinpkg</c> option
279     to the emerge command alongside of the <c>--usepkg</c> option. The former tells
280     emerge to download the prebuilt package from the previously defined server
281     while the latter asks emerge to try to install the prebuilt package first before
282     fetching the sources and compiling it.
283 swift 1.5 </p>
284    
285 swift 1.7 <p>
286 swift 1.19 For instance, to install <c>gnumeric</c> with prebuilt packages:
287 swift 1.7 </p>
288    
289 swift 1.19 <pre caption="Installing the gnumeric prebuilt package">
290     # <i>emerge --usepkg --getbinpkg gnumeric</i>
291 swift 1.7 </pre>
292    
293 swift 1.5 <p>
294 swift 1.19 More information about emerge's prebuilt package options can be found in the
295 swift 1.21 emerge man page:
296 swift 1.5 </p>
297    
298 swift 1.21 <pre caption="Reading the emerge man page">
299 swift 1.19 $ <i>man emerge</i>
300 swift 1.2 </pre>
301 swift 1.1
302     </body>
303     </subsection>
304     </section>
305 nightmorph 1.34 <section>
306     <title>Fetching Files</title>
307     <subsection>
308     <title>Parallel fetch</title>
309     <body>
310    
311     <p>
312     When you are emerging a series of packages, Portage can fetch the source files
313     for the next package in the list even while it is compiling another package,
314     thus shortening compile times. To make use of this capability, add
315     "parallel-fetch" to your FEATURES.
316     </p>
317    
318     </body>
319     </subsection>
320     <subsection>
321     <title>Userfetch</title>
322     <body>
323    
324     <p>
325     When Portage is run as root, FEATURES="userfetch" will allow Portage to drop
326     root privileges while fetching package sources. This is a small security
327     improvement.
328     </p>
329    
330     </body>
331     </subsection>
332     </section>
333 swift 1.38 <section id="webrsync-gpg">
334     <title>Pulling Validated Portage Tree Snapshots</title>
335     <body>
336    
337     <p>
338     As an administrator, you can opt to only update your local Portage tree with a
339     cryptographically validated Portage tree snapshot as released by the Gentoo
340     infrastructure. This ensures that no rogue rsync mirror is adding unwanted code
341     or packages in the tree you are downloading.
342     </p>
343    
344     <p>
345     To configure Portage, first create a truststore in which you download and accept
346     the keys of the Gentoo Infrastructure responsible for signing the Portage tree
347     snapshots. Of course, if you want to, you can validate this GPG key as per the
348 swift 1.39 <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     C26E 239C 75C4</c>).
351 swift 1.38 </p>
352    
353     <pre caption="Creating a truststore for Portage">
354     # <i>mkdir -p /etc/portage/gpg</i>
355 swift 1.39 # <i>chmod 0700 /etc/portage/gpg</i>
356 swift 1.38 # <i>gpg --homedir /etc/portage/gpg --keyserver subkeys.pgp.net --recv-keys 0x239C75C4</i>
357     # <i>gpg --homedir /etc/portage/gpg --edit-key 0x239C75C4 trust</i>
358     </pre>
359    
360     <p>
361     Next, edit <path>/etc/make.conf</path> and enable support for validating the
362     signed Portage tree snapshots (using <c>FEATURES="webrsync-gpg"</c>) and
363     disabling updating the Portage tree using the regular <c>emerge --sync</c>
364     method.
365     </p>
366    
367     <pre caption="Updating Portage for signed tree validation">
368     FEATURES="webrsync-gpg"
369     PORTAGE_GPG_DIR="/etc/portage/gpg"
370     SYNC=""
371     </pre>
372    
373     <p>
374     That's it. Next time you run <c>emerge-webrsync</c>, only the snapshots with
375     a valid signature will be expanded on your file system.
376     </p>
377    
378    
379     </body>
380     </section>
381    
382 swift 1.1 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20