Gentoo Archives: gentoo-dev

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