summaryrefslogtreecommitdiff
blob: 10247a85865315a24770c5f4912811d6a30e8bf5 (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
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
\chapter{Ebuild-defined Functions}
\label{ch:ebuild-functions}

\section{List of Functions}

The following is a list of functions that an ebuild, or eclass, may define, and which will be called
by the package manager as part of the build and/or install process. In all cases the package manager
must provide a default implementation of these functions; unless otherwise stated this must be a
no-op. Most functions must assume only that they have write access to the package's working
directory (the \t{WORKDIR} environment variable; see section~\ref{sec:ebuild-env-vars}), and the
temporary directory \t{T}; exceptions are noted below. All functions may assume that they have read
access to all system libraries, binaries and configuration files that are accessible to normal
users.

The environment for functions run outside of the build sequence (that is, \t{pkg_config},
\t{pkg_info}, \t{pkg_prerm} and \t{pkg_postrm}) must be the environment used for the build of the
package, not the current configuration.

Ebuilds must not call nor assume the existence of any phase functions.

\subsection{Initial working directories}
\label{sec:s-to-workdir-fallback}

Some functions may assume that their initial working directory is set to a particular location;
these are noted below. If no initial working directory is mandated, it may be set to anything and
the ebuild must not rely upon a particular location for it. The ebuild \e{may} assume that the
initial working directory for any phase is a trusted location that may only be written to by a
privileged user and group.

\featurelabel{s-workdir-fallback} Some functions are described as having an initial working
directory of \t{S} with an error or fallback to \t{WORKDIR}\@. For EAPIs listed in
table~\ref{tab:s-fallback-table} as having the fallback, this means that if \t{S} is not a directory
before the start of the phase function, the initial working directory shall be \t{WORKDIR} instead.
For EAPIs where it is a conditional error, if \t{S} is not a directory before the start of the phase
function, it is a fatal error, unless all of the following conditions are true, in which case the
fallback to \t{WORKDIR} is used:

\begin{compactitem}
\item The \t{A} variable contains no items.
\item The phase function in question is not in \t{DEFINED_PHASES}.
\item None of the phase functions \t{unpack}, \t{prepare}, \t{configure}, \t{compile}, \t{test} or
    \t{install}, if supported by the EAPI in question and occurring prior to the phase about to be
    executed, are in \t{DEFINED_PHASES}.
\end{compactitem}

\ChangeWhenAddingAnEAPI{7}
\begin{centertable}{EAPIs with \t{S} to \t{WORKDIR} fallbacks}
    \label{tab:s-fallback-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Fallback to \t{WORKDIR} permitted?}} \\
      \midrule
      0, 1, 2, 3        & Always            \\
      4, 5, 6, 7        & Conditional error \\
      \bottomrule
    \end{tabular}
\end{centertable}

\subsection{pkg_pretend}

\featurelabel{pkg-pretend} The \t{pkg_pretend} function is only called for EAPIs listed in
table~\ref{tab:pkg-pretend-table} as supporting it.

The \t{pkg_pretend} function may be used to carry out sanity checks early on in the install
process. For example, if an ebuild requires a particular kernel configuration, it may perform that
check in \t{pkg_pretend} and call \t{eerror} and then \t{die} with appropriate messages if the
requirement is not met.

\t{pkg_pretend} is run separately from the main phase function sequence, and does not participate
in any kind of environment saving. There is no guarantee that any of an ebuild's dependencies will
be met at this stage, and no guarantee that the system state will not have changed substantially
before the next phase is executed.

\t{pkg_pretend} must not write to the filesystem.

\ChangeWhenAddingAnEAPI{7}
\begin{centertable}{EAPIs supporting \t{pkg_pretend}}
    \label{tab:pkg-pretend-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports \t{pkg_pretend}?}} \\
      \midrule
      0, 1, 2, 3        & No  \\
      4, 5, 6, 7        & Yes \\
      \bottomrule
    \end{tabular}
\end{centertable}

\subsection{pkg_setup}

The \t{pkg_setup} function sets up the ebuild's environment for all following functions, before
the build process starts. Further, it checks whether any necessary prerequisites not covered
by the package manager, e.\,g.\ that certain kernel configuration options are fulfilled.

\t{pkg_setup} must be run with full filesystem permissions, including the ability to add new users
and/or groups to the system.

\subsection{src_unpack}

The \t{src_unpack} function extracts all of the package's sources. In EAPIs lacking
\t{src_prepare}, it may also apply patches and set up the package's build system for further use.

The initial working directory must be \t{WORKDIR}, and the default implementation used when
the ebuild lacks the \t{src_unpack} function shall behave as:

\begin{listing}[H]
\caption{\t{src_unpack}}
\begin{verbatim}
src_unpack() {
    if [[ -n ${A} ]]; then
        unpack ${A}
    fi
}
\end{verbatim}
\end{listing}

\subsection{src_prepare}

\featurelabel{src-prepare} The \t{src_prepare} function is only called for EAPIs listed in
table~\ref{tab:src-prepare-table} as supporting it. The \t{src_prepare} function can be used for
post-unpack source preparation.

The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in
section~\ref{sec:s-to-workdir-fallback}.

\featurelabel{src-prepare-6} For EAPIs listed in table~\ref{tab:src-prepare-table} as using format
6, the default implementation used when the ebuild lacks the \t{src_prepare} function shall behave
as:

\begin{listing}[H]
\caption{\t{src_prepare}, format~6}
\begin{verbatim}
src_prepare() {
    if declare -p PATCHES | grep -q "^declare -a "; then
        [[ -n ${PATCHES[@]} ]] && eapply "${PATCHES[@]}"
    else
        [[ -n ${PATCHES} ]] && eapply ${PATCHES}
    fi
    eapply_user
}
\end{verbatim}
\end{listing}

For other EAPIs supporting \t{src_prepare}, the default implementation used when the ebuild lacks
the \t{src_prepare} function is a no-op.

\ChangeWhenAddingAnEAPI{7}
\begin{centertable}{\t{src_prepare} support and behaviour for EAPIs}
    \label{tab:src-prepare-table}
    \begin{tabular}{lll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports \t{src_prepare}?}} &
      \multicolumn{1}{c}{\textbf{Format}} \\
      \midrule
      0, 1              & No  & Not applicable \\
      2, 3, 4, 5        & Yes & no-op          \\
      6, 7              & Yes & 6              \\
      \bottomrule
    \end{tabular}
\end{centertable}

\subsection{src_configure}

\featurelabel{src-configure} The \t{src_configure} function is only called for EAPIs listed in
table~\ref{tab:src-configure-table} as supporting it.

The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in
section~\ref{sec:s-to-workdir-fallback}.

The \t{src_configure} function configures the package's build environment. The default
implementation used when the ebuild lacks the \t{src_configure} function shall behave as:

\begin{listing}[H]
\caption{\t{src_configure}}
\begin{verbatim}
src_configure() {
    if [[ -x ${ECONF_SOURCE:-.}/configure ]]; then
        econf
    fi
}
\end{verbatim}
\end{listing}

\ChangeWhenAddingAnEAPI{7}
\begin{centertable}{EAPIs supporting \t{src_configure}}
    \label{tab:src-configure-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports \t{src_configure}?}} \\
      \midrule
      0, 1              & No  \\
      2, 3, 4, 5, 6, 7  & Yes \\
      \bottomrule
    \end{tabular}
\end{centertable}

\subsection{src_compile}

\featurelabel{src-compile} The \t{src_compile} function configures the package's build environment
in EAPIs lacking \t{src_configure}, and builds the package in all EAPIs.

The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in
section~\ref{sec:s-to-workdir-fallback}.

\featurelabel{src-compile-0} For EAPIs listed in table~\ref{tab:src-compile-table} as using format
0, the default implementation used when the ebuild lacks the \t{src_compile} function shall behave
as:

\begin{listing}[H]
\caption{\t{src_compile}, format~0}
\begin{verbatim}
src_compile() {
    if [[ -x ./configure ]]; then
        econf
    fi
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then
        emake || die "emake failed"
    fi
}
\end{verbatim}
\end{listing}

\featurelabel{src-compile-1} For EAPIs listed in table~\ref{tab:src-compile-table} as using format
1, the default implementation used when the ebuild lacks the \t{src_compile} function shall behave
as:

\begin{listing}[H]
\caption{\t{src_compile}, format~1}
\begin{verbatim}
src_compile() {
    if [[ -x ${ECONF_SOURCE:-.}/configure ]]; then
        econf
    fi
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then
        emake || die "emake failed"
    fi
}
\end{verbatim}
\end{listing}

\featurelabel{src-compile-2} For EAPIs listed in table~\ref{tab:src-compile-table} as using format
2, the default implementation used when the ebuild lacks the \t{src_compile} function shall behave
as:

\begin{listing}[H]
\caption{\t{src_compile}, format~2}
\begin{verbatim}
src_compile() {
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then
        emake || die "emake failed"
    fi
}
\end{verbatim}
\end{listing}

\ChangeWhenAddingAnEAPI{7}
\begin{centertable}{\t{src_compile} behaviour for EAPIs}
    \label{tab:src-compile-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Format}} \\
      \midrule
      0                 & 0 \\
      1                 & 1 \\
      2, 3, 4, 5, 6, 7  & 2 \\
      \bottomrule
    \end{tabular}
\end{centertable}

\subsection{src_test}

The \t{src_test} function runs unit tests for the newly built but not yet installed package as
provided.

The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in
section~\ref{sec:s-to-workdir-fallback}.

The default implementation used when the ebuild lacks the \t{src_test} function must, if tests are
enabled, run \t{emake check} if and only if such a target is available, or if not run
\t{emake test} if and only if such a target is available. In both cases, if \t{emake} returns
non-zero the build must be aborted.

\featurelabel{parallel-tests} For EAPIs listed in table~\ref{tab:src-test-table} as not supporting
parallel tests, the \t{emake} command must be called with option \t{-j1}.

The \t{src_test} function may be disabled by \t{RESTRICT}\@. See section~\ref{sec:restrict}. It may
be disabled by user too, using a PM-specific mechanism.

\ChangeWhenAddingAnEAPI{7}
\begin{centertable}{\t{src_test} behaviour for EAPIs}
    \label{tab:src-test-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports parallel tests?}} \\
      \midrule
      0, 1, 2, 3, 4     & No  \\
      5, 6, 7           & Yes \\
      \bottomrule
    \end{tabular}
\end{centertable}

\subsection{src_install}

\featurelabel{src-install} The \t{src_install} function installs the package's content to a
directory specified in \t{D}.

The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in
section~\ref{sec:s-to-workdir-fallback}.

\featurelabel{src-install-4} For EAPIs listed in table~\ref{tab:src-install-table} as using format
4, the default implementation used when the ebuild lacks the \t{src_install} function shall behave
as:

\begin{listing}[H]
\caption{\t{src_install}, format~4}
\begin{verbatim}
src_install() {
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then
        emake DESTDIR="${D}" install
    fi

    if ! declare -p DOCS >/dev/null 2>&1 ; then
        local d
        for d in README* ChangeLog AUTHORS NEWS TODO CHANGES \
                THANKS BUGS FAQ CREDITS CHANGELOG ; do
            [[ -s "${d}" ]] && dodoc "${d}"
        done
    elif declare -p DOCS | grep -q "^declare -a " ; then
        dodoc "${DOCS[@]}"
    else
        dodoc ${DOCS}
    fi
}
\end{verbatim}
\end{listing}

\featurelabel{src-install-6} For EAPIs listed in table~\ref{tab:src-install-table} as using format
6, the default implementation used when the ebuild lacks the \t{src_install} function shall behave
as:

\begin{listing}[H]
\caption{\t{src_install}, format~6}
\begin{verbatim}
src_install() {
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then
        emake DESTDIR="${D}" install
    fi
    einstalldocs
}
\end{verbatim}
\end{listing}

For other EAPIs, the default implementation used when the ebuild lacks the \t{src_install} function
is a no-op.

\ChangeWhenAddingAnEAPI{7}
\begin{centertable}{\t{src_install} behaviour for EAPIs}
    \label{tab:src-install-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Format}} \\
      \midrule
      0, 1, 2, 3        & no-op \\
      4, 5              & 4     \\
      6, 7              & 6     \\
      \bottomrule
    \end{tabular}
\end{centertable}

\subsection{pkg_preinst}

The \t{pkg_preinst} function performs any special tasks that are required immediately before
merging the package to the live filesystem. It must not write outside of the directories specified
by the \t{ROOT} and \t{D} environment variables.

\t{pkg_preinst} must be run with full access to all files and directories below that specified by
the \t{ROOT} and \t{D} environment variables.

\subsection{pkg_postinst}

The \t{pkg_postinst} function performs any special tasks that are required immediately after
merging the package to the live filesystem. It must not write outside of the directory specified
in the \t{ROOT} environment variable.

\t{pkg_postinst}, like, \t{pkg_preinst}, must be run with full access to all files and directories
below that specified by the \t{ROOT} environment variable.

\subsection{pkg_prerm}

The \t{pkg_prerm} function performs any special tasks that are required immediately before
unmerging the package from the live filesystem. It must not write outside of the directory specified
by the \t{ROOT} environment variable.

\t{pkg_prerm} must be run with full access to all files and directories below that specified by
the \t{ROOT} environment variable.

\subsection{pkg_postrm}

The \t{pkg_postrm} function performs any special tasks that are required immediately after
unmerging the package from the live filesystem. It must not write outside of the directory specified
by the \t{ROOT} environment variable.

\t{pkg_postrm} must be run with full access to all files and directories below that specified by
the \t{ROOT} environment variable.

\subsection{pkg_config}

The \t{pkg_config} function performs any custom steps required to configure a package after it has been
fully installed. It is the only ebuild function which may be interactive and prompt for user input.

\t{pkg_config} must be run with full access to all files and directories inside of \t{ROOT}.

\subsection{pkg_info}

\featurelabel{pkg-info} The \t{pkg_info} function may be called by the package manager when
displaying information about an installed package. In EAPIs listed in table~\ref{tab:pkg-info-table}
as supporting \t{pkg_info} on non-installed packages, it may also be called by the package manager
when displaying information about a non-installed package. In this case, ebuild authors should note
that dependencies may not be installed.

\t{pkg_info} must not write to the filesystem.

\ChangeWhenAddingAnEAPI{7}
\begin{centertable}{EAPIs supporting \t{pkg_info} on non-installed packages}
    \label{tab:pkg-info-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports \t{pkg_info} on non-installed packages?}} \\
      \midrule
      0, 1, 2, 3        & No  \\
      4, 5, 6, 7        & Yes \\
      \bottomrule
    \end{tabular}
\end{centertable}

\subsection{pkg_nofetch}

The \t{pkg_nofetch} function is run when the fetch phase of an fetch-restricted ebuild is run, and
the relevant source files are not available. It should direct the user to download all relevant
source files from their respective locations, with notes concerning licensing if applicable.

\t{pkg_nofetch} must require no write access to any part of the filesystem.

\subsection{Default phase functions}
\label{sec:default-phase-funcs}

\featurelabel{default-phase-funcs} In EAPIs listed in
table~\ref{tab:default-phase-function-table} as supporting \t{default_} phase functions, a function
named \t{default_}(phase) that behaves as the default implementation for that EAPI shall be defined
when executing any ebuild phase listed in the table. Ebuilds must not call these functions except
when in the phase in question.

\ChangeWhenAddingAnEAPI{7}
\begin{centertable}{EAPIs supporting \t{default_} phase functions}
    \label{tab:default-phase-function-table}
    \begin{tabular}{l P{26em}}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports \t{default_} functions in phases}} \\
      \midrule
      0, 1              & None \\
      2, 3              & \t{pkg_nofetch}, \t{src_unpack}, \t{src_prepare}, \t{src_configure},
                          \t{src_compile}, \t{src_test} \\
      4, 5, 6, 7        & \t{pkg_nofetch}, \t{src_unpack}, \t{src_prepare}, \t{src_configure},
                          \t{src_compile}, \t{src_install}, \t{src_test} \\
      \bottomrule
    \end{tabular}
\end{centertable}

\section{Call Order}

The call order for installing a package is:

\begin{compactitem}
\item \t{pkg_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called
    outside of the normal call order process.
\item \t{pkg_setup}
\item \t{src_unpack}
\item \t{src_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table})
\item \t{src_configure} (only for EAPIs listed in table~\ref{tab:src-configure-table})
\item \t{src_compile}
\item \t{src_test} (except if \t{RESTRICT=test} or disabled by user)
\item \t{src_install}
\item \t{pkg_preinst}
\item \t{pkg_postinst}
\end{compactitem}

The call order for uninstalling a package is:

\begin{compactitem}
\item \t{pkg_prerm}
\item \t{pkg_postrm}
\end{compactitem}

The call order for upgrading, downgrading or reinstalling a package is:

\begin{compactitem}
\item \t{pkg_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called
    outside of the normal call order process.
\item \t{pkg_setup}
\item \t{src_unpack}
\item \t{src_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table})
\item \t{src_configure} (only for EAPIs listed in table~\ref{tab:src-configure-table})
\item \t{src_compile}
\item \t{src_test} (except if \t{RESTRICT=test})
\item \t{src_install}
\item \t{pkg_preinst}
\item \t{pkg_prerm} for the package being replaced
\item \t{pkg_postrm} for the package being replaced
\item \t{pkg_postinst}
\end{compactitem}

\note{When up- or downgrading a package in EAPI 0 or 1, the last four phase functions can
alternatively be called in the order \t{pkg_preinst}, \t{pkg_postinst}, \t{pkg_prerm},
\t{pkg_postrm}. This behaviour is deprecated.}

The \t{pkg_config}, \t{pkg_info} and \t{pkg_nofetch} functions are not called in a normal
sequence. The \t{pkg_pretend} function is called some unspecified time before a (possibly
hypothetical) normal sequence.

For installing binary packages, the \t{src} phases are not called.

When building binary packages that are not to be installed locally, the \t{pkg_preinst}
and \t{pkg_postinst} functions are not called.

% 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: