| 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.4 2012/08/15 07:20:36 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>4</version> |
| 19 |
<date>2012-08-15</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/<identifier></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/<category>/<package>[-<version>[-<revision>]]</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> |
Parent Directory
| 
Revision Log