1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
<?xml version="1.0"?>
<guide self="general-concepts/tree/">
<chapter>
<title>The Gentoo Repository</title>
<body>
<p>
The basic layout of the Gentoo repository is as follows:
</p>
<ul>
<li>
Categories, for example <c>app-editors</c>, <c>sys-apps</c>
<ul>
<li>Category metadata, for example <c>app-admin/metadata.xml</c></li>
<li>
Package directories for example <c>app-editors/vim</c>
<ul>
<li>Package metadata, for example <c>app-editors/vim/metadata.xml</c></li>
<li>Package Manifest, for example <c>app-editors/vim/Manifest</c></li>
<li>
Ebuilds, for example <c>app-editors/vim/vim-6.3.068.ebuild</c>,
<c>app-editors/vim/vim-7.0_alpha20050326.ebuild</c>
</li>
<li>
Package files directory, for example <c>app-editors/vim/files</c>
<ul>
<li>
Small patches and other miscellaneous files, for example
<c>app-editors/vim/files/vim-completion</c>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li>Eclasses directory, <c>eclass/</c></li>
<li>Licenses directory, <c>licenses/</c></li>
<li>
Metadata directory, <c>metadata/</c>. Most of the listed contents
are not kept directly in the main git tree but instead
auto-generated or included from other repositories as part of the
<uri link="::general-concepts/git-to-rsync">Git to Rsync</uri>
process.
<ul>
<li>
Various control files, for example <c>layout.conf</c>, <c>timestamp</c>
and <c>projects.xml</c>. Only <c>layout.conf</c> exists in the main git tree.
</li>
<li>
XML validation files in <c>metadata/dtd/</c> and <c>metadata/xml-schema/</c>.
</li>
<li>
Security advisories in <c>metadata/glsa/</c> and news items in
<c>metadata/news/</c>
</li>
</ul>
</li>
<li>
Profiles directory, <c>profiles/</c>
<ul>
<li>
Various control and documentation files, for example <c>categories</c>,
<c>info_pkgs</c>, <c>info_vars</c>, <c>package.mask</c>, <c>use.desc</c>
</li>
<li>
Updates directory, <c>profiles/updates/</c>
<ul>
<li>Updates files, for example <c>profiles/updates/1Q-2005</c></li>
</ul>
</li>
<li>
Main profile cascade
</li>
</ul>
</li>
<li>Scripts directory, <c>scripts/</c></li>
<li>
Distfiles directory, <c>distfiles/</c>. This is not included in the main
git tree, but it will be found on most user systems.
</li>
<li>
Packages directory, <c>packages</c>. Again, this is found on user systems but not
in the main git tree.
</li>
</ul>
</body>
<section>
<title>What Belongs in the Tree?</title>
<body>
<p>
Things that do <b>not</b> belong in the tree:
</p>
<ul>
<li>Large patches</li>
<li>Non-text files</li>
<li>Photos of teletubbies</li>
<li>Files whose name contains characters outside <c>[A-Za-z0-9._+-]</c></li>
<li>Files whose name starts with a dot, a hyphen, or a plus sign</li>
</ul>
<p>
Naming rules for distfiles are more lenient, but for interoperability their
filenames are restricted to the printable ASCII range excluding SPACE, i.e.,
U+0021 to U+007e (see also
<uri link="https://www.gentoo.org/glep/glep-0031.html#suitable-characters-for-file-and-directory-names">
GLEP 31</uri>). Any characters that have a special meaning in Bash or in
<c>SRC_URI</c> should also be avoided. If necessary, upstream files can be
renamed using <uri link="::ebuild-writing/variables/#Renaming Sources">
<c>-></c> syntax</uri>.
</p>
<p>
Software-wise, in general all of the following should be met in order for a package to be included in the tree:
</p>
<dl>
<dt>Active, Cooperative Upstream</dt>
<dd>
<p>
If a package is undeveloped or unmaintained upstream, it can be extremely
difficult to get problems fixed. If a package does not have an active
upstream, the developers who add the package to the tree must ensure that
they are able to fix any issues which may arise.
</p>
<p>
Sometimes upstream may have a reason for not wanting their package included
in the tree. This should be respected.
</p>
</dd>
<dt>Reasonably Stable</dt>
<dd>
<p>
Keep super-experimental things out of the tree. If you must commit them,
consider using <c>package.mask</c> until things calm down, or better yet make
them available as overlay ebuilds.
</p>
</dd>
<dt>Reasonably Useful</dt>
<dd>
<p>
Don't feel obliged to include "Joe's '1337 XMMS Skinz Collection" or "Hans'
Super Cool Fast File System" in the tree just because a few users ask for
it. Stick to things that might actually be of use.
</p>
</dd>
<dt>Properly Packaged</dt>
<dd>
<p>
If something is only available in live CVS or dodgy autopackage format,
don't include it until upstream can come up with a decent source package.
Similarly, avoid things that don't have a proper build system (where
relevant) <d/> these are very tricky to maintain.
</p>
</dd>
<dt>Patching and Distribution Permitted</dt>
<dd>
<p>
If we can't patch packages as necessary ourselves, we end up relying
entirely upon upstream for support. This can be problematic, especially if
upstream are slow at fixing things. We don't want to be in the situation
where we can't stable a critical package because we're still waiting for a
closed-source vendor to get their act together.
</p>
<p>
Similarly, not being able to mirror and distribute tarballs ourselves makes
us rely entirely upon upstream mirrors. Experience has shown that these are
often extremely unreliable, with files changing, moving or vanishing at
random.
</p>
</dd>
<dt>Working Ebuilds</dt>
<dd>
<p>
If you don't have a <e>working</e> ebuild, don't include it.
</p>
</dd>
<dt>Portable</dt>
<dd>
<p>
If software is unportable, it's generally because it's badly written.
Remember that although x86 has a market majority <e>now</e>, it probably won't in
the not too distant future once x86-64 catches on.
</p>
</dd>
<dt>Reasonable Security Record</dt>
<dd>
<p>
Don't include software that has a terrible security record. Each
vulnerability is a <e>lot</e> of work for a lot of people (security teams, arch
teams and package maintainers).
</p>
</dd>
</dl>
</body>
</section>
</chapter>
</guide>
|