[gentoo-dev] RFC: DEFINED_PHASES magic metadata variable

[Ciaran McCreesh]

I'd like to propose a new metadata variable called DEFINED_PHASES. Like
INHERITED, it will be generated by the package manager rather than by a
combination of explicit ebuild and eclass variables.

The DEFINED_PHASES variable is for package manager use; it may or may
not be exported to the ebuild, and must not be used or set in any way by
ebuilds. The DEFINED_PHASES proposal has (almost -- see below) no
developer-visible effects, other than reserving a variable name.

The name DEFINED_PHASES is currently only for convenience, since the
metadata cache format uses fixed positions rather than a key=value
format, but this may change in the future. In flat metadata cache,
DEFINED_PHASES shall be line 17.

The DEFINED_PHASES variable will contain a space separated arbitrarily
ordered list of phase names. A phase name is listed in DEFINED_PHASES if
and only if the ebuild or an eclass used by that ebuild provides an
implementation of that phase's phase function. For example, the current
value for app-editors/vim-7.2.021 would be (possibly not in this order):

DEFINED_PHASES="setup unpack compile install test postinst postrm"

If an ebuild uses the defaults for every single phase, rather than
defining a blank DEFINED_PHASES, the package manager shall set it to the
string "-". This will let the package manager tell the difference
between "this metadata was generated by an old package manager" and
"this ebuild uses defaults for everything".

Support for DEFINED_PHASES shall be optionally retroactively added to
all existing EAPIs. Package managers are not required to generate it,
and package managers may not assume its existence. Future EAPIs may make
DEFINED_PHASES mandatory.

Having DEFINED_PHASES upfront is useful in a number of ways to the
package manager:

* It lets the package manager avoid having to run phases that have a "do
  nothing" default and that aren't defined by the ebuild. This is
  currently a fairly minor issue, but in the future if we start using
  src_fetch_extra (bug 249086) or pkg_pretend it makes quite a bit of
  difference.

* It lets the package manager parallelise pkg_* functions in many
  situations.

* It lets the package manager avoid having to go to 'interactive' mode
  for every phase of PROPERTIES=interactive ebuilds.

There is one subtle implication of this proposal: it means the phases
defined by an ebuild must now be metadata-invariant. So the following is
remains legal:

    if [[ ${EAPI} == 2 ]] ; then
        src_configure() {
            blah
        }
    fi

But this goes from being "probably illegal, but might work by fluke" to
"definitely illegal":

    if use foo ; then
        src_configure() {
            blah
        }
    fi

This is of course a good thing.

-- 
Ciaran McCreesh