/[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.6 - (show annotations) (download) (as text)
Sat Oct 6 20:19:38 2012 UTC (22 months, 2 weeks ago) by swift
Branch: MAIN
Changes since 1.5: +5 -5 lines
File MIME type: application/xml
Bug #437338 - Rephraze an apparently more diffult to parse line

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 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-portage-advanced.xml,v 1.5 2012/10/06 20:17:51 swift Exp $ -->
8
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 <version>5</version>
19 <date>2012-10-06</date>
20
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 <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 </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 the various build functions (like src_prepare, src_configure, pkg_postinst,
125 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 <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 </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 system set), forced use flags and more.
236 </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 provided you with
303 a patch and asked you to check if it fixes the 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