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
|
\chapter{Ebuild-defined Variables}
\label{ebuild-vars}
\note This section 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{ebuild-env-vars}.
\section{Metadata invariance}
\label{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}
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[HOMEPAGE] The URI or URIs for a package's homepage, including protocols. May be defined by an
eclass. See section~\ref{dependencies} for full syntax.
\item[IUSE] The \t{USE} flags used by the ebuild. Historically, \t{USE\_EXPAND} values and \t{ARCH}
were not included; package managers should support this for backwards compatibility reasons. Ebuilds
must list only flags used by the ebuild itself. 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.
In EAPIs shown in table~\ref{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[KEYWORDS] A whitespace separated list of keywords for the ebuild. Each token must be a
valid keyword name, as per section~\ref{keyword-names}. May include \t{-*}, which
indicates that the package will only work on explicitly listed archs. May include \t{-arch},
which indicates that the package will not work on the specified arch. May be empty, which
indicates uncertain functionality on any architecture. May be defined in an eclass.
\item[LICENSE] The package's license. Each text token must correspond to a tree ``licenses/'' entry
(see section~\ref{licenses-dir}). See section~\ref{dependencies} for full syntax.
May be defined by an eclass. \label{ebuild-var-LICENSE}
\item[SLOT] The package's slot. Must be a valid slot name, as per section~\ref{slot-names}. May
be defined by an eclass. Must not be empty.
\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{thirdpartymirrors} for mirror behaviour).
Fetch restricted packages may include URL parts consisting of just a filename. See
section~\ref{dependencies} for full syntax.
\end{description}
If any of these variables are undefined, or 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.
\begin{centertable}{EAPIs supporting \t{IUSE} defaults} \label{iuse-defaults-table}
\IFKDEBUILDELSE
{
\begin{tabular}{ l l }
\toprule
\multicolumn{1}{c}{\textbf{EAPI}} &
\multicolumn{1}{c}{\textbf{Supports \t{IUSE} defaults?}} \\
\midrule
\t{0} & No \\
\t{1} & Yes \\
\t{kdebuild-1} & Yes \\
\t{2} & Yes \\
\bottomrule
\end{tabular}
}
{
\begin{tabular}{ l l }
\toprule
\multicolumn{1}{c}{\textbf{EAPI}} &
\multicolumn{1}{c}{\textbf{Supports \t{IUSE} defaults?}} \\
\midrule
\t{0} & No \\
\t{1} & Yes \\
\t{2} & Yes \\
\bottomrule
\end{tabular}
}
\end{centertable}
\section{Optional Ebuild-defined Variables}
Ebuilds may define any of the following variables:
\begin{description}
\item[DEPEND] See section~\ref{dependencies}.
\item[EAPI] The EAPI. See below for defaults.
\item[PDEPEND] See section~\ref{dependencies}.
\IFKDEBUILDELSE
{
\item[PROVIDE] Zero or more qualified package names of any \e{old style}
virtuals provided by this package. See section~\ref{dependencies} for full syntax. In EAPIs
listed in table~\ref{provide-table} as not supporting \t{PROVIDE}, ebuilds must not set this
variable and the package manager must reject any ebuild that does so.
\label{ebuild-var-provide}
}{
\item[PROVIDE] Zero or more qualified package names of any \e{old style}
virtuals provided by this package. See section~\ref{dependencies} for full syntax.
\label{ebuild-var-provide}
}
\item[RDEPEND] See section~\ref{dependencies}. \t{RDEPEND} has special behaviour for its value if
unset and when used with an eclass. See section~\ref{rdepend-depend} for details.
\item[RESTRICT] Zero or more behaviour restrictions for this package. See section~\ref{restrict}
for value meanings and section~\ref{dependencies} for full syntax.
\item[S] The path to the temporary build directory, used by \t{src\_compile}, \t{src\_install}
etc. Defaults to \t{\$\{WORKDIR\}/\$\{P\}}.
\end{description}
\IFKDEBUILDELSE
{
\begin{centertable}{EAPIs supporting \t{PROVIDE}} \label{provide-table}
\begin{tabular}{ l l }
\toprule
\multicolumn{1}{c}{\textbf{EAPI}} &
\multicolumn{1}{c}{\textbf{Supports \t{PROVIDE}?}} \\
\midrule
\t{0} & Yes \\
\t{1} & Yes \\
\t{kdebuild-1} & No \\
\t{2} & Yes \\
\bottomrule
\end{tabular}
\end{centertable}
}{
}
\subsection{EAPI}
\label{pre-source-eapi}
An empty \t{EAPI} value is equal 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.
\IFKDEBUILDELSE
{
When sourcing an ebuild with file extension \t{kdebuild-1}, the package manager must pre-set the
\t{EAPI} variable to \t{kdebuild-1}; leaving it empty is not allowed. Ebuilds with this
extension must not modify the \t{EAPI} variable.
}{
}
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.
\section{\t{RDEPEND} value}
\label{rdepend-depend}
If \t{RDEPEND} is unset (but not if it is set to an empty string) in an ebuild, the package manager
must set its value to be 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 added to \t{RDEPEND}.
\section{Magic Ebuild-defined Variables}
The following variables must be defined by \t{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{metadata-invariance}, \t{inherit} may not be used
conditionally, except upon constant conditions.
% vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pms"
%%% End:
|
GitWeb