Difference between pages "Ebuild Functions" and "Portage Variables"

(Difference between pages)
(Ebuild Functions)
 
 
Line 1: Line 1:
== Ebuild Functions ==
+
== Introduction ==
  
Ebuilds provide the ability to define various shell functions that are used to specify various actions relating to building and installing a source or binary package on a user's system. When an ebuild is emerged, the following functions are called, in order:
+
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.
  
* <tt>pkg_setup</tt> - variable intialization and sanity checks
+
{{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.
* <tt>src_unpack</tt>
+
* <tt>src_prepare</tt>
+
* <tt>src_configure</tt>
+
* <tt>src_compile</tt>
+
* <tt>src_install</tt>
+
  
At this point, the files are ready to be "merged" into the live filesystem. This is when they are copied from the temporary build directory into <tt>/usr</tt>, etc. At this point, the following functions are executed:
+
=== Profile Variables ===
  
* <tt>pkg_preinst</tt>
+
These variables are set in the profile(s) selected on the user's system. These profiles live inside <tt>/usr/portage/profiles</tt>.
* (files are merged)
+
* <tt>pkg_postinst</tt>
+
  
=== src_* functions ===
+
; 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:
  
Ebuild functions starting with <tt>src_</tt> are all related to creating the ebuild or package from source code/artifacts, and are defined below:
+
<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>
  
==== src_unpack ====
+
This list was generated using the following command:
  
<tt>src_unpack</tt> is intended to be used to unpack the source code/artifacts that will be used by the other <tt>src_*</tt> functions. With EAPI 1 and earlier, it is also used for patching/modifying the source artifacts to prepare them for building, but with EAPI 2 or later the <tt>src_prepare</tt> function should be used for this instead. When <tt>src_unpack</tt> starts, the current working directory is set to <tt>$WORKDIR</tt>, which is the directory within which all source code/artifacts should be expanded. Note that the variable <tt>$A</tt> is set to the names of all the unique source files/artifacts specified in <tt>SRC_URI</tt>, and they will all be available in <tt>$DISTDIR</tt> by the time <tt>src_unpack</tt> starts. Also note that if no <tt>src_unpack</tt> function is specified, <tt>ebuild.sh</tt> will execute the following function for <tt>src_unpack</tt> by default:
+
<console>
 +
###i## cd /usr/portage/profiles
 +
###i## grep -r ARCH= * | cut -f2 -d"=" | sed -e 's/"//g' | sort -u
 +
</console>
  
<pre>
+
=== Path Variables ===
src_unpack() {
+
  unpack ${A}
+
}
+
</pre>
+
  
==== src_prepare ====
+
;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>.
  
EAPI 2 and above support the <tt>src_prepare</tt> function, which is intended to be used for applying patches or making other modifications to the source code. When <tt>src_prepare</tt> starts, the current working directory is set to <tt>$S</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>.
  
==== src_configure ====
+
;DISTDIR
 +
: DISTDIR defines the path to the location of all distfiles (downloaded source code/artifacts), and defaults to <tt>/usr/portage/distfiles</tt>.
  
EAPI 2 and above support the <tt>src_configure</tt> function, which is used to configure the source code prior to compilation. With EAPI 2 and above, the following default <tt>src_configure</tt> is defined if none is specified:
+
;PKGDIR
 +
: PKGDIR defines the path to where Portage will store all built binary packages, and defaults to <tt>/usr/portage/packages</tt>.
  
<pre>
+
;RPMDIR
src_configure() {
+
: RPMDIR defines the path to where Portage will store all built binary RPM packages, and defaults to <tt>/usr/portage/rpm</tt>.
if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then
+
econf
+
fi
+
}
+
</pre>
+
  
==== src_compile ====
+
;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 <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.
  
This function defines the steps necessary to compile source code. With EAPI 1 and earlier, this function is also used to configure the source code prior to compilation. However, starting with EAPI 2, the <tt>src_configure</tt> function must be used for configuration steps instead of bundling them inside <tt>src_compile</tt>. In addition, starting with EAPI 2, there is now a default <tt>src_compile</tt> function that will be executed if none is defined in the ebuild:
+
=== 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].
src_compile() {
+
if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ] ; then
+
emake || die "emake failed"
+
fi
+
}
+
</pre>
+
  
==== src_test ====
+
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.
  
<tt>src_test</tt> is an interesting function - by default, an end-user's Portage does not have tests enabled. But if a user has <tt>test</tt> in <tt>FEATURES</tt>, or <tt>EBUILD_FORCE_TEST</tt> is defined, then <tt>ebuild.sh</tt> will attempt to run a test suite for this ebuild, by executing <tt>make check</tt> or <tt>make test</tt> if these targets are defined in the Makefile; otherwise, no tests will execute. If your Makefile supports <tt>make check</tt> or <tt>make test</tt> but the test suite is broken, then specify <tt>RESTRICT="test"</tt> in your ebuild to disable the test suite.  
+
;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.
  
==== src_install ====
+
;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.
  
<tt>src_install</tt> is used by the ebuild writer to install all to-be-installed files to the <tt>$D</tt> directory, which can be treated like an empty root filesystem, in that <tt>${D}/usr</tt> is the equivalent of the <tt>/usr</tt> directory, etc. When <tt>src_install</tt> runs, the Portage sandbox will be enabled, which will prevent any processes from creating or modifying files outside of the <tt>${D}</tt> filesystem tree, and a sandbox violation will occur (resulting in the termination of the ebuild) if any such sandbox violation should occur. Once <tt>src_install</tt> has perfomed all necessary steps to install all to-be-installed files to <tt>$D</tt>, Portage will take care of merging these files to the filesystem specified by the <tt>$ROOT</tt> environment variable, which defaults to <tt>/</tt> if not set. When Portage merges these files, it will also record information about the installed package to <tt>/var/db/pkg/(cat)/$P</tt>. Typically, a <tt>src_install</tt> function such as this is sufficient for ensuring that all to-be-installed files are installed to <tt>$D</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.
  
<pre>
+
For more information on Portage's prefix support, see the [http://www.gentoo.org/proj/en/gentoo-alt/prefix/techdocs.xml Gentoo Prefix Techdocs].
src_install() {
+
  make DESTDIR="$D" install
+
}
+
</pre>
+
  
=== pkg_* functions ===
+
=== Path Variables For Your Use ===
  
An ebuild's functions starting with <tt>pkg_*</tt> take a wider view of the package lifecycle, and may be executed very early or very late in the build or package installation process. They are also all executed even if installing a Portage binary package, so are the intended place for defining any global configuration changes that are also required during binary package installation, such as user and group creation. When these functions are executed, the <tt>$ROOT</tt> variable will be defined to point to the target root filesystem to which the package is to be (or has been) installed. All logic inside <tt>pkg_*</tt> functions must function properly even if <tt>$ROOT</tt> is something other than <tt>/</tt>.
+
;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, <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.
  
==== pkg_setup ====
+
;S
 +
: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.
  
The <tt>pkg_setup</tt> function is unusual in that it runs prior to any <tt>src_*</tt> function, and also runs prior to any other <tt>pkg_*</tt> function that runs when a binary package is installed, so it provides a useful place for the ebuild writer to perform any sanity checks, global configuration changes to the system (such as user/group creation) or set any internal global variables that are used by the rest of the ebuild. Using this function for defining global variables that are needed in multiple other functions is a useful way of avoiding duplicate code. You should also look to <tt>pkg_setup</tt> as the ideal place to put any logic that would otherwise linger in the main body of the ebuild, which should be avoided at all costs as it will slow down dependency calculation by Portage. Also remember that Portage can build binary packages, and this function is a good place to execute any steps that are required to run both prior to building an ebuild, and prior to installing a package. Also consider using <tt>pkg_preinst</tt> and <tt>pkg_postinst</tt> for this purpose.
+
;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.
  
==== pkg_pretend ====
+
;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.
  
The <tt>pkg_pretend</tt> function was added with EAPI 3, and it's the opinion of Daniel Robbins that the use of this function should be avoided. This function is especially unusual in that it is intended to be run ''during dependency calculation'', and is intended to provide a polite mechanism to inform the user that a particular ebuild will fail due to a known incompatibility, typically a kernel incompatibility. That way, the user can know during <tt>emerge --pretend</tt> that a merge will fail. While this is useful, extending the dependency engine using <tt>bash</tt> is a very low-performance means to perform these tests. Therefore, The Funtoo core team recommends against using <tt>pkg_pretend</tt>. An extensible dependency engine would be a more appropriate and high-performance way to provide identical functionality.
+
;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.
  
==== pkg_preinst ====
+
=== Metadata Variables ===
  
The <tt>pkg_preinst</tt> function is called by Portage, prior to merging the to-be-installed files to the target filesystem specified by <tt>$ROOT</tt> environment variable (which defaults to <tt>/</tt>.) Keep in mind that these to-be-installed files were either just compiled and installed to <tt>$D</tt> by <tt>src_install</tt>, or they were just extracted from a <tt>.tbz2</tt> binary package. The <tt>pkg_preinst</tt> function provides an ideal place to perform any "just before install" actions, such as user and group creation or other necessary steps to ensure that the package merges successfully. It also provides a potential place to perform any sanity checks related to installing the package to the target filesystem. If any sanity checks fail, calling <tt>die</tt> from this function will cause the package to not be installed to the target filesystem.
+
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.
  
==== pkg_postinst ====
+
;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 [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.
  
The <tt>pkg_postinst</tt> function is called by Portage prior to the package being installed to the target filesystem specified by <tt>$ROOT</tt>. This is a good place to perform any post-install configuration actions as well as print any informational messages for the user's benefit related to the package that was just installed.
+
;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.
  
==== pkg_prerm ====
+
;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.
  
The <tt>pkg_prerm</tt> function is called by Portage before an ebuild is removed from the filesystem.
+
; 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.
  
==== pkg_postrm ====
+
; (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.
  
The <tt>pkg_postrm</tt> function is called by Portage after an ebuild is removed from the filesystem.
+
; 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.
  
==== pkg_config ====
+
; 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 <tt>git push tags</tt> command:
  
The <tt>pkg_config</tt> function is called by Portage when the user calls <tt>emerge --config</tt> for the ebuild. The current directory will be set to the current directory of the shell from where <tt>emerge --config</tt> is run.
+
<source lang="bash">
 +
GITHUB_USER="foo"
 +
SRC_URI="https://github.com/${GITHUB_USER}/${PN}/tarball/${PV} -> ${PN}-git-${PV}.tgz"
  
=== Extra pre_ and post_ functions ===
+
src_prepare() {
 
+
  cd "${WORKDIR}"/${GITHUB_USER}-${PN}-*
Modern versions of Portage also support functions identical to the above functions but with '''pre_''' and '''post_''' at the beginning of the function name. For example, <tt>post_src_configure</tt> will be executed after <tt>src_configure</tt> and before <tt>src_compile</tt>. These additional functions are supported by all EAPIs, provided that the parent function is supported by the EAPI in use. The initial current working directory should be identical to the initial current working directory of the parent function.
+
  S="$(pwd)"
 
+
}
=== Helper Functions ===
+
</source>
  
==== econf() ====
+
=== KEYWORDS ===
  
econf() is part of ebuild.sh and is intended to be a wrapper to the <tt>configure</tt> command that is typically used in the <tt>src_configure()</tt> stage. It has a number of behaviors that are important for ebuild writers to understand. Once you understand what <tt>econf()</tt> does, you are free to use it in your ebuilds. Note that the behavior of <tt>econf()</tt> is generally safe for most autoconf-based source archives, but in some cases it may be necessary to avoid using <tt>econf()</tt> to avoid some of its default behaviors.
+
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).
  
===== Automatically set prefix =====
+
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:
  
<tt>--prefix=/usr</tt> will be passed to <tt>configure</tt> automatically, unless a <tt>--prefix</tt> argument was specified to <tt>econf()</tt>, in which case, that <tt>--prefix</tt> setting will be used instead.
+
;<tt>amd64</tt>
 +
:64-bit PC-compatible stable tree
 +
;<tt>~amd64</tt>
 +
:64-bit PC-compatible current tree
 +
;<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
  
===== Automatically set libdir =====
+
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:
  
If the <tt>ABI</tt> variable is set (typically done in the profile), then <tt>econf()</tt> will look for a variable named <tt>LIBDIR_$ABI</tt> (ie. <tt>LIBDIR_amd64</tt>). If this variable is set, the value of this variable will be used to set <tt>libdir</tt> to the value of <tt>{prefix}/LIBDIR_$ABI</tt>.
+
;<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
  
===== Automatically set CHOST and CTARGET =====
+
{{ 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. }}
  
The <tt>--host=$CHOST</tt> argument will be passed to <tt>configure</tt>. <tt>$CHOST</tt> is defined in the system profile. In addition, the <tt>--target=$CTARGET</tt> argument will be passed to <tt>configure</tt> if <tt>$CTARGET</tt> is defined. This is not normally required but is done to make Portage more capable of cross-compiling the ebuild. However, this functionality is not a guarantee that your ebuild will successfully cross-compile, as other changes to the ebuild may be necessary.
+
Additional wildcard keywords are supported in ebuilds:
  
===== Disable Dependency Tracking (EAPI 4) =====
+
;<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
  
In EAPI 4, the <tt>--disable-dependency-tracking</tt> argument will be passed to <tt>configure</tt> in order to optimize the performance of the configuration process. This option should have no impact other than on the performance of the <tt>configure</tt> script.
+
===== Gentoo Linux KEYWORDS Policies =====
  
===== List of arguments =====
+
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:
  
The following arguments are passed to <tt>configure</tt> and are all overrideable by the user by passing similar options to <tt>econf()</tt>:
+
<source lang="bash">
 +
KEYWORDS="~alpha ~amd64 ~arm ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~s390 ~sh ~sparc ~sparc-fbsd ~x86 ~x86-fbsd"
 +
</source>
  
* <tt>--prefix=/usr</tt>
+
For ebuilds in Funtoo Linux, the <tt>*</tt> form should be used when possible.
* <tt>--libdir={prefix}/LIBDIR_$ABI</tt>
+
* <tt>--host=${CHOST}</tt>
+
* if CTARGET is defined, then <tt>--target=${CTARGET}</tt>
+
* <tt>--mandir=/usr/share/man</tt>
+
* <tt>--infodir=/usr/share/info</tt>
+
* <tt>--datadir=/usr/share</tt>
+
* <tt>--sysconfdir=/etc</tt>
+
* <tt>--localstatedir=/var/lib</tt>
+
* if EAPI 4+, then <tt>--disable-dependency-tracking</tt>
+
  
 
[[Category:Internals]]
 
[[Category:Internals]]
 
[[Category:Portage]]
 
[[Category:Portage]]

Revision as of 21:13, January 28, 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.