/[gentoo]/xml/htdocs/doc/en/handbook/hb-portage-advanced.xml
Gentoo

Contents of /xml/htdocs/doc/en/handbook/hb-portage-advanced.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.4 - (hide annotations) (download) (as text)
Wed Aug 15 07:20:36 2012 UTC (2 years, 2 months ago) by swift
Branch: MAIN
Changes since 1.3: +4 -5 lines
File MIME type: application/xml
Fix bug #429980 - Describe virtuals properly, remove reference to virtuals file in profile (old-style virtuals)

1 swift 1.1 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3    
4     <!-- The content of this document is licensed under the CC-BY-SA license -->
5     <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6    
7 swift 1.4 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-portage-advanced.xml,v 1.3 2012/07/24 12:12:52 swift Exp $ -->
8 swift 1.1
9     <sections>
10    
11     <abstract>
12     As times goes by, Portage evolves and matures further and further. Additional
13     features are continuously being put in - many of these are only of use by more
14     advanced users. This chapter will go into more detail of these specific
15     features.
16     </abstract>
17    
18 swift 1.4 <version>4</version>
19     <date>2012-08-15</date>
20 swift 1.1
21     <section>
22     <title>Introduction</title>
23     <body>
24    
25     <p>
26     For most users, the information received thus far is sufficient for all their
27     Linux operations. But Portage is capable of much more; many of its features are
28     for advanced users or only applicable in specific corner cases. Still, that
29     would not be an excuse not to document them.
30     </p>
31    
32     <p>
33     Of course, with lots of flexibility comes a huge list of potential cases. It
34     will not be possible to document them all here. Instead, we hope to focus on
35     some generic issues which you can then bend to fit your own needs. If you have
36     need for more specific tweaks and tips, you might find them on the <uri
37     link="https://wiki.gentoo.org">Gentoo WiKi</uri> instead.
38     </p>
39    
40     <p>
41     Most, if not all of these additional features can be easily found by digging
42     through the manual pages that portage provides:
43     </p>
44    
45     <pre caption="Reading up on portage man pages">
46     $ <i>man portage</i>
47     $ <i>man make.conf</i>
48     </pre>
49    
50     <p>
51     Finally, know that these are advanced features which, if not worked with
52     correctly, can make debugging and troubleshooting very difficult. Make sure you
53     mention these if you think you hit a bug and want to open a bugreport.
54     </p>
55    
56     </body>
57     </section>
58    
59     <section>
60     <title>Per-Package Environment Variables</title>
61     <subsection>
62     <title>Using /etc/portage/env</title>
63     <body>
64    
65     <p>
66     By default, package builds will use the environment variables defined in
67 swift 1.3 <path>/etc/portage/make.conf</path>, such as <c>CFLAGS</c>, <c>MAKEOPTS</c>
68     and more. In some cases though, you might want to provide different variables
69     for specific packages. To do so, Portage supports the use of
70     <path>/etc/portage/env</path> and <path>/etc/portage/package.env</path>.
71 swift 1.1 </p>
72    
73     <p>
74     The <path>/etc/portage/package.env</path> file contains the list of packages for
75     which you want deviating variables as well as a specific identifier that tells
76     Portage which changes you want. The identifier name you pick yourself, Portage
77     will look for the variables in the <path>/etc/portage/env/&lt;identifier&gt;</path>
78     file.
79     </p>
80    
81     </body>
82     </subsection>
83     <subsection>
84     <title>Example: Using debugging for specific packages</title>
85     <body>
86    
87     <p>
88     As an example, we enable debugging for the <path>media-video/mplayer</path>
89     package.
90     </p>
91    
92     <p>
93     First of all, we set the debugging variables in a file called
94     <path>/etc/portage/env/debug-cflags</path>. The name is arbitrarily chosen, but
95     of course reflects the reason of the deviation to make it more obvious later why
96     a deviation was put in.
97     </p>
98    
99     <pre caption="/etc/portage/env/debug-cflags content">
100     CFLAGS="-O2 -ggdb -pipe"
101     FEATURES="${FEATURES} nostrip"
102     </pre>
103    
104     <p>
105     Next, we tag the <path>media-video/mplayer</path> package to use this content:
106     </p>
107    
108     <pre caption="/etc/portage/package.env content">
109     media-video/mplayer debug-cflags
110     </pre>
111    
112     </body>
113     </subsection>
114     </section>
115    
116     <section>
117     <title>Hooking In the Emerge Process</title>
118     <subsection>
119     <title>Using /etc/portage/bashrc and affiliated files</title>
120     <body>
121    
122     <p>
123     When Portage works with ebuilds, it uses a bash environment in which it calls
124 swift 1.2 the various build functions (like src_prepare, src_configure, pkg_postinst,
125 swift 1.1 etc.). But Portage also allows you to set up a bash environment yourself.
126     </p>
127    
128     <p>
129     The advantage of using your own bash environment is that you can hook in the
130     emerge process during each step it performs. This can be done for every emerge
131     (through <path>/etc/portage/bashrc</path>) or by using per-package environments
132     (through <path>/etc/portage/env</path> as discussed earlier).
133     </p>
134    
135     <p>
136     To hook in the process, the bash environment can listen to the variables
137     <c>EBUILD_PHASE</c>, <c>CATEGORY</c> as well as the variables that are always
138     available during ebuild development (such as <c>P</c>, <c>PF</c>, ...). Based on
139     the values of these variables, you can then execute additional steps.
140     </p>
141    
142     </body>
143     </subsection>
144     <subsection>
145     <title>Example: Updating File Databases</title>
146     <body>
147    
148     <p>
149     In this example, we'll use <path>/etc/portage/bashrc</path> to call some file
150     database applications to ensure their databases are up to date with the system.
151     The applications used in the example are <c>aide</c> (an intrusion detection
152     tool) and <c>updatedb</c> (to use with <c>locate</c>), but these are meant as
153     examples. Do not consider this as a HOWTO for AIDE ;-)
154     </p>
155    
156     <p>
157     To use <path>/etc/portage/bashrc</path> for this case, we need to "hook" in the
158     <c>postrm</c> (after removal of files) and <c>postinst</c> (after installation
159     of files) functions, because that is when the files on the file system have been
160     changed.
161     </p>
162    
163     <pre caption="Example /etc/portage/bashrc">
164     if [ "${EBUILD_PHASE}" == "postinst"] || [ "${EBUILD_PHASE}" == "postrm" ];
165     then
166     echo ":: Calling aide --update to update its database";
167     aide --update;
168     echo ":: Calling updatedb to update its database";
169     updatedb;
170     fi
171     </pre>
172    
173     </body>
174     </subsection>
175     </section>
176    
177     <section>
178     <title>Executing Tasks After --sync</title>
179     <subsection>
180     <title>The /etc/portage/postsync.d location</title>
181     <body>
182    
183     <p>
184     Until now we've talked about hooking into the ebuild processes. However, Portage
185     also has another important function: updating the Portage tree. In order to run
186     tasks after updating the Portage tree, put a script inside
187     <path>/etc/portage/postsync.d</path> and make sure it is marked as executable.
188     </p>
189    
190     </body>
191     </subsection>
192     <subsection>
193     <title>Example: Running eix-update</title>
194     <body>
195    
196     <p>
197     If you didn't use <c>eix-sync</c> to update the tree, you can still have its
198     database updated after running <c>emerge --sync</c> (or <c>emerge-webrsync</c>)
199     by putting a symlink to <path>/usr/bin/eix</path> called <path>eix-update</path>
200     in <path>/etc/portage/postsync.d</path>.
201     </p>
202    
203     <pre caption="Running eix-update after a sync operation">
204     # <i>ln -s /usr/bin/eix /etc/portage/postsync.d/eix-update</i>
205     </pre>
206    
207     <note>
208     If you rather use a different name, you will need to make a script that calls
209     <c>/usr/bin/eix-update</c> instead. The <c>eix</c> binary looks at how it has
210     been called to find out which function it has to execute. If you put in a
211     symlink to <c>eix</c> that isn't called <c>eix-update</c>, it will not run
212     correctly.
213     </note>
214    
215     </body>
216     </subsection>
217     </section>
218    
219     <section>
220     <title>Overriding Profile Settings</title>
221     <subsection>
222     <title>The /etc/portage/profile location</title>
223     <body>
224    
225     <p>
226     By default, Gentoo uses the settings contained in the profile pointed to by
227 swift 1.3 <path>/etc/portage/make.profile</path> (a symbolic link to the right profile
228     directory). These profiles define both specific settings as well as inherit
229     settings from other profiles (through their <path>parent</path> file).
230 swift 1.1 </p>
231    
232     <p>
233     By using <path>/etc/portage/profile</path>, you can override profile settings
234     such as <path>packages</path> (what packages are considered to be part of the
235 swift 1.4 system set), forced use flags and more.
236 swift 1.1 </p>
237    
238     </body>
239     </subsection>
240     <subsection>
241     <title>Example: Adding nfs-utils to the System Set</title>
242     <body>
243    
244     <p>
245     If you use NFS-based file systems for rather critical file systems, you might
246     want to have <path>net-fs/nfs-utils</path> "protected" as a system package,
247     causing Portage to heavily warn you if it would be deleted.
248     </p>
249    
250     <p>
251     To accomplish that, we add the package to
252     <path>/etc/portage/profile/packages</path>, prepended with a <c>*</c>:
253     </p>
254    
255     <pre caption="/etc/portage/profile/packages content">
256     *net-fs/nfs-utils
257     </pre>
258    
259     </body>
260     </subsection>
261     </section>
262    
263     <section>
264     <title>Applying Non-Standard Patches</title>
265     <subsection>
266     <title>Using epatch_user</title>
267     <body>
268    
269     <p>
270     To manage several ebuilds in a similar manner, ebuild developers use
271     <e>eclasses</e> (sort-of shell libraries) that define commonly used functions.
272     One of these eclasses is <path>eutils.eclass</path> which offers an interesting
273     function called <c>epatch_user</c>.
274     </p>
275    
276     <p>
277     The <c>epatch_user</c> function applies source code patches that are found in
278     <path>/etc/portage/patches/&lt;category&gt;/&lt;package&gt;[-&lt;version&gt;[-&lt;revision&gt;]]</path>,
279     whatever directory is found first. Sadly, not all ebuilds automatically call
280     this function so just putting your patch in this location might not always work.
281     </p>
282    
283     <p>
284     Luckily, with the information provided above, you can call this function by
285     hooking into, for instance, the <c>prepare</c> phase. The function can be called
286     as many times as you like - it will only apply the patches once.
287     </p>
288    
289     </body>
290     </subsection>
291     <subsection>
292     <title>Example: Applying Patches to Firefox</title>
293     <body>
294    
295     <p>
296     The <path>www-client/firefox</path> package is one of the few that already call
297     <c>epatch_user</c> from within the ebuild, so you do not need to override
298     anything specific.
299     </p>
300    
301     <p>
302     If you need to patch firefox (for instance because a developer asked you to to
303     support you in a bug you reported), put the patch in
304     <path>/etc/portage/patches/www-client/firefox</path> (probably best to use the
305     full name, including version so that the patch does not interfere with later
306     versions) and rebuild firefox.
307     </p>
308    
309     </body>
310     </subsection>
311     </section>
312    
313     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20