doc/package/ebuild/eapi/4.docbook

   1 <section id='package-ebuild-eapi-4_pre1'>
   2 <title>EAPI 4_pre1</title>
   3 <section id='package-ebuild-eapi-4_pre1-helpers'>
   4 <title>Helpers</title>
   5 <section id='package-ebuild-eapi-4_pre1-helpers-removed-dohard-dosed'>
   6 <title>Removed dohard and dosed</title>
   7 <para>
   8 The dohard and dosed helpers from previous EAPIs are no longer available.
   9 </para>
  10 </section>
  11 <section id='package-ebuild-eapi-4_pre1-helpers-dodoc-r'>
  12 <title>dodoc -r</title>
  13 <para>
  14 The dodoc helper now has a -r option which enables recursion.
  15 </para>
  16 </section>
  17 <section id='package-ebuild-eapi-4_pre1-helpers-doins-newins-symlinks'>
  18 <title>doins and newins preserve symlinks</title>
  19 <para>
  20 The doins and newins helpers now preserve symlinks. In earlier EAPIs
  21 symlinks are dereferenced rather than preserved.
  22 </para>
  23 </section>
  24 <section id='package-ebuild-eapi-4_pre1-helpers-econf-disable-dependency-tracking'>
  25 <title>econf adds --disable-dependency-tracking</title>
  26 <para>
  27 The econf helper now adds --disable-dependency-tracking to the
  28 configure arguments.
  29 </para>
  30 </section>
  31 </section>
  32 <section id='package-ebuild-eapi-4_pre1-metadata'>
  33 <title>Metadata</title>
  34         <section id='package-ebuild-eapi-4_pre1-metadata-dependencies'>
  35         <title>Dependencies</title>
  36                 <section id='package-ebuild-eapi-4_pre1-metadata-dependencies-use-defaults'>
  37                 <title>USE Dependency Defaults</title>
  38                 <para>
  39                 In a 3-style use dependency, the flag name may immediately be followed by a
  40                 default specified by either (+) or (-). The former indicates that, when
  41                 applying the use dependency to a package that does not have the flag in
  42                 question in IUSE_REFERENCEABLE, the package manager shall behave as if the flag
  43                 were present and enabled; the latter, present and disabled.
  44                 </para>
  45                 <para>
  46                 Unless a 3-style default is specified, it is an error for a use dependency to
  47                 be applied to an ebuild which does not have the flag in question in
  48                 IUSE_REFERENCEABLE.
  49                 </para>
  50                 <para>
  51                 Note: By extension of the above, a default that could reference an ebuild using
  52                 an EAPI not supporting profile IUSE injections cannot rely upon any particular
  53                 behaviour for flags that would not have to be part of IUSE.
  54                 </para>
  55                 <para>
  56                 It is an error for an ebuild to use a conditional use dependency when that
  57                 ebuild does not have the flag in IUSE_EFFECTIVE.
  58                 </para>
  59                 </section>
  60         </section>
  61 <section id='package-ebuild-eapi-4_pre1-metadata-required-use'>
  62 <title>REQUIRED_USE</title>
  63 <para>
  64 This new REQUIRED_USE metadata key is used to specify what USE flag combinations are disallowed for a specific pkg.
  65 </para>
  66 <section id='package-ebuild-eapi-4_pre1-metadata-required-use-motivation'>
  67 <title>Motivation</title>
  68 <para>
  69 It's a semi common occurence that an ebuild may need to state that they disallow USE flags in specific combinations- either mysql or sqlite for example, but not both.
  70 </para>
  71 <para>
  72 Existing solutions rely on checking the the USE configuration in pkg_setup which is non-optimal due to pkg_setup being ran potentially hours after the initial emerge -p invocation.
  73 </para>
  74 <para>
  75 Current versions of EAPI4 support a phase hook pkg_pretend that is intended to move pre-build checks to just after resolution. It has been proposed that pkg_pretend should continue the tradition of adhoc shell code validating the USE state- this too is non optimal for the following reasons-
  76 </para>
  77 <orderedlist>
  78 <listitem>
  79 <para>
  80 The only way to find out if the USE state is disallowed is to run the code
  81 </para>
  82 </listitem>
  83 <listitem>
  84 <para>
  85 The common implementation of this can result in an iterative process where the user hits a USE constraint, fixs it, reruns the emerge invocation only to find that there is another constraint still violated for the ebuild, thus requiring them to fix it, rerun emerge, etc.
  86 </para>
  87 </listitem>
  88 <listitem>
  89 <para>
  90 For a package manager to classify the error, the only option it has is to try and parse adhoc output written by an ebuild dev. This effectively disallows package manager options for providing a more informative error message. A simple example would be if the package manager wanted to integrate in the flag descriptions from use.desc/use.local.desc; this would be effectively impossible.
  91 </para>
  92 </listitem>
  93 <listitem>
  94 <para>
  95 Fundamentally these constraints are data, yet they're being encoded as executable code- this effectively blocks the possibility of doing a wide variety of QA/tree scans. For example it blocks the possibility of sanely scanning for USE flag induced hard dependency cycles, because the tools in question cannot get that info out of adhoc shell code.
  96 More importantly if the manager cannot know what the allowed USE states are for the ebuild in question, this eliminates the possibility of ever sanely breaking dependency cycles caused by USE flags.
  97 </para>
  98 </listitem>
  99 </orderedlist>
 100 <para>
 101 Just as .sh scripts are considered a poor archival form due to their opaqueness, pkg_setup and pkg_pretend aren't a proper solution for this. pkg_pretend in particular makes the situation slightly worse due to ebuild devs being expected to convert their ebuilds to the pkg_pretend form when using EAPI4. In doing so they'll have to do work w/out the gains REQUIRED_USE provides and have to repeat the same conversion work when REQUIRED_USE lands in a later EAPI.
 102 </para>
 103 </section>
 104 <section id='package-ebuild-eapi-4_pre1-metadata-required-use-specification'>
 105 <title>Specification</title>
 106 <para>
 107 Essentially REQUIRED_USE is proposed to be an analog of DEPENDS style syntax- a list of assertions that must be met for this USE configuration to be valid for this ebuild. For example, to state "if build is set, python must be unset":
 108 </para>
 109 <para>
 110 REQUIRED_USE="build? ( !python )"
 111 </para>
 112 <para>
 113 To state "either mysql or sqlite must be set, but not both":
 114 </para>
 115 <para>
 116 REQUIRED_USE="mysql? ( !sqlite ) !mysql? ( sqlite )"
 117 </para>
 118 <para>
 119 Note that the mysql/sqlite relationship is that of an Exclusive OR (XOR). While an XOR can be formed from existing syntax, it's suggested that a specific operator be added for this case using ^^. Reformatting the "mysql or sqlite, but not both" with XOR results in:
 120 </para>
 121 <para>
 122 REQUIRED_USE="^^ ( mysql sqlite )"
 123 </para>
 124 <para>
 125 Like any block operator, this can be combined with other constraints. For example if the user has flipped on the client flag, one gui must be choosen:
 126 </para>
 127 <para>
 128 REQUIRED_USE="client? ( ^^ ( gtk qt motif ) )"
 129 </para>
 130 <para>
 131 If the pkg is implemented sanely and requires at least one gui, but can support multiple it would be:
 132 </para>
 133 <para>
 134 REQUIRED_USE="client? ( || ( gtk qt motif ) )"
 135 </para>
 136 <para>
 137 Because ARCH is integrated into the USE space, this also allows for specifying corner cases like "at least one gui must be specified, but on mips only one gui can be specified":
 138 </para>
 139 <para>
 140 REQUIRED_USE="client? ( !mips? ( || (  gtk qt motif ) ) mips? ( ^^ ( gtk qt motif ) ) )"
 141 </para>
 142 <para>
 143 Please note that the AND operator is of course supported- if to enable client you must choose at least one gui and enable the python bindings the syntax would be:
 144 </para>
 145 <para>
 146 REQUIRED_USE="client? ( python || ( gtk qt motif x11 ) )"</para>
 147 <para>
 148 Finally, please note that this new metadata key can be set by eclasses, and the inherit implementation should protect the eclass set value just the same as how eclass defined DEPEND is protected.
 149 </para>
 150 </section>
 151 </section>
 152 </section>
 153         <section id='package-ebuild-eapi-4_pre1-phases'>
 154                 <title>Phases</title>
 155                 <section id='package-ebuild-eapi-4_pre1-phases-pkg-pretend'>
 156                         <title>New pkg_pretend Phase Function</title>
 157                         <para>
 158                         The pkg_pretend function may be used to carry out sanity checks early on in the
 159                         install process. For example, if an ebuild requires a particular kernel
 160                         configuration, it may perform that check in pkg_pretend and call eerror and
 161                         then die with appropriate messages if the requirement is not met.
 162                         </para>
 163                         <para>
 164                         pkg_pretend is run separately from the main phase function sequence, and does
 165                         not participate in any kind of environment saving. There is no guarantee that
 166                         any of an ebuild's dependencies will be met at this stage, and no guarantee
 167                         that the system state will not have changed substantially before the next phase
 168                         is executed.
 169                         </para>
 170                         <para>
 171                         pkg_pretend must not write to the filesystem.
 172                         </para>
 173                 </section>
 174                 <section id='package-ebuild-eapi-4_pre1-phases-src-install'>
 175                         <title>Default src_install no longer a no-op</title>
 176                         <programlisting>
 177 src_install() {
 178         if [[ -f Makefile || -f GNUmakefile || -f makefile ]] ; then
 179                 emake DESTDIR="${D}" install
 180         fi
 181
 182         if [[ -z $DOCS ]] ; then
 183                 local d
 184                 for d in README* ChangeLog AUTHORS NEWS TODO CHANGES \
 185                                 THANKS BUGS FAQ CREDITS CHANGELOG ; do
 186                         [[ -s "${d}" ]] &amp;&amp; dodoc "${d}"
 187                 done
 188         elif [[ $(declare -p DOCS) == "declare -a "* ]] ; then
 189                 dodoc "${DOCS[@]}"
 190         else
 191                 dodoc ${DOCS}
 192         fi
 193 }
 194                         </programlisting>
 195                 </section>
 196         </section>
 197         <section id='package-ebuild-eapi-4_pre1-variables'>
 198                 <title>Variables</title>
 199                 <section id='package-ebuild-eapi-4_pre1-variables-aa-kv-removed'>
 200                         <title>AA and KV variables are no longer exported</title>
 201                         <para>
 202                         The AA and KV variables are no longer exported to the ebuild environment.
 203                         </para>
 204                 </section>
 205         </section>
 206 </section>