1 |
commit: 29d3b185220083178af1ce1680af68dc25da94e7 |
2 |
Author: Michał Górny <mgorny <AT> gentoo <DOT> org> |
3 |
AuthorDate: Sun Nov 5 21:11:03 2017 +0000 |
4 |
Commit: Michał Górny <mgorny <AT> gentoo <DOT> org> |
5 |
CommitDate: Mon Nov 13 16:33:01 2017 +0000 |
6 |
URL: https://gitweb.gentoo.org/data/glep.git/commit/?id=29d3b185 |
7 |
|
8 |
glep-0074: More suggestions from Robin H. Johnson |
9 |
|
10 |
glep-0074.rst | 64 ++++++++++++++++++++++++++++++++++------------------------- |
11 |
1 file changed, 37 insertions(+), 27 deletions(-) |
12 |
|
13 |
diff --git a/glep-0074.rst b/glep-0074.rst |
14 |
index e4d6a80..86b2361 100644 |
15 |
--- a/glep-0074.rst |
16 |
+++ b/glep-0074.rst |
17 |
@@ -8,7 +8,7 @@ Type: Standards Track |
18 |
Status: Draft |
19 |
Version: 1 |
20 |
Created: 2017-10-21 |
21 |
-Last-Modified: 2017-10-30 |
22 |
+Last-Modified: 2017-11-06 |
23 |
Post-History: 2017-10-26 |
24 |
Content-Type: text/x-rst |
25 |
Requires: 59, 61 |
26 |
@@ -125,9 +125,10 @@ that are not otherwise ignored, they need to be covered by an explicit |
27 |
|
28 |
All the local (non-``DIST``) files covered by a Manifest tree must |
29 |
reside on the same filesystem. It is an error to specify entries |
30 |
-applying to files on another filesystem. If subdirectories |
31 |
-that are not otherwise ignored reside on a different filesystem, they |
32 |
-must be explicitly excluded via ``IGNORE``. |
33 |
+applying to files on another filesystem. If files or directories that |
34 |
+are not otherwise ignored reside on a different filesystem, or symbolic |
35 |
+links point to targets on a different filesystem, they must |
36 |
+be explicitly excluded via ``IGNORE``. |
37 |
|
38 |
|
39 |
File verification |
40 |
@@ -194,7 +195,7 @@ The Manifest files can specify the following tags: |
41 |
to detect an outdated repository checkout as described in `Timestamp |
42 |
verification`_. |
43 |
|
44 |
-``MANIFEST <path> <size> <checksums>…`` |
45 |
+``MANIFEST <path> <size> <checksums>...`` |
46 |
Specifies a sub-Manifest. The sub-Manifest must be verified like |
47 |
a regular file. If the verification succeeds, the entries from |
48 |
the sub-Manifest are included for verification as described |
49 |
@@ -206,12 +207,12 @@ The Manifest files can specify the following tags: |
50 |
verification (always pass). *Path* must be a plain file or directory |
51 |
path without a trailing slash, and must not contain wildcards. |
52 |
|
53 |
-``DATA <path> <size> <checksums>…`` |
54 |
+``DATA <path> <size> <checksums>...`` |
55 |
Specifies a regular file subject to Manifest verification. The file |
56 |
is required to pass verification. Used for all files that do not match |
57 |
any other type. |
58 |
|
59 |
-``DIST <filename> <size> <checksums>…`` |
60 |
+``DIST <filename> <size> <checksums>...`` |
61 |
Specifies a distfile entry used to verify files fetched as part |
62 |
of ``SRC_URI``. The filename must match the filename used to store |
63 |
the fetched file as specified in the PMS [#PMS-FETCH]_. The package |
64 |
@@ -226,15 +227,15 @@ Deprecated Manifest tags |
65 |
For backwards compatibility, the following tags are additionally |
66 |
allowed at the package directory level: |
67 |
|
68 |
-``EBUILD <filename> <size> <checksums>…`` |
69 |
+``EBUILD <filename> <size> <checksums>...`` |
70 |
Equivalent to the ``DATA`` type. |
71 |
|
72 |
-``MISC <path> <size> <checksums>…`` |
73 |
+``MISC <path> <size> <checksums>...`` |
74 |
Equivalent to the ``DATA`` type. Historically indicated that |
75 |
the package manager may ignore a verification failure if operating |
76 |
in non-strict mode. However, that behavior is deprecated. |
77 |
|
78 |
-``AUX <filename> <size> <checksums>…`` |
79 |
+``AUX <filename> <size> <checksums>...`` |
80 |
Equivalent to the ``DATA`` type, except that the filename is relative |
81 |
to ``files/`` subdirectory. |
82 |
|
83 |
@@ -314,13 +315,13 @@ of supported algorithms is outside the scope of this specification. |
84 |
The algorithm names reserved at the time of writing are: |
85 |
|
86 |
- ``MD5`` [#MD5]_, |
87 |
-- ``RMD160`` — RIPEMD-160 [#RIPEMD160]_, |
88 |
+- ``RMD160`` -- RIPEMD-160 [#RIPEMD160]_, |
89 |
- ``SHA1`` [#SHS]_, |
90 |
-- ``SHA256`` and ``SHA512`` — SHA-2 family of hashes [#SHS]_, |
91 |
+- ``SHA256`` and ``SHA512`` -- SHA-2 family of hashes [#SHS]_, |
92 |
- ``WHIRLPOOL`` [#WHIRLPOOL]_, |
93 |
-- ``BLAKE2B`` and ``BLAKE2S`` — BLAKE2 family of hashes [#BLAKE2]_, |
94 |
-- ``SHA3_256`` and ``SHA3_512`` — SHA-3 family of hashes [#SHA3]_, |
95 |
-- ``STREEBOG256`` and ``STREEBOG512`` — Streebog family of hashes |
96 |
+- ``BLAKE2B`` and ``BLAKE2S`` -- BLAKE2 family of hashes [#BLAKE2]_, |
97 |
+- ``SHA3_256`` and ``SHA3_512`` -- SHA-3 family of hashes [#SHA3]_, |
98 |
+- ``STREEBOG256`` and ``STREEBOG512`` -- Streebog family of hashes |
99 |
[#STREEBOG]_. |
100 |
|
101 |
The method of introducing new hashes is defined by GLEP 59 [#GLEP59]_. |
102 |
@@ -370,9 +371,9 @@ the following content:: |
103 |
IGNORE lost+found |
104 |
IGNORE packages |
105 |
MANIFEST app-accessibility/Manifest 14821 SHA256 1b5f.. SHA512 f7eb.. |
106 |
- … |
107 |
+ ... |
108 |
MANIFEST eclass/Manifest.gz 50812 SHA256 8c55.. SHA512 2915.. |
109 |
- … |
110 |
+ ... |
111 |
|
112 |
An example modern Manifest (disregarding backwards compatibility) |
113 |
for a package directory would have the following content:: |
114 |
@@ -484,15 +485,17 @@ files, and symbolic links to directories are followed as if they were |
115 |
regular directories. |
116 |
|
117 |
Dotfiles are implicitly ignored as that is a common notion used |
118 |
-in software written for POSIX systems. All other common filenames |
119 |
-require explicit ``IGNORE`` lines. |
120 |
+in software written for POSIX systems. All other filenames require |
121 |
+explicit ``IGNORE`` lines. |
122 |
|
123 |
An ability to inject additional ignore entries is provided to account |
124 |
-for site configuration affecting the repository tree — placing |
125 |
+for site configuration affecting the repository tree -- placing |
126 |
additional files in it, skipping some of the categories from syncing. |
127 |
+This configuration can extend beyond the limits of this GLEP, |
128 |
+e.g. by allowing wildcards or regular expressions. |
129 |
|
130 |
The algorithm is restricted to work on a single filesystem. This is |
131 |
-mostly relevant when scanning for top-level Manifest — we do not want |
132 |
+mostly relevant when scanning for top-level Manifest -- we do not want |
133 |
to cross filesystem boundaries then. However, to ensure consistent |
134 |
bidirectional behavior we need to also ban them when operating downwards |
135 |
the tree. |
136 |
@@ -551,9 +554,12 @@ However, the usefulness of ``MISC`` in both cases is doubtful. |
137 |
The cases for stripping unnecessary files mostly focused around space |
138 |
savings. For this purpose, stripping ``metadata.xml`` and similar files |
139 |
has little value. It is much more common for users to strip whole |
140 |
-categories which can not be handled via the ``MISC`` type, and needs |
141 |
-a dedicated package manager mechanism. The same mechanism can also |
142 |
-handle files that used the ``MISC`` type. |
143 |
+packages or categories. The ``MISC`` type is not suitable for that, |
144 |
+and so a dedicated package manager mechanism needs to be developed |
145 |
+instead. The same mechanism can also handle files that historically used |
146 |
+the ``MISC`` type. As an example, the package manager may choose |
147 |
+to generate both the rsync exclusion list and Manifest ignore list |
148 |
+using a single source list. |
149 |
|
150 |
The cases for autogenerated files involve such cache files |
151 |
as ``use.local.desc``. However, we can not include ``md5-cache`` there |
152 |
@@ -673,8 +679,8 @@ in a single file inside the package directory. It has been specifically |
153 |
pointed out that: |
154 |
|
155 |
- since distfiles are sometimes reused across different packages, |
156 |
- the repeating checksums are redundant, |
157 |
- |
158 |
+ the repeating checksums are redundant [#DIST]_. |
159 |
+ |
160 |
- mirror admins were interested in the possibility of verifying all |
161 |
the distfiles with a single tool. |
162 |
|
163 |
@@ -833,7 +839,7 @@ References |
164 |
.. [#WHIRLPOOL] The WHIRLPOOL Hash Function |
165 |
(http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html) |
166 |
|
167 |
-.. [#BLAKE2] BLAKE2 — fast secure hashing |
168 |
+.. [#BLAKE2] BLAKE2 -- fast secure hashing |
169 |
(https://blake2.net/) |
170 |
|
171 |
.. [#SHA3] FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash |
172 |
@@ -846,6 +852,10 @@ References |
173 |
.. [#C08] Cappos, J et al. (2008). "Attacks on Package Managers" |
174 |
(https://www2.cs.arizona.edu/stork/packagemanagersecurity/attacks-on-package-managers.html) |
175 |
|
176 |
+.. [#DIST] According to Robin H. Johnson, 8.4% of all DIST entries |
177 |
+ at the time of writing are duplicate, representing a 2 MiB |
178 |
+ out of 25 MiB of DIST entries altogether. |
179 |
+ |
180 |
.. [#GEMATO] gemato: Gentoo Manifest Tool |
181 |
(https://github.com/mgorny/gemato/) |