summaryrefslogtreecommitdiff log msg author committer range
blob: 2ca30f2053222e61fdab71b4bfc5b937fb29d006 (plain)
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331  pre { line-height: 125%; } td.linenos pre { color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px; } span.linenos { color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px; } td.linenos pre.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } .highlight .hll { background-color: #ffffcc } .highlight .c { color: #888888 } /* Comment */ .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */ .highlight .k { color: #008800; font-weight: bold } /* Keyword */ .highlight .ch { color: #888888 } /* Comment.Hashbang */ .highlight .cm { color: #888888 } /* Comment.Multiline */ .highlight .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */ .highlight .cpf { color: #888888 } /* Comment.PreprocFile */ .highlight .c1 { color: #888888 } /* Comment.Single */ .highlight .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */ .highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */ .highlight .ge { font-style: italic } /* Generic.Emph */ .highlight .gr { color: #aa0000 } /* Generic.Error */ .highlight .gh { color: #333333 } /* Generic.Heading */ .highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */ .highlight .go { color: #888888 } /* Generic.Output */ .highlight .gp { color: #555555 } /* Generic.Prompt */ .highlight .gs { font-weight: bold } /* Generic.Strong */ .highlight .gu { color: #666666 } /* Generic.Subheading */ .highlight .gt { color: #aa0000 } /* Generic.Traceback */ .highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */ .highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */ .highlight .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */ .highlight .kp { color: #008800 } /* Keyword.Pseudo */ .highlight .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */ .highlight .kt { color: #888888; font-weight: bold } /* Keyword.Type */ .highlight .m { color: #0000DD; font-weight: bold } /* Literal.Number */ .highlight .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */ .highlight .na { color: #336699 } /* Name.Attribute */ .highlight .nb { color: #003388 } /* Name.Builtin */ .highlight .nc { color: #bb0066; font-weight: bold } /* Name.Class */ .highlight .no { color: #003366; font-weight: bold } /* Name.Constant */ .highlight .nd { color: #555555 } /* Name.Decorator */ .highlight .ne { color: #bb0066; font-weight: bold } /* Name.Exception */ .highlight .nf { color: #0066bb; font-weight: bold } /* Name.Function */ .highlight .nl { color: #336699; font-style: italic } /* Name.Label */ .highlight .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */ .highlight .py { color: #336699; font-weight: bold } /* Name.Property */ .highlight .nt { color: #bb0066; font-weight: bold } /* Name.Tag */ .highlight .nv { color: #336699 } /* Name.Variable */ .highlight .ow { color: #008800 } /* Operator.Word */ .highlight .w { color: #bbbbbb } /* Text.Whitespace */ .highlight .mb { color: #0000DD; font-weight: bold } /* Literal.Number.Bin */ .highlight .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */ .highlight .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */ .highlight .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */ .highlight .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */ .highlight .sa { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Affix */ .highlight .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */ .highlight .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */ .highlight .dl { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Delimiter */ .highlight .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */ .highlight .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */ .highlight .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */ .highlight .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */ .highlight .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */ .highlight .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */ .highlight .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */ .highlight .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */ .highlight .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */ .highlight .bp { color: #003388 } /* Name.Builtin.Pseudo */ .highlight .fm { color: #0066bb; font-weight: bold } /* Name.Function.Magic */ .highlight .vc { color: #336699 } /* Name.Variable.Class */ .highlight .vg { color: #dd7700 } /* Name.Variable.Global */ .highlight .vi { color: #3333bb } /* Name.Variable.Instance */ .highlight .vm { color: #336699 } /* Name.Variable.Magic */ .highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */\chapter{Ebuild-defined Variables} \label{ch:ebuild-vars} \note{This chapter describes variables that may or must be defined by ebuilds. For variables that are passed from the package manager to the ebuild, see section~\ref{sec:ebuild-env-vars}.} If any of these variables are set to invalid values, or if any of the mandatory variables are undefined, the package manager's behaviour is undefined; ideally, an error in one ebuild should not prevent operations upon other ebuilds or packages. \section{Metadata Invariance} \label{sec:metadata-invariance} All ebuild-defined variables discussed in this chapter must be defined independently of any system, profile or tree dependent data, and must not vary depending upon the ebuild phase. In particular, ebuild metadata can and will be generated on a different system from that upon which the ebuild will be used, and the ebuild must generate identical metadata every time it is used. Globally defined ebuild variables without a special meaning must similarly not rely upon variable data. \section{Mandatory Ebuild-defined Variables} \label{sec:mandatory-vars} All ebuilds must define at least the following variables: \begin{description} \item[DESCRIPTION] A short human-readable description of the package's purpose. May be defined by an eclass. Must not be empty. \item[SLOT] The package's slot. Must be a valid slot name, as per section~\ref{sec:slot-names}. May be defined by an eclass. Must not be empty. In EAPIs shown in table~\ref{tab:slot-deps-table} as supporting sub-slots, the \t{SLOT} variable may contain an optional sub-slot part that follows the regular slot and is delimited by a \t{/} character. The sub-slot must be a valid slot name, as per section~\ref{sec:slot-names}. The sub-slot is used to represent cases in which an upgrade to a new version of a package with a different sub-slot may require dependent packages to be rebuilt. When the sub-slot part is omitted from the \t{SLOT} definition, the package is considered to have an implicit sub-slot which is equal to the regular slot. \end{description} \section{Optional Ebuild-defined Variables} \label{sec:optional-vars} Ebuilds may define any of the following variables: \begin{description} \item[EAPI] The EAPI\@. See below in section~\ref{sec:eapi}. \item[HOMEPAGE] The URI or URIs for a package's homepage, including protocols. See section~\ref{sec:dependency-spec} for full syntax. \item[SRC_URI] A list of source URIs for the package. Valid protocols are \t{http://}, \t{https://}, \t{ftp://} and \t{mirror://} (see section~\ref{sec:thirdpartymirrors} for mirror behaviour). Fetch restricted packages may include URL parts consisting of just a filename. See section~\ref{sec:src-uri-behaviour} for description and section~\ref{sec:dependency-spec} for full syntax. \item[LICENSE] The package's license. Each text token must be a valid license name, as per section~\ref{sec:license-names}, and must correspond to a tree licenses/'' entry (see section~\ref{sec:licenses-dir}). See section~\ref{sec:dependency-spec} for full syntax. \item[KEYWORDS] A whitespace separated list of keywords for the ebuild. Each token must be a valid keyword name, as per section~\ref{sec:keyword-names}. See section~\ref{sec:keywords} for full syntax. \item[IUSE] The \t{USE} flags used by the ebuild. Any eclass that works with \t{USE} flags must also set \t{IUSE}, listing only the variables used by that eclass. The package manager is responsible for merging these values. See section~\ref{sec:use-iuse-handling} for discussion on which values must be listed in this variable. \featurelabel{iuse-defaults} In EAPIs shown in table~\ref{tab:iuse-defaults-table} as supporting \t{IUSE} defaults, any use flag name in \t{IUSE} may be prefixed by at most one of a plus or a minus sign. If such a prefix is present, the package manager may use it as a suggestion as to the default value of the use flag if no other configuration overrides it. \item[REQUIRED_USE] \featurelabel{required-use} Zero or more assertions that must be met by the configuration of \t{USE} flags to be valid for this ebuild. See section~\ref{sec:required-use} for description and section~\ref{sec:dependency-spec} for full syntax. Only in EAPIs listed in table~\ref{tab:optional-vars-table} as supporting \t{REQUIRED_USE}. \item[PROPERTIES] \featurelabel{properties} Zero or more properties for this package. See section~\ref{sec:properties} for value meanings and section~\ref{sec:dependency-spec} for full syntax. For EAPIs listed in table~\ref{tab:optional-vars-table} as having optional support, ebuilds must not rely upon the package manager recognising or understanding this variable in any way. \item[RESTRICT] Zero or more behaviour restrictions for this package. See section~\ref{sec:restrict} for value meanings and section~\ref{sec:dependency-spec} for full syntax. \item[DEPEND] See chapter~\ref{ch:dependencies}. \item[RDEPEND] See chapter~\ref{ch:dependencies}. For some EAPIs, \t{RDEPEND} has special behaviour for its value if unset and when used with an eclass. See section~\ref{sec:rdepend-depend} for details. \item[PDEPEND] See chapter~\ref{ch:dependencies}. \item[BDEPEND] See chapter~\ref{ch:dependencies}. \end{description} \ChangeWhenAddingAnEAPI{7} \begin{centertable}{EAPIs supporting \t{IUSE} defaults} \label{tab:iuse-defaults-table} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Supports \t{IUSE} defaults?}} \\ \midrule 0 & No \\ 1, 2, 3, 4, 5, 6, 7 & Yes \\ \bottomrule \end{tabular} \end{centertable} \ChangeWhenAddingAnEAPI{7} \begin{centertable}{EAPIs supporting various ebuild-defined variables} \label{tab:optional-vars-table} \begin{tabular}{lll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Supports \t{PROPERTIES}?}} & \multicolumn{1}{c}{\textbf{Supports \t{REQUIRED_USE}?}} \\ \midrule 0, 1, 2, 3 & Optionally & No \\ 4, 5, 6, 7 & Yes & Yes \\ \bottomrule \end{tabular} \end{centertable} \subsection{EAPI} \label{sec:eapi} An empty or unset \t{EAPI} value is equivalent to \t{0}. Ebuilds must not assume that they will get a particular one of these two values if they are expecting one of these two values. The package manager must either pre-set the \t{EAPI} variable to \t{0} or ensure that it is unset before sourcing the ebuild for metadata generation. When using the ebuild for other purposes, the package manager must either pre-set \t{EAPI} to the value specified by the ebuild's metadata or ensure that it is unset. If any of these variables are set to invalid values, the package manager's behaviour is undefined; ideally, an error in one ebuild should not prevent operations upon other ebuilds or packages. If the EAPI is to be specified in an ebuild, the \t{EAPI} variable must be assigned to precisely once. The assignment must not be preceded by any lines other than blank lines or those that start with optional whitespace (spaces or tabs) followed by a \t{\#} character, and the line containing the assignment statement must match the following regular expression: \begin{verbatim} ^[ \t]*EAPI=(['"]?)([A-Za-z0-9+_.-]*)\1[ \t]*([ \t]#.*)?\$ \end{verbatim} The package manager must determine the EAPI of an ebuild by parsing its first non-blank and non-comment line, using the above regular expression. If it matches, the EAPI is the substring matched by the capturing parentheses (\t{0} if empty), otherwise it is \t{0}. For a recognised EAPI, the package manager must make sure that the \t{EAPI} value obtained by sourcing the ebuild with bash is identical to the EAPI obtained by parsing. The ebuild must be treated as invalid if these values are different. \subsection{SRC_URI} \label{sec:src-uri-behaviour} All filename components that are enabled (i.\,e.\ not inside a use-conditional block that is not matched) in \t{SRC_URI} must be available in the \t{DISTDIR} directory. In addition, these components are used to make the \t{A} and \t{AA} variables. If a component contains a full URI with protocol, that download location must be used. Package managers may also consult mirrors for their files. The special \t{mirror://} protocol must be supported. See section~\ref{sec:thirdpartymirrors} for mirror details. If a simple filename rather than a full URI is provided, the package manager can only use mirrors to download the file. The \t{RESTRICT} metadata key can be used to impose additional restrictions upon downloading---see section~\ref{sec:restrict} for details. \featurelabel{src-uri-arrows} In EAPIs listed in table~\ref{tab:uri-arrows-table} as supporting arrows, if an arrow is used, the filename used when saving to \t{DISTDIR} shall instead be the name on the right of the arrow. When consulting mirrors (except for those explicitly listed on the left of the arrow, if \t{mirror://} is used), the filename to the right of the arrow shall be requested instead of the filename in the URI. \ChangeWhenAddingAnEAPI{7} \begin{centertable}{EAPIs supporting \t{SRC_URI} arrows} \label{tab:uri-arrows-table} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Supports \t{SRC_URI} arrows?}} \\ \midrule 0, 1 & No \\ 2, 3, 4, 5, 6, 7 & Yes \\ \bottomrule \end{tabular} \end{centertable} \subsection{Keywords} \label{sec:keywords} Keywords are used to indicate levels of stability of a package on a respective architecture \t{arch}. The following conventions are used: \begin{compactitem} \item \t{arch}: Both the package version and the ebuild are widely tested, known to work and not have any serious issues on the indicated platform. This is referred to as a \i{stable keyword}. \item \t{\textasciitilde arch}: The package version and the ebuild are believed to work and do not have any known serious bugs, but more testing is required before the package version is considered suitable for obtaining a stable keyword. This is referred to as an \i{unstable keyword} or a \i{testing keyword}. \item No keyword: It is not known whether the package will work, or insufficient testing has occurred. \item \t{-arch}: The package version will not work on the architecture. \end{compactitem} The \t{-*} keyword is used to indicate package versions which are not worth trying to test on unlisted architectures. An empty \t{KEYWORDS} variable indicates uncertain functionality on any architecture. \subsection{USE state constraints} \label{sec:required-use} \t{REQUIRED_USE} contains a list of assertions that must be met by the configuration of \t{USE} flags to be valid for this ebuild. In order to be matched, a \t{USE} flag in a terminal element must be enabled (or disabled if it has an exclamation mark prefix). If the package manager encounters a package version where \t{REQUIRED_USE} assertions are not met, it must treat this package version as if it was masked. No phase functions must be called. It is an error for a flag to be used if it is not included in \t{IUSE_EFFECTIVE}. \subsection{Properties} \label{sec:properties} The following tokens are permitted inside \t{PROPERTIES}: \begin{description} \item[interactive] The package may require interaction with the user via the tty. \end{description} Ebuilds may not rely upon any token being supported. \subsection{Restrict} \label{sec:restrict} The following tokens are permitted inside \t{RESTRICT}: \begin{description} \item[mirror] The package's \t{SRC_URI} entries may not be mirrored, and mirrors should not be checked when fetching. \item[fetch] The package's \t{SRC_URI} entries may not be downloaded automatically. If entries are not available, \t{pkg_nofetch} is called. Implies \t{mirror}. \item[strip] No stripping of debug symbols from files to be installed may be performed. In EAPIs listed in table~\ref{tab:staging-area-commands} as supporting controllable stripping, this behaviour may be altered by the \t{dostrip} command. \item[userpriv] The package manager may not drop root privileges when building the package. \item[test] The \t{src_test} phase must not be run. \end{description} Package managers may recognise other tokens, but ebuilds may not rely upon them being supported. \subsection{RDEPEND value} \label{sec:rdepend-depend} \featurelabel{rdepend-depend} In EAPIs listed in table~\ref{tab:rdepend-depend-table} as having \t{RDEPEND=DEPEND}, if \t{RDEPEND} is unset (but not if it is set to an empty string) in an ebuild, when generating metadata the package manager must treat its value as being equal to the value of \t{DEPEND}. When dealing with eclasses, only values set in the ebuild itself are considered for this behaviour; any \t{DEPEND} or \t{RDEPEND} set in an eclass does not change the implicit \t{RDEPEND=DEPEND} for the ebuild portion, and any \t{DEPEND} value set in an eclass does not get treated as being part of \t{RDEPEND}. \ChangeWhenAddingAnEAPI{7} \begin{centertable}{EAPIs with \t{RDEPEND=DEPEND} default} \label{tab:rdepend-depend-table} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{\t{RDEPEND=DEPEND}?}} \\ \midrule 0, 1, 2, 3 & Yes \\ 4, 5, 6, 7 & No \\ \bottomrule \end{tabular} \end{centertable} \section{Magic Ebuild-defined Variables} The following variables must be defined by \t{inherit} (see section~\ref{sec:inherit}), and may be considered to be part of the ebuild's metadata: \begin{description} \item[ECLASS] The current eclass, or unset if there is no current eclass. This is handled magically by \t{inherit} and must not be modified manually. \item[INHERITED] List of inherited eclass names. Again, this is handled magically by \t{inherit}. \end{description} \note{Thus, by extension of section~\ref{sec:metadata-invariance}, \t{inherit} may not be used conditionally, except upon constant conditions.} The following are special variables defined by the package manager for internal use and may or may not be exported to the ebuild environment: \begin{description} \item[DEFINED_PHASES] \featurelabel{defined-phases} A space separated arbitrarily ordered list of phase names (e.\,g.\ \t{configure setup unpack}) whose phase functions are defined by the ebuild or an eclass inherited by the ebuild. If no phase functions are defined, a single hyphen is used instead of an empty string. For EAPIs listed in table~\ref{tab:defined-phases-table} as having optional \t{DEFINED_PHASES} support, package managers may not rely upon the metadata cache having this variable defined, and must treat an empty string as this information is not available''. \end{description} \note{Thus, by extension of section~\ref{sec:metadata-invariance}, phase functions must not be defined based upon any variant condition.} \ChangeWhenAddingAnEAPI{7} \begin{centertable}{EAPIs supporting \t{DEFINED_PHASES}} \label{tab:defined-phases-table} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Supports \t{DEFINED_PHASES}?}} \\ \midrule 0, 1, 2, 3 & Optionally \\ 4, 5, 6, 7 & Yes \\ \bottomrule \end{tabular} \end{centertable} % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en : %%% Local Variables: %%% mode: latex %%% TeX-master: "pms" %%% LaTeX-indent-level: 4 %%% LaTeX-item-indent: 0 %%% TeX-brace-indent-level: 4 %%% fill-column: 100 %%% End: