Difference between pages "Multiple ABI Support" and "Ebuild Functions"

(Difference between pages)
 
(Ebuild Functions)
 
Line 1: Line 1:
=== Summary ===
+
== Ebuild Functions ==
  
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.
+
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:
  
=== Core ABI Support ===
+
* <tt>pkg_setup</tt> - variable intialization and sanity checks
 +
* <tt>src_unpack</tt>
 +
* <tt>src_prepare</tt>
 +
* <tt>src_configure</tt>
 +
* <tt>src_compile</tt>
 +
* <tt>src_install</tt>
  
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.
+
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:
  
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.
+
* <tt>pkg_preinst</tt>
 +
* (files are merged)
 +
* <tt>pkg_postinst</tt>
  
==== Core ABI: econf() ====
+
=== src_* functions ===
  
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.
+
Ebuild functions starting with <tt>src_</tt> are all related to creating the ebuild or package from source code/artifacts, and are defined below:
  
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.
+
==== src_unpack ====
  
==== Core ABI: Gcc Wrapper ====
+
<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:
  
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.
+
<pre>
 +
src_unpack() {
 +
  unpack ${A}
 +
}
 +
</pre>
  
==== Core ABI: Working Together ====
+
==== src_prepare ====
  
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>.)
+
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>.
  
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.
+
==== src_configure ====
  
==== Core ABI: Demonstration ====
+
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:
  
To test the multiple ABI functionality on an amd64 multilib system, you can execute the following command:
+
<pre>
 +
src_configure() {
 +
if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then
 +
econf
 +
fi
 +
}
 +
</pre>
 +
 
 +
==== src_compile ====
 +
 
 +
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:
  
 
<pre>
 
<pre>
# ABI="x86" emerge --buildpkgonly sys-libs/zlib
+
src_compile() {
 +
if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ] ; then
 +
emake || die "emake failed"
 +
fi
 +
}
 
</pre>
 
</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:
+
==== src_test ====
 +
 
 +
<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.  
 +
 
 +
==== src_install ====
 +
 
 +
<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>:
  
 
<pre>
 
<pre>
ninja1 lib32 # file libz.so.1.2.5
+
src_install() {
libz.so.1.2.5: ELF 32-bit LSB shared object, Intel 80386, version 1 (SYSV), dynamically linked, stripped
+
  make DESTDIR="$D" install
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>
 
</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.
+
=== pkg_* functions ===
  
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.
+
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>.
  
=== Extended ABI Support ===
+
==== pkg_setup ====
  
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>.
+
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.
  
==== ABI Profile Variables ====
+
==== pkg_pretend ====
  
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.
+
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.
+
; 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
+
==== pkg_preinst ====
: Defines the name of the default ABI for which packages should be built.
+
  
; MULTILIB_ABIS
+
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.
: 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>
+
  
==== ABI-Specific Profile Variables ====
+
==== pkg_postinst ====
  
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.
+
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.
  
; LIBDIR_*
+
==== pkg_prerm ====
  
; CHOST_*
+
The <tt>pkg_prerm</tt> function is called by Portage before an ebuild is removed from the filesystem.
  
; CDEFINE_*
+
==== pkg_postrm ====
  
; CFLAGS_*
+
The <tt>pkg_postrm</tt> function is called by Portage after an ebuild is removed from the filesystem.
: Note: this variable is used by the gcc wrapper when ABI is defined in the environment.
+
  
; LDFLAGS_*
+
==== pkg_config ====
  
; ASFLAGS_*
+
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.
  
==== multilib.eclass ====
+
=== Extra pre_ and post_ functions ===
  
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.
+
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.
  
; has_multilib_profile()
+
=== Helper Functions ===
: This is a boolean function that returns 0 (true) if multiple ABIs are defined in the MULTILIB_ABIS variable; otherwise 1 (false).
+
  
; get_libdir()
+
==== econf() ====
: 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>.
+
  
; get_modname()
+
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.
: 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].
+
  
; get_libname()
+
===== Automatically set prefix =====
: 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.
+
  
; multilib_env()
+
<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.
: 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()
+
===== Automatically set libdir =====
: 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>:
+
  
<pre>
+
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>.
src_configure() {
+
 
  use amd64 && multilib_toolchain_setup x86
+
===== Automatically set CHOST and CTARGET =====
  # we're now building a 32-bit app on a 64-bit system, whee!
+
 
  econf
+
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.
}
+
 
</pre>
+
===== Disable Dependency Tracking (EAPI 4) =====
 +
 
 +
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.
 +
 
 +
===== List of arguments =====
  
=== ABI Support Limitations ===
+
The following arguments are passed to <tt>configure</tt> and are all overrideable by the user by passing similar options to <tt>econf()</tt>:
  
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.
+
* <tt>--prefix=/usr</tt>
 +
* <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]]
[[Category:Official Documentation]]
 

Revision as of 01:54, 5 April 2013

Ebuild Functions

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:

  • pkg_setup - variable intialization and sanity checks
  • src_unpack
  • src_prepare
  • src_configure
  • src_compile
  • src_install

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 /usr, etc. At this point, the following functions are executed:

  • pkg_preinst
  • (files are merged)
  • pkg_postinst

src_* functions

Ebuild functions starting with src_ are all related to creating the ebuild or package from source code/artifacts, and are defined below:

src_unpack

src_unpack is intended to be used to unpack the source code/artifacts that will be used by the other src_* 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 src_prepare function should be used for this instead. When src_unpack starts, the current working directory is set to $WORKDIR, which is the directory within which all source code/artifacts should be expanded. Note that the variable $A is set to the names of all the unique source files/artifacts specified in SRC_URI, and they will all be available in $DISTDIR by the time src_unpack starts. Also note that if no src_unpack function is specified, ebuild.sh will execute the following function for src_unpack by default:

src_unpack() {
  unpack ${A}
}

src_prepare

EAPI 2 and above support the src_prepare function, which is intended to be used for applying patches or making other modifications to the source code. When src_prepare starts, the current working directory is set to $S.

src_configure

EAPI 2 and above support the src_configure function, which is used to configure the source code prior to compilation. With EAPI 2 and above, the following default src_configure is defined if none is specified:

src_configure() {
	if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then
		econf
	fi
}

src_compile

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 src_configure function must be used for configuration steps instead of bundling them inside src_compile. In addition, starting with EAPI 2, there is now a default src_compile function that will be executed if none is defined in the ebuild:

src_compile() {
	if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ] ; then
		emake || die "emake failed"
	fi
}

src_test

src_test is an interesting function - by default, an end-user's Portage does not have tests enabled. But if a user has test in FEATURES, or EBUILD_FORCE_TEST is defined, then ebuild.sh will attempt to run a test suite for this ebuild, by executing make check or make test if these targets are defined in the Makefile; otherwise, no tests will execute. If your Makefile supports make check or make test but the test suite is broken, then specify RESTRICT="test" in your ebuild to disable the test suite.

src_install

src_install is used by the ebuild writer to install all to-be-installed files to the $D directory, which can be treated like an empty root filesystem, in that ${D}/usr is the equivalent of the /usr directory, etc. When src_install runs, the Portage sandbox will be enabled, which will prevent any processes from creating or modifying files outside of the ${D} filesystem tree, and a sandbox violation will occur (resulting in the termination of the ebuild) if any such sandbox violation should occur. Once src_install has perfomed all necessary steps to install all to-be-installed files to $D, Portage will take care of merging these files to the filesystem specified by the $ROOT environment variable, which defaults to / if not set. When Portage merges these files, it will also record information about the installed package to /var/db/pkg/(cat)/$P. Typically, a src_install function such as this is sufficient for ensuring that all to-be-installed files are installed to $D:

src_install() {
  make DESTDIR="$D" install
}

pkg_* functions

An ebuild's functions starting with pkg_* 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 $ROOT 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 pkg_* functions must function properly even if $ROOT is something other than /.

pkg_setup

The pkg_setup function is unusual in that it runs prior to any src_* function, and also runs prior to any other pkg_* 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 pkg_setup 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 pkg_preinst and pkg_postinst for this purpose.

pkg_pretend

The pkg_pretend 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 emerge --pretend that a merge will fail. While this is useful, extending the dependency engine using bash is a very low-performance means to perform these tests. Therefore, The Funtoo core team recommends against using pkg_pretend. An extensible dependency engine would be a more appropriate and high-performance way to provide identical functionality.

pkg_preinst

The pkg_preinst function is called by Portage, prior to merging the to-be-installed files to the target filesystem specified by $ROOT environment variable (which defaults to /.) Keep in mind that these to-be-installed files were either just compiled and installed to $D by src_install, or they were just extracted from a .tbz2 binary package. The pkg_preinst 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 die from this function will cause the package to not be installed to the target filesystem.

pkg_postinst

The pkg_postinst function is called by Portage prior to the package being installed to the target filesystem specified by $ROOT. 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.

pkg_prerm

The pkg_prerm function is called by Portage before an ebuild is removed from the filesystem.

pkg_postrm

The pkg_postrm function is called by Portage after an ebuild is removed from the filesystem.

pkg_config

The pkg_config function is called by Portage when the user calls emerge --config for the ebuild. The current directory will be set to the current directory of the shell from where emerge --config is run.

Extra pre_ and post_ functions

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, post_src_configure will be executed after src_configure and before src_compile. 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.

Helper Functions

econf()

econf() is part of ebuild.sh and is intended to be a wrapper to the configure command that is typically used in the src_configure() stage. It has a number of behaviors that are important for ebuild writers to understand. Once you understand what econf() does, you are free to use it in your ebuilds. Note that the behavior of econf() is generally safe for most autoconf-based source archives, but in some cases it may be necessary to avoid using econf() to avoid some of its default behaviors.

Automatically set prefix

--prefix=/usr will be passed to configure automatically, unless a --prefix argument was specified to econf(), in which case, that --prefix setting will be used instead.

Automatically set libdir

If the ABI variable is set (typically done in the profile), then econf() will look for a variable named LIBDIR_$ABI (ie. LIBDIR_amd64). If this variable is set, the value of this variable will be used to set libdir to the value of {prefix}/LIBDIR_$ABI.

Automatically set CHOST and CTARGET

The --host=$CHOST argument will be passed to configure. $CHOST is defined in the system profile. In addition, the --target=$CTARGET argument will be passed to configure if $CTARGET 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.

Disable Dependency Tracking (EAPI 4)

In EAPI 4, the --disable-dependency-tracking argument will be passed to configure in order to optimize the performance of the configuration process. This option should have no impact other than on the performance of the configure script.

List of arguments

The following arguments are passed to configure and are all overrideable by the user by passing similar options to econf():

  • --prefix=/usr
  • --libdir={prefix}/LIBDIR_$ABI
  • --host=${CHOST}
  • if CTARGET is defined, then --target=${CTARGET}
  • --mandir=/usr/share/man
  • --infodir=/usr/share/info
  • --datadir=/usr/share
  • --sysconfdir=/etc
  • --localstatedir=/var/lib
  • if EAPI 4+, then --disable-dependency-tracking