Difference between pages "Multiple ABI Support" and "Portage Variables"

(Difference between pages)
 
 
Line 1: Line 1:
=== Summary ===
+
== Introduction ==
  
Support for multiple ABIs has been partially integrated into Portage and the Gentoo gcc wrapper (part of sys-devel/gcc-config) and has been enabled in some system profiles. Extended Multiple ABI is available as part of <tt>multilib.eclass</tt>. This page documents this functionality so it can be more easily understood, used and improved.
+
Ebuild developers as well as users of Portage can control Portage behavior using a number of Portage variables. Also, when an ebuild executes, a number of variables are defined by <tt>ebuild.sh</tt>, the main ebuild script, so they are available for your ebuild. There are also variables that the ebuild writer can define within his or her ebuild to provide information about the ebuild as well as control behavior. Information on [[Ebuild Functions]], which are used to define actions that are performed during various parts of a package's lifecycle, is also available on this wiki.
  
=== Core ABI Support ===
+
{{Note}}An '''ebuild''' is a textual meta-description of a software package (stored in a filename suffixed by ''.ebuild'' and generally located in a subdirectory of ''/usr/portage'') that provides the instructions to build and install the later on your system plus a number of additional informations like a brief summary of the package, the required dependencies to build and run the package, where to get the software package source code and so on. Due to the 1:1 matching between an ebuild file and a software package most of Gentoo and Funtoo developers uses the term ''ebuild'' to designate the  meta-description of a package and the software package it relates in itself.
  
Portage and some system profiles currently contain a very small set of changes so that multiple ABIs can be targeted by Portage. In addition, Gentoo's gcc "wrapper" (part of sys-devel/gcc-config) has a key feature in it to enable this multiple ABI support -- this functionality is detailed later in this section. This implements the core minimal multiple ABI functionality.
+
=== Profile Variables ===
  
In practice, this capability, combined with the gcc-wrapper's ABI support, can come in handy for directing Portage to build libraries for the non-default ABI, using the appropriate directories so that the resultant .tbz2 file can be manually installed on your system without overwriting the libraries for the default ABI. An example of this approach is documented later in this section. This support is also useful when it is necessary for the ebuild to direct the system to create 32-bit versions of some applications that may not be compatible with 64-bit multilib systems, and supports the ability for the ebuild to reliably compile both 32-bit and 64-bit versions of certain applications when necessary.
+
These variables are set in the profile(s) selected on the user's system. These profiles live inside <tt>/usr/portage/profiles</tt>.
  
==== Core ABI: econf() ====
+
; ARCH
 +
: ARCH defines the name for the underlying system architecture. As of late December 2010, Gentoo Linux supports defines the following architectures in various system profiles:
  
Portage's <tt>econf()</tt> function has support for automatically specifying the proper <tt>--libdir=</tt> setting to <tt>configure</tt> based on settings that are found in the system profile. The intended purpose of automatically setting <tt>--libdir=</tt> is designed so that 64-bit libraries will be installed into /usr/lib64 on multilib systems, and 32-bit libraries will be installed into /usr/lib32 on multilib systems, rather than simply installing these libraries into /usr/lib.
+
<tt>alpha
 +
amd64
 +
amd64-fbsd
 +
arm
 +
cobalt
 +
fulong-2e
 +
hppa
 +
hppa-hpux
 +
ia64
 +
ia64-hpux
 +
ip22
 +
ip27
 +
ip28
 +
ip30
 +
ip32
 +
ip32r10k
 +
m68k
 +
m68k-mint
 +
mips
 +
mips-irix
 +
mips64
 +
mips64el
 +
mipsel
 +
ppc
 +
ppc-aix
 +
ppc-macos
 +
ppc-openbsd
 +
ppc64
 +
ppc64-macos
 +
s390
 +
sgi
 +
sh
 +
sparc
 +
sparc-fbsd
 +
sparc-solaris
 +
sparc64
 +
sparc64-fbsd
 +
sparc64-solaris
 +
x64-macos
 +
x64-openbsd
 +
x64-solaris
 +
x86
 +
x86-cygwin
 +
x86-fbsd
 +
x86-interix
 +
x86-macos
 +
x86-netbsd
 +
x86-openbsd
 +
x86-solaris
 +
x86-winnt
 +
xbox
 +
yeeloong</tt>
  
While this functionality has questionable value for most normal ebuilds (since a library installed into /usr/lib will work just as well as one installed into /usr/lib64 on an amd64 multilib system,) this functionality likely comes in handy when building the app-emulation/emul-linux-x86-* binary library bundles to support 32-bit applications, as it allows the ABI to be set in the environment, and in combination with the gcc wrapper will cause 32-bit libraries to be built and installed to /usr/lib32.
+
This list was generated using the following command:
  
==== Core ABI: Gcc Wrapper ====
+
<console>
 +
###i## cd /usr/portage/profiles
 +
###i## grep -r ARCH= * | cut -f2 -d"=" | sed -e 's/"//g' | sort -u
 +
</console>
  
It is important to note that Gentoo Linux uses a ''gcc wrapper'' as a front-end for all calls to gcc, and this wrapper  is part of the sys-devel/gcc-config ebuild. One of the features of the wrapper is that it determines whether the <tt>ABI</tt> variable has been defined in the environment, and if it has, the wrapper will automatically ensure that the <tt>CFLAGS</tt> variable that the compiler sees is actually the <tt>CFLAGS_$ABI</tt> variable, which originates from the system profile. On amd64 multilib systems, this means that a call to <tt>ABI="x86" gcc</tt> will result in an extra <tt>-m32</tt> option being passed to gcc to force it to produce 32-bit code. The <tt>-m32</tt> option will generally not appear in the build log, which may cause some confusion for developers. This is a critical component of the multiple ABI support in Gentoo and Funtoo Linux.
+
=== Path Variables ===
  
==== Core ABI: Working Together ====
+
;PORTDIR
 +
: PORTDIR will be set to the path of the Portage directory that contains the ebuild that is currently executing, such as <tt>/usr/portage</tt>.
  
The algorithm used by <tt>econf()</tt> works as follows: A system profile (or the user, via the environment) sets the <tt>ABI</tt> variable to a value like <tt>amd64</tt> or <tt>x86</tt>. A corresponding ABI-specific variable named <tt>LIBDIR_$ABI</tt> (e.g. <tt>LIBDIR_x86</tt>) will be used from the system profile, and will be set to either <tt>lib32</tt>, <tt>lib64</tt> or <tt>lib</tt>. This will be used to define the target <tt>--libdir</tt> setting used by <tt>econf()</tt>. This will allow the system profile to control exactly where libraries are installed when building them for a particular ABI, as long as the ebuild author uses <tt>econf()</tt> (part of core Portage) or <tt>get_libdir()</tt> (part of <tt>multilib.eclass</tt>.)
+
;PORTAGE_TMPDIR
 +
: PORTAGE_TMPDIR defines the path to the location that Portage should use for all its temporary files, and defaults to <tt>/var/tmp</tt>.
  
In addition, the <tt>ABI</tt> variable set in the environment will cause the gcc-wrapper to adjust the <tt>CFLAGS</tt> variable, by using the <tt>CFLAGS_$ABI</tt> variable to tell the multilib-aware gcc to target the alternate ABI. With <tt>ABI="x86"</tt> on amd64 multilib systems, this will cause <tt>-m32</tt> to be appended to the <tt>CFLAGS</tt> variable, which will instruct gcc to produce 32-bit code.
+
;DISTDIR
 +
: DISTDIR defines the path to the location of all distfiles (downloaded source code/artifacts), and defaults to <tt>/usr/portage/distfiles</tt>.
  
==== Core ABI: Demonstration ====
+
;PKGDIR
 +
: PKGDIR defines the path to where Portage will store all built binary packages, and defaults to <tt>/usr/portage/packages</tt>.
  
To test the multiple ABI functionality on an amd64 multilib system, you can execute the following command:
+
;RPMDIR
 +
: RPMDIR defines the path to where Portage will store all built binary RPM packages, and defaults to <tt>/usr/portage/rpm</tt>.
  
<pre>
+
;ROOT
# ABI="x86" emerge --buildpkgonly sys-libs/zlib
+
:ROOT defines the root of the filesystem to which packages should be installed, and may be set on the command-line. If not defined, Portage will set ROOT to <tt>/</tt> by the time your ebuild executes. When writing <tt>pkg_*</tt> ebuild functions, all your ebuild logic must respect the setting of the ROOT variable and compensate for situations when ROOT is not <tt>/</tt>. ROOT is used by stage1 builds to install to a sub-directory. <tt>ROOT=/tmp/stage1root emerge -e system</tt> is a command that might be run by a stage1 build. After <tt>src_install</tt> executes, Portage will always install the resultant files placed in <tt>$D</tt> to the filesystem defined by ROOT.
</pre>
+
  
If you compare the libz shared library in the resultant .tbz2 package ot the one installed in /lib64, you'll note that the one in the .tbz2 is 32-bit while the one in /lib64 is 64-bit:
+
=== Prefix Variables ===
  
<pre>
+
Portage supports the ability to act as a package manager for commercial operating systems such as MacOS X, or to install ebuilds on non-Gentoo systems, or to sub-directories on Gentoo or non-Gentoo systems. When used in this capacity, ebuilds are not installed to the root filesystem but are instead installed to a subdirectory, called a "prefix". Portage's prefix variables, available in EAPI 3, support this capability, and are designed to work with ebuilds that are maintained in a separate [http://overlays.gentoo.org/proj/alt/browser/trunk/prefix-overlay prefix overlay].
ninja1 lib32 # file libz.so.1.2.5
+
libz.so.1.2.5: ELF 32-bit LSB shared object, Intel 80386, version 1 (SYSV), dynamically linked, stripped
+
ninja1 lib32 # file /lib/libz.so.1.2.5
+
/lib/libz.so.1.2.5: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, stripped
+
</pre>
+
  
It is important to note that Gentoo's gcc wrapper (part of sys-devel/gcc-config) instructs gcc to produce 32-bit code by silently passing (not visible in the build output, due to the wrapper design)a <tt>-m32</tt> option to all compiler calls.
+
As part of the EAPI 3 prefix support, all ebuild helpers such as <tt>econf</tt> and <tt>einstall</tt> use <tt>$ED</tt> instead of <tt>$D</tt>. See below for full variable definitions.
  
Note that you should not install the 32-bit zlib .tbz2 package on a 64-bit multilib system, as it will replace the critical 64-bit zlib binaries on your system. Portage's  /var/db/pkg database does not allow side-by-side installations of packages that were built against different ABIs. However, this Portage functionality can be used to build 32-bit libraries when needed, which can be installed via manual extraction of the resultant .tbz2 file to the root filesystem.
+
;EPREFIX
 +
:This variable is typically set in <tt>/etc/make.conf</tt> or <tt>make.globals</tt>, and defines the prefix that should be used by ebuilds. Prefix-aware ebuilds can reference this variable and use it appropriately. if EPREFIX is not defined, then EPREFIX will default to no value.
  
=== Extended ABI Support ===
+
;EROOT
 +
:EROOT is a more concise way of specifying <tt>$ROOT$EPREFIX</tt>, and is intended to be used in <tt>pkg_*</tt> ebuild functions.
  
Beyond the core functionality, the <tt>multilib.eclass</tt> (which is inherited as part of the ubiquitous <tt>eutils.eclass</tt>) contains a more significant set of code to support multiple ABIs, which appears to be designed to be eventually merged into the Portage core. This means that latent multiple ABI support is available in Portage and can be used without inheriting <tt>multilib.eclass</tt> for "regular" ebuilds, but ebuilds that need more control over the ABI configuration can inherit <tt>multilib.eclass</tt> for access to a significant number of helper functions. If you want to use <tt>multilib.eclass</tt>, first familiarize yourself with the changes in Portage that exist that support <tt>multilib.eclass</tt> functionality, which are documented in this section. Then you will have a much easier time understanding <tt>multilib.eclass</tt>.
+
;ED
 +
:ED is a more concise way of specifying <tt>$D$EPREFIX</tt>, and is intended to be used in <tt>src_*</tt> ebuild functions.  
  
==== ABI Profile Variables ====
+
For more information on Portage's prefix support, see the [http://www.gentoo.org/proj/en/gentoo-alt/prefix/techdocs.xml Gentoo Prefix Techdocs].
  
The following variables are supported on a limited number of architectures - namely, those that have different ABIs available. These include Sparc, PowerPC and PC-compatible x86/amd64 architectures.
+
=== Path Variables For Your Use ===
+
; ABI
+
: Defines the name of the current ABI for which packages should be built. This variable is recognized by the gcc wrapper - see "Core gcc wrapper ABI support", below.
+
  
; DEFAULT_ABI
+
;WORKDIR
: Defines the name of the default ABI for which packages should be built.
+
:WORKDIR defines the temporary filesystem location that is used for extracting source code/artifacts, preparation, configuration and compilation, and will be defined for you by the time your ebuild executes, and its value must not be modified. By default, <tt>src_unpack</tt> will extract all source code/artifacts within WORKDIR. If you need to manually extract any archives, this must all be done somewhere within WORKDIR, T or D, with WORKDIR being the preferred location for doing this. WORKDIR is automatically cleaned up by Portage upon completion.
  
; MULTILIB_ABIS
+
;S
: This consists of a space-separated string of one or more ABIs that are supported on the current system. Amd64 multilib systems will have this set to <tt>amd64 x86</tt>
+
:S defaults to <tt>$WORKDIR/$P</tt>, but may be redefined in your ebuild to be some other sub-directory of WORKDIR. Typically, S may be redefined to reflect the ''real'' directory name that is contained within the source tarball when it differs from the default of <tt>$WORKDIR/$P</tt>. When <tt>src_prepare</tt>, <tt>src_configure</tt>, <tt>src_compile</tt>, <tt>src_test</tt> and <tt>src_install</tt> run, they will attempt to set the current working directory to S if it exists, falling back to WORKDIR if S does not exist.
  
==== ABI-Specific Profile Variables ====
+
;T
 +
:A temporary file storage location that is available to you during your ebuild's execution. T is automatically cleaned up by Portage upon completion.
  
These variables have a suffix (represented below by <tt>*</tt>) that is set based on the ABI that the particular setting is for. For example, <tt>LIBDIR_amd64</tt> would set the library directory name for the amd64 ABI. The rationale for this naming convention is that it allows settings for multiple architectures to be defined together in a single file, and multiple ABI settings to exist on a system that may support multiple ABIs.
+
;D
 +
:D defines the filesystem tree to which the <tt>src_install</tt> function should install all files. All files defined here will be installed by Portage to the destination defined by ROOT.
  
; LIBDIR_*
+
;FILESDIR
 +
: FILESDIR is shorthand for <tt>$PORTDIR/$CATEGORY/$PN/files</tt> -- the <tt>files/</tt> sub-directory in the Portage tree for your particular ebuild. Typically used in <tt>src_prepare</tt> for applying patches, or by <tt>src_install</tt> for installing supplementary files such as initialization scripts that were committed to the Portage tree alongside your ebuild.
  
; CHOST_*
+
=== Metadata Variables ===
  
; CDEFINE_*
+
Metadata variables are variables that you set in your ebuild. They are cached by Portage so they can be quickly accessed for dependency resolution and searches -- in <tt>/var/cache/edb/dep</tt>. When an ebuild is updated, Portage automatically updates the cache the next time it notices the ebuild has changed.
  
; CFLAGS_*
+
;EAPI
: Note: this variable is used by the gcc wrapper when ABI is defined in the environment.
+
: Periodically, the Gentoo Linux project defines new functionality and behavior related to how ebuilds are handled by Portage. These changes may require you to write your ebuilds slightly differently, or may allow you to take advantage of new capabilities in Portage. In your ebuild, you can specify the EAPI you are targeted by setting the EAPI variable as the first line in the ebuild. If no EAPI is specified, an EAPI of 0 ("classic" behavior) is assumed. To view a complete definition of EAPIs 1 through 3, please see [http://devmanual.gentoo.org/ebuild-writing/eapi/index.html The Gentoo Developer Guide's EAPI page]. Note that the information on EAPI 4 is incomplete, and more detailed information can be found on in-progress [http://dev.gentoo.org/~zmedico/portage/doc/ch05s03s05.html EAPI 4 document maintained by Zac Medico]. At some point, it may be possible to set an EAPI on a repository or overlay-wide basis, but for now, it is set by each individual ebuild.
  
; LDFLAGS_*
+
;DEPEND
 +
: DEPEND is used to specify an ebuild's build dependencies, and is a list of all ebuilds (and their corresponding versions/slots) that are required to be installed to a bare stage3 (or @system set + dependencies) in order for this package to '''build''' (compile, etc.). If one or more of these ebuilds are not installed, then it must cause the building of this package to fail; otherwise it is not a true build dependency. Do not list any dependencies for packages that are included in the underlying bare stage3 unless specific versions of the core packages (such as gcc, or glibc) are required, since these packages are expected to be available on all systems. All dependencies listed in DEPEND are satisfied '''prior''' to this package being built.
  
; ASFLAGS_*
+
;RDEPEND
 +
: RDEPEND is used to specify an ebuild's runtime dependencies, and is a list of all ebuilds (and their corresponding versions/slots) that are required to be installed to a bare stage3 (or @system set + dependencies) in order for this package to '''run''' (function). If one or more of these ebuilds are not installed, then it must cause the execution of this package to fail; otherwise it is not a true runtime dependency. Do not list any dependencies for packages that are included in the bare stage3 unless specific versions of the core packages (such as glibc) are required, since these packages are expected to be available on all systems. The dependencies listed in RDEPEND may or not be installed prior to this package being built.
  
==== multilib.eclass ====
+
; DEPEND ''and'' RDEPEND
 +
: Note that if a dependency needs to be available both ''before'' the package is built, and also ''after'' the package is built, then the dependency must be listed in both DEPEND and RDEPEND, as it is both a build and runtime dependency. This is common with many packages, including virtually all shared libraries, which must be installed prior to compilation for headers and linking purposes but must continue to be available after the package is installed so that it can function properly.
  
Note that a number of these functions can probably be replaced with enhanced profile settings, as all they do is spit out canned values based on the setting of one variable or another. They are also prime candidates for inclusion into the Portage core, possibly with some reworking or deprecation so that as many of these as possible are replaced with "dead" variables rather than "live" code.
+
; (R)DEPEND if installed
 +
: It is often useful for an ebuild to conditionally depend on a specific version of another package, if it happens to be installed. Take sys-fs/lvm2 and sys-fs/udev, for example. sys-fs/lvm2 may not always be installed, but sys-fs/udev is a required ebuild. It would be nice if we could specify in the sys-fs/udev ebuild that a specific or higher version of lvm2 is required to work with this particular version of udev, or specify in the lvm2 ebuild that a specific version or higher of udev is required to work with this version of lvm2. While this is not currently possible in Portage, it is possible to use the blocker functionality in Portage to define that earlier versions are ''not'' compatible, which essentially accomplishes the same thing. To specify that another package should not be installed alongside your ebuild, use the double-exclamation from of a blocker: "!!<sys-fs/udev-160" might be an example. This will prevent both ebuilds from being installed on the system at the same time. The double-exclamation blocker is supported in EAPI 2 and above.
  
; has_multilib_profile()
+
; IUSE
: This is a boolean function that returns 0 (true) if multiple ABIs are defined in the MULTILIB_ABIS variable; otherwise 1 (false).
+
: IUSE specifies the USE variables that are recognized by this ebuild. Note that changing IUSE in existing ebuilds should be handled carefully, as if another ebuild depends on a particular USE variable in IUSE being enabled in your ebuild, and you remove it, then Portage will not be able to satisfy this dependency. Similarly, if another ebuild depends on a particular USE variable in IUSE being disabled in your ebuild, and you remove it, then Portage will no longer be able to satisfy this dependency either. For this reason, it can become difficult to remove USE variables from IUSE once other ebuilds explicitly depend upon them being enabled or disabled.
  
; get_libdir()
+
; SRC_URI
: Returns the "lib" directory name to use, based on the current setting of ABI. For example, on amd64 multilib systems, this will typically return <tt>lib64</tt>, and is typically used in <tt>src_configure()</tt> like this: <tt>./configure --libdir=/usr/$(get_libdir)</tt>.
+
: SRC_URI contains a list of all remote files that are used by this ebuild during the unpack/prepare/compile/install phases. Starting with EAPI 2, it is possible to rename source tarballs, which comes in handy when pulling down tagged sources from GitHub, using the following trick. This approach also makes it quite easy to release source tarballs for ebuilds, as all you need to do is tag the release and then push the tags to GitHub with a <tt>git push tags</tt> command:
  
; get_modname()
+
<source lang="bash">
: Used by some ebuilds that generate dynamically-loadable modules, called "bundles" on MacOS X. ELF (used by Linux) makes no differentiation between the handling of shared libraries and loadable modules (or their file extension, which is ".so",) but Mach (MacOS X) does. MacOS X bundles cannot be linked against, but can be dynamically loaded using the dyld API. Apple also recommends that they have an extension of ".bundle" rather than ".so". This function will return ".bundle" for Darwin (Mach) systems, and ".so" for everything else. For more information, see [http://docstore.mik.ua/orelly/unix3/mac/ch05_03.htm MacOS X Guide For Unix Geeks].
+
GITHUB_USER="foo"
 +
SRC_URI="https://github.com/${GITHUB_USER}/${PN}/tarball/${PV} -> ${PN}-git-${PV}.tgz"
  
; get_libname()
+
src_prepare() {
: Used by a handful of ebuilds to determine the proper suffix for shared libraries on the current system. This function has various hard-coded values depending on the value of CHOST. For example, Darwin systems will get an echoed value of "<tt>.dylib</tt>" while Linux systems will get a value of "<tt>.so</tt>". Accepts an optional version argument that will be properly appended to the output.
+
  cd "${WORKDIR}"/${GITHUB_USER}-${PN}-*
 +
  S="$(pwd)"
 +
}
 +
</source>
  
; multilib_env()
+
=== KEYWORDS ===
: Used by toolchain.eclass, gnatbuild.eclass and the glibc ebuild - sets up environment variables for using a cross-compiler. Accepts a single argument - the target architecture in GNU format.
+
  
; multilib_toolchain_setup()
+
KEYWORDS is a general keywording system for ebuilds (meta description of a software package), but is now used exclusively by the Gentoo architecture teams to define whether a particular package is marked as belonging to the stable or the current (''testing'' in Gentoo terminology) branch on a given system architecture. Not all packages are tagged as belonging to stable/current on all architectures, some of them lacks of such tags and are considered as being masked on a particular architecture. This can happen for several reasons like:
: In practice, this function is used exclusively to target a non-default x86 ABI on amd64 multilib systems. It accepts one argument, the name of an ABI, or <tt>default</tt> as a shorthand for the default system ABI. It will configure environment variables so the x86 (or other) compiler is targeted, and also backs up all modified variables so they can be restored later. It is typically used to allow non-64-bit-compatible code to still be installed on amd64 multilib systems, by adding the following to the top of <tt>src_configure()</tt>:
+
* The package makes no sense for the architecture (e.g. SILO ''sys-boot/silo'' which is a boot loader for SPARC machines).
 +
* The package points to a development repository (e.g. version numbered -9999  packages like ''dev-vcs/git-9999'')
 +
* The package makes sense on a a given architecture but no one has tested it (yet)
 +
* The package has been pushed in the portage tree but remains to go in a intensive test cycle before being tagged as current then stable).
  
<pre>
+
In a user's arch profile (see <tt>eselect profile list</tt>.) <tt>ACCEPT_KEYWORDS</tt> variable is defined which specifies what specific keywords should be unmasked for this system by default. On Funtoo Linux systems, ACCEPT_KEYWORDS is set to one of six values:
src_configure() {
+
 
  use amd64 && multilib_toolchain_setup x86
+
;<tt>amd64</tt>
  # we're now building a 32-bit app on a 64-bit system, whee!
+
:64-bit PC-compatible stable tree
  econf
+
;<tt>~amd64</tt>
}
+
:64-bit PC-compatible current tree
</pre>
+
;<tt>x86</tt>
 +
:32-bit PC-compatible stable tree
 +
;<tt>~x86</tt>
 +
:32-bit PC-compatible current tree
 +
;<tt>sparc</tt>
 +
:SPARC stable tree
 +
;<tt>~sparc</tt>
 +
:SPARC current tree
 +
 
 +
An ebuild uses the KEYWORDS variable to control what tree or trees the ebuild is part of, and will contain at most one setting for each system architecture. The KEYWORD settings are defined with the following meaning:
 +
 
 +
;<tt>amd64</tt>
 +
:ebuild unmasked in 64-bit PC-compatible stable '''and current''' trees
 +
;<tt>~amd64</tt>
 +
:ebuild unmasked in 64-bit PC-compatible current tree only
 +
;<tt>-amd64</tt>
 +
:ebuild masked for all 64-bit PC-compatible trees
 +
;<tt>x86</tt>
 +
:ebuild unmasked in 32-bit PC-compatible stable '''and current''' trees
 +
;<tt>~x86</tt>
 +
:ebuild unmasked in 32-bit PC-compatible current tree only
 +
;<tt>-x86</tt>
 +
:ebuild masked for all 32-bit PC-compatible trees
 +
;<tt>sparc</tt>
 +
:ebuild unmasked in SPARC stable '''and current''' trees
 +
;<tt>~sparc</tt>
 +
:ebuild unmasked in SPARC current tree only
 +
;<tt>-sparc</tt>
 +
:ebuild masked for all sparc trees
 +
 
 +
{{ fancyimportant|'''x86''', '''amd64''' or '''sparc''' setting in the ebuild's KEYWORDS will unmask the ebuild for both current and stable tree systems -- that is, any ebuild made available to stable is also made available to current. }}
 +
 
 +
Additional wildcard keywords are supported in ebuilds:
 +
 
 +
;<tt>*</tt>
 +
: unmask for all trees. This variable can be modified by appending negative keywords: <tt>"* -ia64"</tt> means "all keywords except (~)ia64
 +
;<tt>-*</tt>
 +
:mask for all trees. This variable can be modified by appending positive keywords: <tt>"-* amd64 x86"</tt> means "no keywords except for x86 and amd64 stable trees
 +
 
 +
===== Gentoo Linux KEYWORDS Policies =====
 +
 
 +
Due to the exclusive use of KEYWORDS by the Gentoo Linux architecture teams, a number of unfortunate policy-related checks have been integrated into the Portage source code. One is banning the use of <tt>KEYWORDS="*"</tt> to enable KEYWORDS for all available architectures, since it is Gentoo Linux policy for each architecture team to independently verify an ebuild one architecture at a time - this rule currently applies to all ebuilds, including architecture-independent ebuilds. This means that virtually all ebuilds originating from Gentoo Linux will specify an exhaustive, explicit list of all architecture trees for which this package has been unmasked, which will look something like this:
  
=== ABI Support Limitations ===
+
<source lang="bash">
 +
KEYWORDS="~alpha ~amd64 ~arm ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~s390 ~sh ~sparc ~sparc-fbsd ~x86 ~x86-fbsd"
 +
</source>
  
Only a handful of applications leverage the more sophisticated functionality available in <tt>multilib.eclass</tt>, and Gentoo Linux currently uses binary bundles of 32-bit libraries to provide support for 32-bit applications on 64-bit multilib systems, rather than using Portage functionality to build these components from source. One possible explanation for this approach is that Portage currently does not allow applications to be slotted on ABI -- that is, a 32-bit and 64-bit version of sys-libs/zlib cannot co-exist in the Portage /var/db/pkg database, even if they do not overwrite one another on the filesystem when installed. There may be other possible reasons why building 32-bit packages from source remains unfeasible in Gentoo Linux, and will be documented here as they are discovered.
+
For ebuilds in Funtoo Linux, the <tt>*</tt> form should be used when possible.
  
 
[[Category:Internals]]
 
[[Category:Internals]]
 
[[Category:Portage]]
 
[[Category:Portage]]

Revision as of 21:13, 28 January 2014

Introduction

Ebuild developers as well as users of Portage can control Portage behavior using a number of Portage variables. Also, when an ebuild executes, a number of variables are defined by ebuild.sh, the main ebuild script, so they are available for your ebuild. There are also variables that the ebuild writer can define within his or her ebuild to provide information about the ebuild as well as control behavior. Information on Ebuild Functions, which are used to define actions that are performed during various parts of a package's lifecycle, is also available on this wiki.

Note

{{{1}}}

An ebuild is a textual meta-description of a software package (stored in a filename suffixed by .ebuild and generally located in a subdirectory of /usr/portage) that provides the instructions to build and install the later on your system plus a number of additional informations like a brief summary of the package, the required dependencies to build and run the package, where to get the software package source code and so on. Due to the 1:1 matching between an ebuild file and a software package most of Gentoo and Funtoo developers uses the term ebuild to designate the meta-description of a package and the software package it relates in itself.

Profile Variables

These variables are set in the profile(s) selected on the user's system. These profiles live inside /usr/portage/profiles.

ARCH
ARCH defines the name for the underlying system architecture. As of late December 2010, Gentoo Linux supports defines the following architectures in various system profiles:

alpha amd64 amd64-fbsd arm cobalt fulong-2e hppa hppa-hpux ia64 ia64-hpux ip22 ip27 ip28 ip30 ip32 ip32r10k m68k m68k-mint mips mips-irix mips64 mips64el mipsel ppc ppc-aix ppc-macos ppc-openbsd ppc64 ppc64-macos s390 sgi sh sparc sparc-fbsd sparc-solaris sparc64 sparc64-fbsd sparc64-solaris x64-macos x64-openbsd x64-solaris x86 x86-cygwin x86-fbsd x86-interix x86-macos x86-netbsd x86-openbsd x86-solaris x86-winnt xbox yeeloong

This list was generated using the following command:

# cd /usr/portage/profiles
# grep -r ARCH= * | cut -f2 -d"=" | sed -e 's/"//g' | sort -u 

Path Variables

PORTDIR
PORTDIR will be set to the path of the Portage directory that contains the ebuild that is currently executing, such as /usr/portage.
PORTAGE_TMPDIR
PORTAGE_TMPDIR defines the path to the location that Portage should use for all its temporary files, and defaults to /var/tmp.
DISTDIR
DISTDIR defines the path to the location of all distfiles (downloaded source code/artifacts), and defaults to /usr/portage/distfiles.
PKGDIR
PKGDIR defines the path to where Portage will store all built binary packages, and defaults to /usr/portage/packages.
RPMDIR
RPMDIR defines the path to where Portage will store all built binary RPM packages, and defaults to /usr/portage/rpm.
ROOT
ROOT defines the root of the filesystem to which packages should be installed, and may be set on the command-line. If not defined, Portage will set ROOT to / by the time your ebuild executes. When writing pkg_* ebuild functions, all your ebuild logic must respect the setting of the ROOT variable and compensate for situations when ROOT is not /. ROOT is used by stage1 builds to install to a sub-directory. ROOT=/tmp/stage1root emerge -e system is a command that might be run by a stage1 build. After src_install executes, Portage will always install the resultant files placed in $D to the filesystem defined by ROOT.

Prefix Variables

Portage supports the ability to act as a package manager for commercial operating systems such as MacOS X, or to install ebuilds on non-Gentoo systems, or to sub-directories on Gentoo or non-Gentoo systems. When used in this capacity, ebuilds are not installed to the root filesystem but are instead installed to a subdirectory, called a "prefix". Portage's prefix variables, available in EAPI 3, support this capability, and are designed to work with ebuilds that are maintained in a separate prefix overlay.

As part of the EAPI 3 prefix support, all ebuild helpers such as econf and einstall use $ED instead of $D. See below for full variable definitions.

EPREFIX
This variable is typically set in /etc/make.conf or make.globals, and defines the prefix that should be used by ebuilds. Prefix-aware ebuilds can reference this variable and use it appropriately. if EPREFIX is not defined, then EPREFIX will default to no value.
EROOT
EROOT is a more concise way of specifying $ROOT$EPREFIX, and is intended to be used in pkg_* ebuild functions.
ED
ED is a more concise way of specifying $D$EPREFIX, and is intended to be used in src_* ebuild functions.

For more information on Portage's prefix support, see the Gentoo Prefix Techdocs.

Path Variables For Your Use

WORKDIR
WORKDIR defines the temporary filesystem location that is used for extracting source code/artifacts, preparation, configuration and compilation, and will be defined for you by the time your ebuild executes, and its value must not be modified. By default, src_unpack will extract all source code/artifacts within WORKDIR. If you need to manually extract any archives, this must all be done somewhere within WORKDIR, T or D, with WORKDIR being the preferred location for doing this. WORKDIR is automatically cleaned up by Portage upon completion.
S
S defaults to $WORKDIR/$P, but may be redefined in your ebuild to be some other sub-directory of WORKDIR. Typically, S may be redefined to reflect the real directory name that is contained within the source tarball when it differs from the default of $WORKDIR/$P. When src_prepare, src_configure, src_compile, src_test and src_install run, they will attempt to set the current working directory to S if it exists, falling back to WORKDIR if S does not exist.
T
A temporary file storage location that is available to you during your ebuild's execution. T is automatically cleaned up by Portage upon completion.
D
D defines the filesystem tree to which the src_install function should install all files. All files defined here will be installed by Portage to the destination defined by ROOT.
FILESDIR
FILESDIR is shorthand for $PORTDIR/$CATEGORY/$PN/files -- the files/ sub-directory in the Portage tree for your particular ebuild. Typically used in src_prepare for applying patches, or by src_install for installing supplementary files such as initialization scripts that were committed to the Portage tree alongside your ebuild.

Metadata Variables

Metadata variables are variables that you set in your ebuild. They are cached by Portage so they can be quickly accessed for dependency resolution and searches -- in /var/cache/edb/dep. When an ebuild is updated, Portage automatically updates the cache the next time it notices the ebuild has changed.

EAPI
Periodically, the Gentoo Linux project defines new functionality and behavior related to how ebuilds are handled by Portage. These changes may require you to write your ebuilds slightly differently, or may allow you to take advantage of new capabilities in Portage. In your ebuild, you can specify the EAPI you are targeted by setting the EAPI variable as the first line in the ebuild. If no EAPI is specified, an EAPI of 0 ("classic" behavior) is assumed. To view a complete definition of EAPIs 1 through 3, please see The Gentoo Developer Guide's EAPI page. Note that the information on EAPI 4 is incomplete, and more detailed information can be found on in-progress EAPI 4 document maintained by Zac Medico. At some point, it may be possible to set an EAPI on a repository or overlay-wide basis, but for now, it is set by each individual ebuild.
DEPEND
DEPEND is used to specify an ebuild's build dependencies, and is a list of all ebuilds (and their corresponding versions/slots) that are required to be installed to a bare stage3 (or @system set + dependencies) in order for this package to build (compile, etc.). If one or more of these ebuilds are not installed, then it must cause the building of this package to fail; otherwise it is not a true build dependency. Do not list any dependencies for packages that are included in the underlying bare stage3 unless specific versions of the core packages (such as gcc, or glibc) are required, since these packages are expected to be available on all systems. All dependencies listed in DEPEND are satisfied prior to this package being built.
RDEPEND
RDEPEND is used to specify an ebuild's runtime dependencies, and is a list of all ebuilds (and their corresponding versions/slots) that are required to be installed to a bare stage3 (or @system set + dependencies) in order for this package to run (function). If one or more of these ebuilds are not installed, then it must cause the execution of this package to fail; otherwise it is not a true runtime dependency. Do not list any dependencies for packages that are included in the bare stage3 unless specific versions of the core packages (such as glibc) are required, since these packages are expected to be available on all systems. The dependencies listed in RDEPEND may or not be installed prior to this package being built.
DEPEND and RDEPEND
Note that if a dependency needs to be available both before the package is built, and also after the package is built, then the dependency must be listed in both DEPEND and RDEPEND, as it is both a build and runtime dependency. This is common with many packages, including virtually all shared libraries, which must be installed prior to compilation for headers and linking purposes but must continue to be available after the package is installed so that it can function properly.
(R)DEPEND if installed
It is often useful for an ebuild to conditionally depend on a specific version of another package, if it happens to be installed. Take sys-fs/lvm2 and sys-fs/udev, for example. sys-fs/lvm2 may not always be installed, but sys-fs/udev is a required ebuild. It would be nice if we could specify in the sys-fs/udev ebuild that a specific or higher version of lvm2 is required to work with this particular version of udev, or specify in the lvm2 ebuild that a specific version or higher of udev is required to work with this version of lvm2. While this is not currently possible in Portage, it is possible to use the blocker functionality in Portage to define that earlier versions are not compatible, which essentially accomplishes the same thing. To specify that another package should not be installed alongside your ebuild, use the double-exclamation from of a blocker: "!!<sys-fs/udev-160" might be an example. This will prevent both ebuilds from being installed on the system at the same time. The double-exclamation blocker is supported in EAPI 2 and above.
IUSE
IUSE specifies the USE variables that are recognized by this ebuild. Note that changing IUSE in existing ebuilds should be handled carefully, as if another ebuild depends on a particular USE variable in IUSE being enabled in your ebuild, and you remove it, then Portage will not be able to satisfy this dependency. Similarly, if another ebuild depends on a particular USE variable in IUSE being disabled in your ebuild, and you remove it, then Portage will no longer be able to satisfy this dependency either. For this reason, it can become difficult to remove USE variables from IUSE once other ebuilds explicitly depend upon them being enabled or disabled.
SRC_URI
SRC_URI contains a list of all remote files that are used by this ebuild during the unpack/prepare/compile/install phases. Starting with EAPI 2, it is possible to rename source tarballs, which comes in handy when pulling down tagged sources from GitHub, using the following trick. This approach also makes it quite easy to release source tarballs for ebuilds, as all you need to do is tag the release and then push the tags to GitHub with a git push tags command:
GITHUB_USER="foo"
SRC_URI="https://github.com/${GITHUB_USER}/${PN}/tarball/${PV} -> ${PN}-git-${PV}.tgz"
 
src_prepare() {
  cd "${WORKDIR}"/${GITHUB_USER}-${PN}-*
  S="$(pwd)"
}

KEYWORDS

KEYWORDS is a general keywording system for ebuilds (meta description of a software package), but is now used exclusively by the Gentoo architecture teams to define whether a particular package is marked as belonging to the stable or the current (testing in Gentoo terminology) branch on a given system architecture. Not all packages are tagged as belonging to stable/current on all architectures, some of them lacks of such tags and are considered as being masked on a particular architecture. This can happen for several reasons like:

  • The package makes no sense for the architecture (e.g. SILO sys-boot/silo which is a boot loader for SPARC machines).
  • The package points to a development repository (e.g. version numbered -9999 packages like dev-vcs/git-9999)
  • The package makes sense on a a given architecture but no one has tested it (yet)
  • The package has been pushed in the portage tree but remains to go in a intensive test cycle before being tagged as current then stable).

In a user's arch profile (see eselect profile list.) ACCEPT_KEYWORDS variable is defined which specifies what specific keywords should be unmasked for this system by default. On Funtoo Linux systems, ACCEPT_KEYWORDS is set to one of six values:

amd64
64-bit PC-compatible stable tree
~amd64
64-bit PC-compatible current tree
x86
32-bit PC-compatible stable tree
~x86
32-bit PC-compatible current tree
sparc
SPARC stable tree
~sparc
SPARC current tree

An ebuild uses the KEYWORDS variable to control what tree or trees the ebuild is part of, and will contain at most one setting for each system architecture. The KEYWORD settings are defined with the following meaning:

amd64
ebuild unmasked in 64-bit PC-compatible stable and current trees
~amd64
ebuild unmasked in 64-bit PC-compatible current tree only
-amd64
ebuild masked for all 64-bit PC-compatible trees
x86
ebuild unmasked in 32-bit PC-compatible stable and current trees
~x86
ebuild unmasked in 32-bit PC-compatible current tree only
-x86
ebuild masked for all 32-bit PC-compatible trees
sparc
ebuild unmasked in SPARC stable and current trees
~sparc
ebuild unmasked in SPARC current tree only
-sparc
ebuild masked for all sparc trees

Important

x86, amd64 or sparc setting in the ebuild's KEYWORDS will unmask the ebuild for both current and stable tree systems -- that is, any ebuild made available to stable is also made available to current.

Additional wildcard keywords are supported in ebuilds:

*
unmask for all trees. This variable can be modified by appending negative keywords: "* -ia64" means "all keywords except (~)ia64
-*
mask for all trees. This variable can be modified by appending positive keywords: "-* amd64 x86" means "no keywords except for x86 and amd64 stable trees
Gentoo Linux KEYWORDS Policies

Due to the exclusive use of KEYWORDS by the Gentoo Linux architecture teams, a number of unfortunate policy-related checks have been integrated into the Portage source code. One is banning the use of KEYWORDS="*" to enable KEYWORDS for all available architectures, since it is Gentoo Linux policy for each architecture team to independently verify an ebuild one architecture at a time - this rule currently applies to all ebuilds, including architecture-independent ebuilds. This means that virtually all ebuilds originating from Gentoo Linux will specify an exhaustive, explicit list of all architecture trees for which this package has been unmasked, which will look something like this:

KEYWORDS="~alpha ~amd64 ~arm ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~s390 ~sh ~sparc ~sparc-fbsd ~x86 ~x86-fbsd"

For ebuilds in Funtoo Linux, the * form should be used when possible.