1 |
Here's v2.0.1 with suggestions from mjo applied. |
2 |
|
3 |
ReST: https://dev.gentoo.org/~mgorny/tmp/glep-0065.rst |
4 |
HTML: https://dev.gentoo.org/~mgorny/tmp/glep-0065.html |
5 |
|
6 |
--- |
7 |
GLEP: 65 |
8 |
Title: Post-install QA checks |
9 |
Author: Michał Górny <mgorny@g.o> |
10 |
Type: Standards Track |
11 |
Status: Draft |
12 |
Version: 2 |
13 |
Created: 2014-10-26 |
14 |
Last-Modified: 2017-10-17 |
15 |
Post-History: 2014-10-30, 2017-10-17 |
16 |
Content-Type: text/x-rst |
17 |
--- |
18 |
|
19 |
Abstract |
20 |
======== |
21 |
|
22 |
This GLEP provides two kinds of QA check: checks run on the installation image |
23 |
once ``src_install`` returns, and checks run on the live system once |
24 |
``pkg_postinst`` returns. The checks can be provided by the Package Manager, |
25 |
repositories, packages (installed system-wide) and the system administrator. |
26 |
The QA checks can inspect the installation image or live system, output |
27 |
and store both user- and machine-oriented QA warning logs, manipulate files |
28 |
and abort the install. |
29 |
|
30 |
|
31 |
Motivation |
32 |
========== |
33 |
|
34 |
The current Portage versions have two main QA check mechanisms: repoman |
35 |
and post-install QA checks. While repoman is usually considered more |
36 |
important, it has severe limitations. In particular, it is run on repository |
37 |
without executing the ebuild, therefore it is incapable of inspecting |
38 |
the installed files. This is where post-install QA checks become useful. |
39 |
|
40 |
Over time, many different QA checks have been added to Portage. That includes |
41 |
checks corresponding to generic Gentoo rules (like filesystem hierarchy, |
42 |
security requirements), checks enforcing Gentoo team policies, and checks |
43 |
enforcing correct eclass usage. Some of the checks depend on external tools |
44 |
being present. |
45 |
|
46 |
Keeping those checks directly in Portage sources has two major disadvantages: |
47 |
|
48 |
1. The checks can not be properly updated without Portage upgrade. |
49 |
In particular, a change in a QA check becomes fully effective when |
50 |
the relevant Portage version becomes stable and the user upgrades. |
51 |
There is no easy way to keep QA checks in sync with eclasses. |
52 |
|
53 |
2. Gentoo-specific checks are enforced for all repositories and derived |
54 |
distributions. Modifying the QA check list requires forking Portage. |
55 |
|
56 |
|
57 |
Specification |
58 |
============= |
59 |
|
60 |
QA check types |
61 |
-------------- |
62 |
|
63 |
There are two kinds of QA checks defined in this specification: |
64 |
|
65 |
1. Post-install QA checks (``install-qa-check.d``), |
66 |
|
67 |
2. Post-merge QA checks (``postinst-qa-check.d``). |
68 |
|
69 |
The post-install QA checks are are executed after the ``src_install`` ebuild |
70 |
phase finishes but before the binary package is built or the ``pkg_preinst`` |
71 |
phase is executed. They can use the same commands as are permitted |
72 |
in ``src_install``, and access the installation image ``${D}`` |
73 |
and the temporary directory ``${T}``. |
74 |
|
75 |
In case of severe QA issues, the checks are allowed to alter the contents of |
76 |
the installation image in order to sanitize them, or call the ``die`` function |
77 |
to abort the build. |
78 |
|
79 |
The post-merge QA checks are executed after the ``pkg_postinst`` ebuild phase |
80 |
finishes. They can use the same commands as are permitted in ``pkg_postinst``, |
81 |
and access the installed system location ``${ROOT}`` and the temporary |
82 |
directory ``${T}``. |
83 |
|
84 |
The checks are allowed to alter the contents of the filesystem to the same |
85 |
degree as ``pkg_postinst`` phase is. They must not call ``die``. |
86 |
|
87 |
QA check file format & locations |
88 |
-------------------------------- |
89 |
|
90 |
QA checks are stored as bash scripts. The checks are identified and ordered |
91 |
by file name. If files with same names are present in multiple locations, |
92 |
the file in location with the highest priority is used. |
93 |
|
94 |
The specification defines four sources of QA checks, listed in the order |
95 |
of increasing priority: |
96 |
|
97 |
1. internal checks included in the Package Manager, |
98 |
2. repository-specific QA checks, |
99 |
3. package-installed QA checks, |
100 |
4. sysadmin-defined QA checks. |
101 |
|
102 |
The internal checks are stored in Package Manager-specific location and should |
103 |
be installed along with the Package Manager. It is recommended that only |
104 |
generic checks are included in the Package Manager and not checks specific to |
105 |
Gentoo policies, packages or eclasses included in Gentoo. |
106 |
|
107 |
Repository-specific QA checks are included in ``metadata/install-qa-check.d`` |
108 |
and ``metadata/postinst-qa-check.d`` directories of a repository. |
109 |
For an ebuild in question, the repository containing it and its masters are |
110 |
traversed for QA checks, with priority decreasing with each inheritance level. |
111 |
|
112 |
The package-installed QA checks are located in ``/usr/lib/install-qa-check.d`` |
113 |
and ``/usr/lib/postinst-qa-check.d``, and are intended to be installed |
114 |
by packages. The sysadmin-defined QA checks are located |
115 |
in ``/usr/local/lib/install-qa-check.d`` |
116 |
and ``/usr/local/lib/postinst-qa-check.d``. |
117 |
|
118 |
QA check script format |
119 |
---------------------- |
120 |
|
121 |
QA checks are sourced as bash scripts by the Package Manager. QA scripts are |
122 |
run in an isolated subshell, and therefore can safely alter the environment |
123 |
and change the working directory. QA scripts must always end with a command |
124 |
terminating with a successful exit code. |
125 |
|
126 |
Aside from the standard PMS functions, two additional commands are provided: |
127 |
|
128 |
1. ``eqawarn`` to output QA warnings to user, |
129 |
2. ``eqatag`` to store machine-readable information about QA issues. |
130 |
|
131 |
Repository-defined QA checks are allowed to ``inherit`` eclasses from |
132 |
the repository providing the check or any of its masters. The same |
133 |
inheritance rules apply as to ebuilds in the particular repository. Sourced |
134 |
eclasses do not affect the final ebuild metadata or phase functions. |
135 |
|
136 |
Function specification |
137 |
---------------------- |
138 |
|
139 |
eqawarn |
140 |
~~~~~~~ |
141 |
Synopsis |
142 |
``eqawarn <message>...`` |
143 |
|
144 |
Output the specified message to the user as a QA warning, if the QA warning |
145 |
output is enabled. The message can contain escape sequences, and they will be |
146 |
interpreted according to the rules for ``echo -e`` bash built-in. |
147 |
|
148 |
The mechanism for enabling QA warning output and the specific output |
149 |
facilities are defined by the Package Manager. |
150 |
|
151 |
eqatag |
152 |
~~~~~~ |
153 |
Synopsis |
154 |
``eqatag [-v] <tag> [<key>=<value>...] [<file>...]`` |
155 |
|
156 |
Tag the package with specific QA issues. The *tag* parameter is |
157 |
a well-defined name identifying specific QA issue. The tag can be additionally |
158 |
associated with some data in key-value form and/or one or more *files*. |
159 |
The file paths are relative to the installation root (``${D}`` in post-install |
160 |
checks or ``${ROOT}`` in post-merge), and need to start with a leading slash. |
161 |
|
162 |
If ``-v`` (verbose) parameter is passed, the function will also output |
163 |
newline-delimited list of files using ``eqawarn``. This is intended |
164 |
as a short-hand for both storing machine-readable and outputting user-readable |
165 |
QA warnings. |
166 |
|
167 |
The mechanism used to store tags is defined by the Package Manager. The tag |
168 |
names are defined by the specific QA checks. However, it is recommended that |
169 |
tags are named hierarchically, with words being concatenated using a dot |
170 |
``.``, and that the first word matches QA check filename. For example, |
171 |
the tags used by ``60bash-completion`` check would be named |
172 |
``bash-completion.missing-alias`` and ``bash-completion.deprecated-have``. |
173 |
|
174 |
|
175 |
Rationale |
176 |
========= |
177 |
|
178 |
QA check types |
179 |
-------------- |
180 |
|
181 |
The two types of QA checks were created to account for different kinds |
182 |
of common mistakes in ebuilds. |
183 |
|
184 |
Post-install QA checks can be used to verify the installation image before |
185 |
it is merged to a live system or published as a binary package. They can |
186 |
account for various problems caused by the ebuild code up to and including |
187 |
``src_install``, the upstream code executed as part of any of those phases |
188 |
and the supplied files. |
189 |
|
190 |
Post-merge QA checks can be used to verify the state of system after |
191 |
the package is merged and its ``pkg_postinst`` phase is executed. They mostly |
192 |
aim to detect missing postinst actions but can do other live system integrity |
193 |
checks. |
194 |
|
195 |
QA check file format & locations |
196 |
-------------------------------- |
197 |
|
198 |
The multiple locations for QA checks aim to get the best coverage for various |
199 |
requirements. |
200 |
|
201 |
The checks installed along with the Package Manager are meant to cover |
202 |
the generic cases and other checks that rely on Package Manager internals. |
203 |
Unlike other categories of QA checks, those checks apply to a single Package |
204 |
Manager only and can therefore use internal API. However, it is recommended |
205 |
that this category is used scarcely. |
206 |
|
207 |
Storing checks in the repository allows developers to strictly bind them to |
208 |
a specific version of the distribution and update them along with the relevant |
209 |
policies and/or eclasses. In particular, rules enforced by Gentoo policies |
210 |
and eclasses don't have to apply to other distributions using Portage. |
211 |
|
212 |
The QA checks are applied to sub-repositories (via ``masters`` attribute) |
213 |
likewise eclasses. This makes sure that the majority of repositories don't |
214 |
lose QA checks. The QA checks related to eclasses are inherited the same way |
215 |
as eclasses are. Similarly to eclasses, sub-repositories can override |
216 |
(or disable) QA checks. |
217 |
|
218 |
System-wide QA checks present the opportunity of installing QA checks along |
219 |
with packages. In the past, some QA checks were run only conditionally |
220 |
depending on existence of external checker software. Instead, the software |
221 |
packages can install their own QA checks directly. |
222 |
|
223 |
The administrative override via ``/usr/local`` is a natural extension |
224 |
of system-wide QA checks. Additionally, it can be used by the sysadmin |
225 |
to override or disable practically any other QA check, either internal Portage |
226 |
or repository-wide. |
227 |
|
228 |
Sharing the QA checks has the additional advantage of having unified QA tools |
229 |
for all Package Managers. |
230 |
|
231 |
QA check script format |
232 |
---------------------- |
233 |
|
234 |
Use of bash is aimed to match the ebuild format. The choice of functions aims |
235 |
at portability between Package Managers. |
236 |
|
237 |
The scripts are run in isolated subshell to simplify the checks and reduce |
238 |
the risk of accidental cross-script issues. |
239 |
|
240 |
The script need to end with a successful command as a result of bash |
241 |
limitation:: |
242 |
|
243 |
source foo || die "source failed" |
244 |
|
245 |
The ``source`` call either returns the exit code of last command in the script |
246 |
or unsuccessful exit code in case of sourcing error. In order to distinguish |
247 |
between the two, we need to guarantee that the script always returns |
248 |
successfully. |
249 |
|
250 |
The extra ``eqawarn`` log function aims to provide the user with distinction |
251 |
between important user-directed warnings and developer-oriented QA issues. |
252 |
The ``eqatag`` function aims to store check results in a machine-readable |
253 |
format for further processing. |
254 |
|
255 |
Inheriting eclasses makes it possible to reuse code and improve |
256 |
maintainability. The possibility is mostly intended for eclass-specific checks |
257 |
that may want to e.g. obtain search paths from the eclass. |
258 |
|
259 |
Inheriting is allowed only in repository-specific since it is the only |
260 |
location where availability of eclasses can be assumed. For system-wide |
261 |
checks, we can't assume that the source repository will be available when |
262 |
ebuild in question is processed. |
263 |
|
264 |
Function specification |
265 |
---------------------- |
266 |
eqawarn |
267 |
~~~~~~~ |
268 |
|
269 |
This function is already considered well-defined at the time of writing. It is |
270 |
supported by Portage and stubbed in ``eutils.eclass``. Therefore, |
271 |
the specification aims to be a best match between the current implementation |
272 |
and the PMS definition of ``ewarn`` function. The latter specifically involves |
273 |
making the output and output control mechanisms PM-defined. |
274 |
|
275 |
eqatag |
276 |
~~~~~~ |
277 |
|
278 |
This functions is defined in order to allow external tools to parse results |
279 |
of QA checks easily, tinderbox in particular. The name ``eqatag`` alludes |
280 |
to the process of 'tagging' files with QA labels. |
281 |
|
282 |
The original proposal has used the name ``eqalog`` but it was rejected because |
283 |
of potential confusion with user-oriented ``elog`` function. |
284 |
|
285 |
The tags can be associated both with files and abstract data to accommodate |
286 |
the widest range of checks. The additional data is provided in key-value form |
287 |
to allow extending or changing the format easily. The file path format is |
288 |
meant to match the canonical ``/usr/bin/foo`` paths. |
289 |
|
290 |
The requirement of leading slash allows the function to safely distinguish |
291 |
between key-value data (assuming the key name must not start with a slash) |
292 |
and files. |
293 |
|
294 |
The ``-v`` argument works as a short-hand for an expected-to-be-common |
295 |
practice of:: |
296 |
|
297 |
eqawarn "The following files are frobnicated incorrectly:" |
298 |
eqawarn |
299 |
eqatag -v frobnicate "${files[@]}" |
300 |
eqawarn |
301 |
eqawarn "Please consult http://example.com/frobnicate for more details." |
302 |
|
303 |
which would be output as:: |
304 |
|
305 |
* The following files are frobnicated incorrectly: |
306 |
* |
307 |
* /usr/bin/frobnicatee |
308 |
* /usr/bin/other-frobnicatee |
309 |
* |
310 |
* Please consult http://example.com/frobnicate for more details. |
311 |
|
312 |
The mechanism for storing the results is left implementation-defined because |
313 |
both the method of running builds and their location varies through Package |
314 |
Managers. The original proposal used a well-defined format in ``${T}/qa.log``. |
315 |
|
316 |
|
317 |
Backwards Compatibility |
318 |
======================= |
319 |
|
320 |
Past versions of the Package Managers will only use their own built-in checks, |
321 |
and will not be affected by the specification. |
322 |
|
323 |
Compliant versions of the Package Manager will split the built-in checks into |
324 |
multiple files. When particular checks are moved into the repository, the name |
325 |
will be retained so that the repository copy will override the built-in check |
326 |
and no duplicate checking will happen. |
327 |
|
328 |
The transferred checks will be removed in the future versions of the Package |
329 |
Manager. However, since they will support this GLEP, the relevant checks will |
330 |
be used from the repository anyway. |
331 |
|
332 |
|
333 |
Reference implementation |
334 |
======================== |
335 |
|
336 |
The reference implementation of ``install-qa-check.d`` is available in Portage |
337 |
starting with version 2.2.15 (released 4 Dec 2014). The support |
338 |
for ``postinst-qa-check.d`` was added in 2.3.9 (released 19 Sep 2017). |
339 |
|
340 |
|
341 |
Copyright |
342 |
========= |
343 |
|
344 |
This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 |
345 |
Unported License. To view a copy of this license, visit |
346 |
http://creativecommons.org/licenses/by-sa/3.0/. |
347 |
|
348 |
-- |
349 |
Best regards, |
350 |
Michał Górny |