1 |
Hi, |
2 |
|
3 |
Here's the second version. I've attempted to make the format section |
4 |
more readable, clarified the value types and added more examples all |
5 |
over the place. |
6 |
|
7 |
|
8 |
--- |
9 |
GLEP: 9999 |
10 |
Title: Repository configuration file (layout.conf) |
11 |
Author: Michał Górny <mgorny@g.o> |
12 |
Type: Standards Track |
13 |
Status: Draft |
14 |
Version: 1.0 |
15 |
Created: 2021-05-19 |
16 |
Last-Modified: 2021-05-19 |
17 |
Post-History: 2021-05-19 |
18 |
Content-Type: text/x-rst |
19 |
--- |
20 |
|
21 |
Abstract |
22 |
======== |
23 |
|
24 |
The ``metadata/layout.conf`` file format is specified as used by Portage |
25 |
and pkgcore. A standard set of configuration keys is described |
26 |
including the keys currently used in the Gentoo repository. |
27 |
|
28 |
|
29 |
Motivation |
30 |
========== |
31 |
|
32 |
The ``metadata/layout.conf`` file was first added to the Gentoo |
33 |
repository in Oct 2011, to facilitate setting of hashes used |
34 |
in Manifest2 files. In Mar 2012, it was used to indicate the transition |
35 |
to the new ``md5-dict`` cache format. In Jul 2013, it started being |
36 |
used to indicate the repository's masters and effectively became |
37 |
obligatory for all repositories. |
38 |
|
39 |
Today, ``layout.conf`` is used for various repository configuration |
40 |
knobs that can be expressed as simple values and therefore |
41 |
do not justify adding new files to the repository. This primarily |
42 |
involves the configuration of development tools but also includes a few |
43 |
keys relevant to the behavior of the package manager. |
44 |
|
45 |
However, ``layout.conf`` is currently not covered by any formal |
46 |
specification. The PMS neglects its existence entirely, and the keys |
47 |
used are roughly defined by their first use of Portage or pkgcore. |
48 |
This GLEP aims to overcome this by providing a formal specification |
49 |
for the file, as well as an up-to-date list of permitted configuration |
50 |
keys. |
51 |
|
52 |
|
53 |
Specification |
54 |
============= |
55 |
|
56 |
layout.conf file format |
57 |
----------------------- |
58 |
|
59 |
Every ebuild repository must contain a ``metadata/layout.conf`` file. |
60 |
The file uses a line-oriented key-value format:: |
61 |
|
62 |
# comments are allowed |
63 |
key = value |
64 |
key2 = value2 |
65 |
|
66 |
Lines starting with a hash sign (``#``) represent comments and are |
67 |
ignored, as are lines consisting entirely of whitespace. |
68 |
|
69 |
Key can be any string and must not contain spaces. The exact form |
70 |
of value depends on the key. For some keys, the value is permitted |
71 |
to contain spaces, and it must not be quoted. In some cases an empty |
72 |
value is permitted. The whitespace between the elements is optional |
73 |
and is ultimately stripped. Every key must occur no more than once |
74 |
in the file. |
75 |
|
76 |
|
77 |
Configuration keys |
78 |
------------------ |
79 |
|
80 |
This GLEP specifies a number of standard configuration keys. New keys |
81 |
may be added to it in the future. It is strongly recommended that any |
82 |
new keys are added to the specification before being used. |
83 |
|
84 |
The package manager can implement a subset of the listed keys. Unknown |
85 |
keys should be ignored. |
86 |
|
87 |
|
88 |
The following keys must be present in a ``layout.conf`` file: |
89 |
|
90 |
masters = <space-separated repository names> |
91 |
Specifies the master repositories of this repository. For stand-alone |
92 |
repositories, this must be set to an empty value. Otherwise, it can |
93 |
list one or more repositories, separated by spaces. This key must |
94 |
be specified. |
95 |
|
96 |
Examples:: |
97 |
|
98 |
# most common case |
99 |
masters = gentoo |
100 |
# stand-alone repository |
101 |
masters = |
102 |
# multiple masters |
103 |
masters = gentoo python |
104 |
|
105 |
|
106 |
The following keys are optional: |
107 |
|
108 |
manifest-hashes = <space-separated hash names> |
109 |
Specifies the list of hashes that should be used for new distfiles |
110 |
in the Manifest files. The development tools may create a subset |
111 |
of the specified hashes if it is not updating the checksums for |
112 |
the specified distfile, or does not support the hash in question. |
113 |
The hash names are specified in GLEP 74. [#GLEP74]_ The default |
114 |
set of hashes is implementation-defined. |
115 |
|
116 |
Example:: |
117 |
|
118 |
manifest-hashes = BLAKE2B SHA512 |
119 |
|
120 |
manifest-required-hashes = <space-separated hash names> |
121 |
Specifies the list of hashes that must be used in Manifest files. |
122 |
The development tools must support all the hashes listed there, |
123 |
and update distfile checksums to use these hashes (refetching |
124 |
if necessary). This must be a subset of manifest-hashes. If not |
125 |
specified, all hashes from manifest-hashes (or the default set) |
126 |
are considered required. |
127 |
|
128 |
use-manifests = ``strict``, ``true`` or ``false`` |
129 |
Indicates the policy for creating and using Manifest files. If set |
130 |
to ``strict``, Manifest files are created and files are required to |
131 |
match digests found in Manifests. If set to ``true``, Manifests |
132 |
are created but digest mismatches are ignored. If set to ``false``, |
133 |
Manifests are not used at all. The default is ``strict``. |
134 |
|
135 |
update-changelog = ``true`` or ``false`` |
136 |
Indicates whether the development tools should write ChangeLog files. |
137 |
The default is ``false``. |
138 |
|
139 |
cache-formats = <space-separated format names> |
140 |
Specifies one or more cache formats used by the repository. |
141 |
The currently defined values are ``pms`` for the original format |
142 |
specified in the PMS and ``md5-dict`` for the md5-dict format |
143 |
introduced in Portage 2.2.0_alpha68. The default is |
144 |
implementation-defined. |
145 |
|
146 |
Examples:: |
147 |
|
148 |
# modern repo |
149 |
cache-formats = md5-dict |
150 |
# backwards compatibility case |
151 |
cache-formats = md5-dict pms |
152 |
|
153 |
eapis-deprecated = <space-separated EAPI names> |
154 |
Specifies one or more EAPIs that are to be considered deprecated |
155 |
by the development tools for use in ebuilds, i.e. their use should |
156 |
trigger a warning. If not specified, no EAPIs are deprecated. |
157 |
|
158 |
Example:: |
159 |
|
160 |
eapis-deprecated = 0 1 2 3 4 |
161 |
|
162 |
eapis-banned = <space-separated EAPI names> |
163 |
Specifies one or more EAPIs that are to be considered banned |
164 |
by the development tools for use in ebuilds, i.e. their use should |
165 |
be blocked. If not specified, no EAPIs are banned. |
166 |
|
167 |
repo-name = <string> |
168 |
Specifies the repository name. If specified, it must be equal |
169 |
to the contents of ``profiles/repo_name``. If not specified, |
170 |
it defaults to the same value. Discouraged. |
171 |
|
172 |
aliases = <space-separated names> |
173 |
Specified one or more additional names that can be used to reference |
174 |
the repository (e.g. in repository dependencies). If not specified, |
175 |
no aliases are defined. |
176 |
|
177 |
Example:: |
178 |
|
179 |
# gen2 is a fork of Gentoo that can be used in place of the Gentoo |
180 |
# repository |
181 |
repo-name = gen2 |
182 |
aliases = gentoo |
183 |
|
184 |
thin-manifests = ``true`` or ``false`` |
185 |
If enabled, Manifest files in the package directory must contain only |
186 |
``DIST`` entries. If disabled, Manifest files in the package |
187 |
directory must list digests for all files found in the package |
188 |
directory and the files directory. The default is ``false``. |
189 |
|
190 |
sign-commits = ``true`` or ``false`` |
191 |
Indicates whether git commits are to be signed (using ``git commit |
192 |
--gpg-sign``. The default is ``false``. |
193 |
|
194 |
sign-manifests = ``true`` or ``false`` |
195 |
Indicates whether individual package Manifests should be PGP-signed. |
196 |
Note that this refers to the historical behavior of signing individual |
197 |
Manifests, not the GLEP 74 behavior of signing the top-level Manifest. |
198 |
[#GLEP74]_ The default is ``true`` if PGP signing is configured. |
199 |
|
200 |
properties-allowed = <space-separated property tokens> |
201 |
Specifies the list of ``PROPERTIES`` tokens that are permitted |
202 |
to be used in ebuilds. If present, the development tools should issue |
203 |
a warning if ``PROPERTIES`` contains any tokens that are not listed |
204 |
here. If not specified, all tokens are permitted. |
205 |
|
206 |
Example:: |
207 |
|
208 |
properties-allowed = live |
209 |
|
210 |
restrict-allowed = <space-separated restrict tokens> |
211 |
Same as properties-allowed, except for ``RESTRICT``. |
212 |
|
213 |
profile-formats = <space-separated format names> |
214 |
Specifies the format used by profiles and/or extensions to it. |
215 |
The default is ``pms`` indicating the format specified in the PMS. |
216 |
Other values are implementation-defined. |
217 |
|
218 |
Examples:: |
219 |
|
220 |
profile-formats = portage-1 |
221 |
profile-formats = portage-2 profile-set |
222 |
|
223 |
|
224 |
Complete example |
225 |
---------------- |
226 |
|
227 |
The following is an example configuration for a git repository with |
228 |
Gentoo set as a master:: |
229 |
|
230 |
masters = gentoo |
231 |
|
232 |
# git: do not use ChangeLog, use thin, unsigned Manifests |
233 |
update-changelog = false |
234 |
thin-manifests = true |
235 |
sign-manifests = false |
236 |
|
237 |
# force the new md5-dict cache format |
238 |
cache-formats = md5-dict |
239 |
|
240 |
|
241 |
Rationale |
242 |
========= |
243 |
|
244 |
This GLEP is written almost 10 years after ``layout.conf`` was |
245 |
originally introduced. This made it necessary to write it in such a way |
246 |
that both the modern and historical implementations in Portage |
247 |
and pkgcore, as well as the use in the Gentoo repository |
248 |
and a reasonably large subset of the other repositories would remain |
249 |
compliant. |
250 |
|
251 |
The historical default of assuming ``masters = gentoo`` when unspecified |
252 |
is omitted as it is not portable and verbosely deprecated for many |
253 |
years in Portage. All repositories are required to explicitly specify |
254 |
their masters, or an empty value if they are stand-alone. |
255 |
|
256 |
The default for Manifest hashes and cache formats are left to be |
257 |
implementation-defined, as the defaults changed over time and do not |
258 |
match between package managers. In particular, Portage attempts to |
259 |
autodetect the cache format currently used in a given repository. |
260 |
|
261 |
The repo-name key has been originally added as an alternative to |
262 |
``profiles/repo_name``. However, the latter file is still required |
263 |
for PMS compliance. Furthermore, given that it is much easier to parse, |
264 |
there seems to be no appealing reason to work towards replacing that |
265 |
file. This means that for all practical reasons, the repo-name key |
266 |
is redundant and is listed here for completeness only. |
267 |
|
268 |
The profile-formats key has been introduced to permit Portage-specific |
269 |
extensions to the profile directory without having to introduce custom |
270 |
EAPIs. The exact extensions are considered outside the scope of this |
271 |
specification. |
272 |
|
273 |
|
274 |
Backwards Compatibility |
275 |
======================= |
276 |
|
277 |
The existing implementations found in Portage and pkgcore conform |
278 |
to this specification, so does the ``metadata/layout.conf`` file |
279 |
found in the Gentoo repository. |
280 |
|
281 |
|
282 |
Reference Implementation |
283 |
======================== |
284 |
|
285 |
The support for ``metadata/layout.conf`` is already a part of Portage |
286 |
and pkgcore. |
287 |
|
288 |
|
289 |
References |
290 |
========== |
291 |
|
292 |
.. [#GLEP74] GLEP 74: Full-tree verification using Manifest files |
293 |
(https://www.gentoo.org/glep/glep-0074.html) |
294 |
|
295 |
|
296 |
Copyright |
297 |
========= |
298 |
|
299 |
This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 |
300 |
International License. To view a copy of this license, visit |
301 |
https://creativecommons.org/licenses/by-sa/4.0/. |
302 |
|
303 |
|
304 |
|
305 |
-- |
306 |
Best regards, |
307 |
Michał Górny |