doc/package/ebuild/phases.docbook

<section id='package-ebuild-phases'>
	<title>Ebuild Phases</title>
	<para>
	Ebuild execution is divided into a series of phases. In order
	to implement a phase, an ebuild defines a function to serve as
	an entry point for execution of that phase.
	This design is similar to the template method pattern that
	is commonly used in object oriented programming languages. An ebuild
	can inherit or override a template method from an eclass.
	</para>
	<para>
	The function names for the ebuild phases, listed in order of execution:
	</para>
	<itemizedlist>
	<listitem>
		<para>pkg_pretend</para>
	</listitem>
	<listitem>
		<para>pkg_setup</para>
	</listitem>
	<listitem>
		<para>src_unpack</para>
	</listitem>
	<listitem>
		<para>src_prepare</para>
	</listitem>
	<listitem>
		<para>src_configure</para>
	</listitem>
	<listitem>
		<para>src_compile</para>
	</listitem>
	<listitem>
		<para>src_test</para>
	</listitem>
	<listitem>
		<para>src_install</para>
	</listitem>
	<listitem>
		<para>pkg_preinst</para>
	</listitem>
	<listitem>
		<para>pkg_postinst</para>
	</listitem>
	<listitem>
		<para>pkg_prerm</para>
	</listitem>
	<listitem>
		<para>pkg_postrm</para>
	</listitem>
	</itemizedlist>
	<section id='package-ebuild-phases-previous-installed'>
	<title>Interaction with previous installed version</title>
	<para>
	The order for upgrade and downgrade operations changed in
	version 2.1.5, but the order for reinstall operations remained unchanged.
	</para>
	<section id='package-ebuild-phases-before-2.1.5'>
	<title>Upgrade/downgrade order used by versions less than 2.1.5 (deprecated)</title>
	<itemizedlist>
	<listitem>
		<para>pkg_preinst</para>
	</listitem>
	<listitem>
		<para>pkg_postinst</para>
	</listitem>
	<listitem>
		<para>pkg_prerm</para>
	</listitem>
	<listitem>
		<para>pkg_postrm</para>
	</listitem>
	</itemizedlist>
	</section>
	<section id='package-ebuild-phases-after-2.1.5'>
	<title>Upgrade/downgrade order starting with version 2.1.5</title>
	<para>
	The new order for upgrades and downgrades is identical to the order used
	for reinstall operations:
	</para>
	<itemizedlist>
	<listitem>
		<para>pkg_preinst</para>
	</listitem>
	<listitem>
		<para>pkg_prerm</para>
	</listitem>
	<listitem>
		<para>pkg_postrm</para>
	</listitem>
	<listitem>
		<para>pkg_postinst</para>
	</listitem>
	</itemizedlist>
	<para>
	Now that pkg_postinst is called after all other phases, it's not possible to
	call has_version in pkg_postinst to detect whether the current install
	operation is an upgrade or downgrade. If this information is needed during the
	pkg_postinst phase, do the has_version call in an earlier phase (such as
	pkg_preinst) and store the result in a global variable to be accessed by
	pkg_postinst when it is called.
	</para>
	</section>
	</section>
</section>