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