1 |
commit: ded893153edae1761760c572f9f40f30eff4b273 |
2 |
Author: Markos Chandras <hwoarang <AT> gentoo <DOT> org> |
3 |
AuthorDate: Sat Nov 3 22:20:06 2012 +0000 |
4 |
Commit: Markos Chandras <hwoarang <AT> gentoo <DOT> org> |
5 |
CommitDate: Sat Nov 3 22:20:06 2012 +0000 |
6 |
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=ded89315 |
7 |
|
8 |
metadata: Add examples from the devrel handbook |
9 |
|
10 |
--- |
11 |
ebuild-writing/misc-files/metadata/text.xml | 464 +++++++++++++++++++++++++-- |
12 |
1 files changed, 442 insertions(+), 22 deletions(-) |
13 |
|
14 |
diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml |
15 |
index 1cd4081..5e6cd52 100644 |
16 |
--- a/ebuild-writing/misc-files/metadata/text.xml |
17 |
+++ b/ebuild-writing/misc-files/metadata/text.xml |
18 |
@@ -19,31 +19,452 @@ provided, an English long description must be present. A typical |
19 |
example might look like: |
20 |
</p> |
21 |
|
22 |
+<subsection> |
23 |
+<body> |
24 |
+ |
25 |
+<p> |
26 |
+A <path>metadata.xml</path> file can contain a number of tags: |
27 |
+</p> |
28 |
+ |
29 |
+<table> |
30 |
+<tr> |
31 |
+ <th>tag</th> |
32 |
+ <th>description</th> |
33 |
+</tr> |
34 |
+<tr> |
35 |
+ <ti> |
36 |
+ <brite><pkgmetadata></brite> |
37 |
+ </ti> |
38 |
+ <ti> |
39 |
+ This is the root element of the <path>metadata.xml</path> file for |
40 |
+ packages. It has no attributes. The following subtags are |
41 |
+ allowed: |
42 |
+ <brite><herd></brite>, |
43 |
+ <brite><maintainer></brite>, |
44 |
+ <brite><longdescription></brite>, |
45 |
+ <brite><use></brite>, and |
46 |
+ <brite><upstream></brite>. |
47 |
+ There should be at least one <brite><herd></brite> or |
48 |
+ <brite><maintainer></brite> subtag. |
49 |
+ </ti> |
50 |
+</tr> |
51 |
+<tr> |
52 |
+ <ti> |
53 |
+ <brite><catmetadata></brite> |
54 |
+ </ti> |
55 |
+ <ti> |
56 |
+ This is the root element of the <path>metadata.xml</path> file for |
57 |
+ categories as per <uri link="/proj/en/glep/glep-0034.html">GLEP 34</uri>. |
58 |
+ It has no attributes. It contains a number of |
59 |
+ <brite><longdescription></brite> tags, each for a different |
60 |
+ language. |
61 |
+ </ti> |
62 |
+</tr> |
63 |
+<tr> |
64 |
+ <ti> |
65 |
+ <brite><herd></brite> |
66 |
+ </ti> |
67 |
+ <ti> |
68 |
+ If a package is maintained by one or more herds, names of these herds |
69 |
+ can be specified with the <brite><herd></brite> tag. The names |
70 |
+ used in this tag must be the same as specified in the <uri |
71 |
+ link="http://sources.gentoo.org/viewcvs.py/*checkout*/gentoo/xml/htdocs/proj/en/metastructure/herds/herds.xml?content-type=text/plain&rev=HEAD">herds.xml</uri> |
72 |
+ file. |
73 |
+ </ti> |
74 |
+</tr> |
75 |
+<tr> |
76 |
+ <ti> |
77 |
+ <brite><maintainer></brite> |
78 |
+ </ti> |
79 |
+ <ti> |
80 |
+ Besides being part of a herd, a package can also be maintained directly. |
81 |
+ The maintainers of a package can be specified with the |
82 |
+ <brite><maintainer></brite> tag. This tag has one required subtag: |
83 |
+ <brite><email></brite>. It has two optional subtags: |
84 |
+ <brite><name></brite>, and <brite><description></brite>. |
85 |
+ </ti> |
86 |
+</tr> |
87 |
+<tr> |
88 |
+ <ti><brite><email></brite></ti> |
89 |
+ <ti> |
90 |
+ This contains the e-mail address of the maintainer. It is required. |
91 |
+ </ti> |
92 |
+</tr> |
93 |
+<tr> |
94 |
+ <ti><brite><name></brite></ti> |
95 |
+ <ti> |
96 |
+ This contains freetext with the name of the maintainer. It is optional. |
97 |
+ </ti> |
98 |
+</tr> |
99 |
+<tr> |
100 |
+ <ti><brite><description></brite></ti> |
101 |
+ <ti> |
102 |
+ The description tag contains a description of the maintainership, or for |
103 |
+ example a remark that someone interested can take over the maintainership. |
104 |
+ It is optional. |
105 |
+ </ti> |
106 |
+</tr> |
107 |
+<tr> |
108 |
+ <ti><brite><longdescription></brite></ti> |
109 |
+ <ti> |
110 |
+ This tag contains a description of the package. This is to augment the |
111 |
+ DESCRIPTION field in the ebuilds themselves. This tag has two optional |
112 |
+ subtags: <brite><pkg></brite> and <brite><cat></brite>. |
113 |
+ </ti> |
114 |
+</tr> |
115 |
+<tr> |
116 |
+ <ti><brite><use></brite></ti> |
117 |
+ <ti> |
118 |
+ This tag contains descriptions of <uri |
119 |
+ link="::ebuild-writing/variables#iuse">USE flags</uri>. |
120 |
+ This tag is optional and, if specified, has one required subtag: |
121 |
+ <brite><flag></brite>. |
122 |
+ </ti> |
123 |
+</tr> |
124 |
+<tr> |
125 |
+ <ti><brite><flag></brite></ti> |
126 |
+ <ti> |
127 |
+ This tag contains a description of how the named USE flag affects this |
128 |
+ package. It is required if the <brite><use></brite> tag is specified. |
129 |
+ It also requires the USE flag to be named in the <c>name</c> attribute. |
130 |
+ This tag has two optional subtags: <brite><pkg></brite> and |
131 |
+ <brite><cat></brite>. |
132 |
+ </ti> |
133 |
+</tr> |
134 |
+<tr> |
135 |
+ <ti><brite><upstream></brite></ti> |
136 |
+ <ti> |
137 |
+ This tag contains information about the upstream developers/project. |
138 |
+ </ti> |
139 |
+</tr> |
140 |
+<tr> |
141 |
+ <ti><brite><maintainer></brite></ti> |
142 |
+ <ti> |
143 |
+ Name and e-mail of an upstream maintainer. May appear more than once. |
144 |
+ </ti> |
145 |
+</tr> |
146 |
+<tr> |
147 |
+ <ti><brite><name></brite></ti> |
148 |
+ <ti> |
149 |
+ The name of an upstream maintainer should contain a block of text with upstream's name. |
150 |
+ This element is mandatory for an upstream maintainer and must appear only once. |
151 |
+ </ti> |
152 |
+</tr> |
153 |
+<tr> |
154 |
+ <ti><brite><email></brite></ti> |
155 |
+ <ti> |
156 |
+ The email address of an upstream may appear only once. |
157 |
+ </ti> |
158 |
+</tr> |
159 |
+<tr> |
160 |
+ <ti><brite><changelog></brite></ti> |
161 |
+ <ti> |
162 |
+ Should contain a URL where the location of the upstream changelog can be found. |
163 |
+ The URL must be version independent and must point to a changelog which is only |
164 |
+ updated on new releases of the corresponding package. (This also implies that |
165 |
+ one can link to an automatically updated changelog in case of vcs snapshots |
166 |
+ only.) |
167 |
+ </ti> |
168 |
+</tr> |
169 |
+<tr> |
170 |
+ <ti><brite><doc></brite></ti> |
171 |
+ <ti> |
172 |
+ Should contain a URL where the location of the upstream documentation can be |
173 |
+ found. The link must not point to any third party documentation and must be |
174 |
+ version independent. If the documentation is available in more than one language, |
175 |
+ a lang attribute can be used which follows the same rules as the one for |
176 |
+ longdescription. |
177 |
+ </ti> |
178 |
+</tr> |
179 |
+<tr> |
180 |
+ <ti><brite><bugs-to></brite></ti> |
181 |
+ <ti> |
182 |
+ Should contain a place where bugs can be filed, a URL or an e-mail address prefixed |
183 |
+ with mailto:. |
184 |
+ </ti> |
185 |
+</tr> |
186 |
+<tr> |
187 |
+ <ti><brite><remote-id></brite></ti> |
188 |
+ <ti> |
189 |
+ Should specify a type of package identification tracker and the identification that |
190 |
+ corresponds to the package in question. remote-id should make it easier to index |
191 |
+ information such as its Freshmeat ID or its CPAN name. |
192 |
+ </ti> |
193 |
+</tr> |
194 |
+<tr> |
195 |
+ <ti><brite><pkg></brite></ti> |
196 |
+ <ti> |
197 |
+ This tag contains a valid package name in the format of a DEPEND. |
198 |
+ </ti> |
199 |
+</tr> |
200 |
+<tr> |
201 |
+ <ti><brite><cat></brite></ti> |
202 |
+ <ti> |
203 |
+ This tag contains a valid category name as defined in |
204 |
+ <path>profiles/categories</path>. |
205 |
+ </ti> |
206 |
+</tr> |
207 |
+</table> |
208 |
+ |
209 |
+<p> |
210 |
+There are also some attributes that can be used with these tags. They are all |
211 |
+optional: |
212 |
+</p> |
213 |
+ |
214 |
+<table> |
215 |
+<tr> |
216 |
+ <th>attribute</th> |
217 |
+ <th>tags</th> |
218 |
+ <th>description</th> |
219 |
+</tr> |
220 |
+<tr> |
221 |
+ <ti>lang</ti> |
222 |
+ <ti> |
223 |
+ <brite><description></brite>, <brite><longdescription></brite>, |
224 |
+ <brite><use></brite>, <brite><doc></brite> |
225 |
+ </ti> |
226 |
+ <ti> |
227 |
+ In every case where a description is required, there must be at |
228 |
+ <e>least</e> an english description. If an additional description in |
229 |
+ another language is given, this attribute is used to specify the language |
230 |
+ used. The format is the two-character language code as defined by the <uri |
231 |
+ link="http://www.w3.org/WAI/ER/IG/ert/iso639.htm#2letter">ISO-639-1</uri> |
232 |
+ norm. |
233 |
+ </ti> |
234 |
+</tr> |
235 |
+<tr> |
236 |
+ <ti>restrict</ti> |
237 |
+ <ti> |
238 |
+ <brite><herd></brite>, <brite><maintainer></brite>, |
239 |
+ <brite><longdescription></brite>, <brite><flag></brite> |
240 |
+ </ti> |
241 |
+ <ti> |
242 |
+ The restrict attribute allows one to restrict the application of certain |
243 |
+ tags to certain versions of a package. When this attribute is used, a tag |
244 |
+ without this attribute must also exist. That tag without the restrict |
245 |
+ attribute will serve as the default. The format of the restrict attribute |
246 |
+ is that of the DEPEND flag, except that "<" and |
247 |
+ ">" need to be specified by &lt; and &gt;.<br /> |
248 |
+ <br /> |
249 |
+ For example, in the <c>sys-libs/db</c> package, |
250 |
+ <c>restrict="&gt;=sys-libs/db-3.2.9-r5"</c> on the |
251 |
+ <brite>maintainer</brite> tag shows that I'm currently maintaining all |
252 |
+ versions greater then 3.2.9-r5. |
253 |
+ </ti> |
254 |
+</tr> |
255 |
+<tr> |
256 |
+ <ti>name</ti> |
257 |
+ <ti> |
258 |
+ <brite><flag></brite> |
259 |
+ </ti> |
260 |
+ <ti> |
261 |
+ This attribute is required on the <brite><flag></brite> tag. It |
262 |
+ simply contains the USE flag. |
263 |
+ <br /><br /> |
264 |
+ For example, in the <c>sys-apps/hal</c> package, <c><flag name='acpi'> |
265 |
+ Enables ACPI</flag></c> |
266 |
+ </ti> |
267 |
+</tr> |
268 |
+<tr> |
269 |
+ <ti>status</ti> |
270 |
+ <ti> |
271 |
+ <brite><maintainer></brite> |
272 |
+ </ti> |
273 |
+ <ti> |
274 |
+ The upstream maintainer element has a status attribute, which is one of active or inactive. |
275 |
+ This attribute is not mandatory. The absence of it shall be interpreted as unknown. |
276 |
+ Please note: This attribute is only allowed in the <upstream> <maintainer> element! |
277 |
+ </ti> |
278 |
+</tr> |
279 |
+<tr> |
280 |
+ <ti>type</ti> |
281 |
+ <ti> |
282 |
+ <brite><remote-id></brite> |
283 |
+ </ti> |
284 |
+ <ti> |
285 |
+ A string identifying the type of upstream source. A list of valid strings are kept in metadata.dtd. |
286 |
+ Developers should email the gentoo-dev mailing list before using a new type value. |
287 |
+ </ti> |
288 |
+</tr> |
289 |
+ |
290 |
+</table> |
291 |
+ |
292 |
+</body> |
293 |
+</subsection> |
294 |
+ |
295 |
+</body> |
296 |
+</section> |
297 |
+ |
298 |
+<section> |
299 |
+<title>Metadata Examples</title> |
300 |
+<subsection> |
301 |
+<title>First Example</title> |
302 |
+<body> |
303 |
+ |
304 |
+<p> |
305 |
+In this first example we provide you with the <path>metadata.xml</path> for |
306 |
+OpenOffice of which the ebuilds are completely managed by a herd called |
307 |
+<c>openoffice</c>: |
308 |
+</p> |
309 |
+ |
310 |
<codesample lang="sgml"> |
311 |
- <?xml version="1.0" encoding="UTF-8"?> |
312 |
- <!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> |
313 |
- <pkgmetadata> |
314 |
- <herd>freedesktop</herd> |
315 |
- <maintainer> |
316 |
- <email>dang@g.o</email> |
317 |
- <name>Daniel Gryniewicz</name> |
318 |
+<?xml version='1.0' encoding='UTF-8'?> |
319 |
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> |
320 |
+<pkgmetadata> |
321 |
+ <herd>openoffice</herd> |
322 |
+ <longdescription> |
323 |
+ OpenOffice is the opensource version of staroffice. |
324 |
+ This ebuild allows you to compile it yourself. Unfortunately this |
325 |
+ compilation can take up to a day depending on the speed of your |
326 |
+ computer. It will however make a snappier openoffice than the binary |
327 |
+ version. |
328 |
+ </longdescription> |
329 |
+</pkgmetadata> |
330 |
+</codesample> |
331 |
+ |
332 |
+<p> |
333 |
+The <c>openoffice</c> herd is defined in <path>herds.xml</path> by the |
334 |
+<uri link="/proj/en/metastructure">Gentoo Metastructure Project</uri>: |
335 |
+</p> |
336 |
+ |
337 |
+<note> |
338 |
+This example may be outdated when you read it. It's just an example! |
339 |
+</note> |
340 |
+ |
341 |
+<codesample lang="sgml"> |
342 |
+<herd> |
343 |
+ <name>openoffice</name> |
344 |
+ <email>openoffice@g.o</email> |
345 |
+ <description>Openoffice related packages</description> |
346 |
+ <maintainer><email>pauldv@g.o</email></maintainer> |
347 |
+ <maintainer><email>suka@g.o</email></maintainer> |
348 |
+</herd> |
349 |
+</codesample> |
350 |
+ |
351 |
+<p> |
352 |
+If you want to add (or remove) yourself from a herd, edit <path>herds.xml</path> |
353 |
+located in <path>[gentoo]/xml/htdocs/proj/en/metastructure/herds</path> in Gentoo's CVS repository. Make sure you |
354 |
+know the e-mail alias the herd listens to (for instance the "sound" herd has |
355 |
+<mail link="sound@g.o">sound@g.o</mail>) and add yourself to the |
356 |
+alias (by editing <path>/var/mail/alias/misc/<alias name></path> on |
357 |
+dev.gentoo.org). |
358 |
+</p> |
359 |
+ |
360 |
+</body> |
361 |
+</subsection> |
362 |
+<subsection> |
363 |
+<title>Second Example</title> |
364 |
+<body> |
365 |
+ |
366 |
+<p> |
367 |
+For the second example, we will examine the <path>metadata.xml</path> of |
368 |
+<c>app-portage/mirrorselect</c>. This ebuild is maintained by the |
369 |
+<c>tools-portage</c> herd, but has a separate maintainer. |
370 |
+</p> |
371 |
+ |
372 |
+<pre caption="Herd & individually maintained package"> |
373 |
+<?xml version='1.0' encoding='UTF-8'?> |
374 |
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> |
375 |
+<pkgmetadata> |
376 |
+ <herd>tools-portage</herd> |
377 |
+ <maintainer> |
378 |
+ <email>johnm@g.o</email> |
379 |
+ <name>John Mylchreest</name> |
380 |
+ </maintainer> |
381 |
+ <longdescription> |
382 |
+ This utility is used to select the fastest mirror (distfiles) and provide a |
383 |
+ nicer front-end for mirror selection (both rsync + distfiles) to a user. |
384 |
+ </longdescription> |
385 |
+</pkgmetadata> |
386 |
+</pre> |
387 |
+ |
388 |
+</body> |
389 |
+</subsection> |
390 |
+<subsection> |
391 |
+<title>Third Example</title> |
392 |
+<body> |
393 |
+ |
394 |
+<p> |
395 |
+For the third example, we will describe the <path>metadata.xml</path> of |
396 |
+<c>sys-apps/hal</c>. This ebuild is maintained by the <c>gentopia</c> herd |
397 |
+and contains USE flag descriptions. |
398 |
+</p> |
399 |
+ |
400 |
+<codesample lang="sgml"> |
401 |
+<?xml version="1.0" encoding="UTF-8"> |
402 |
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> |
403 |
+<pkgmetadata> |
404 |
+<herd>gentopia</herd> |
405 |
+<maintainer> |
406 |
+ <email>compnerd@g.o</email> |
407 |
+</maintainer> |
408 |
+<maintainer> |
409 |
+ <email>steev@g.o</email> |
410 |
+</maintainer> |
411 |
+<use> |
412 |
+ <flag name='acpi'>Enables HAL to attempt to read from |
413 |
+ /proc/acpi/event, if unavailable, HAL will read events from |
414 |
+ <pkg>sys-power/acpid</pkg>. If you need multiple acpi |
415 |
+ readers, ensure acpid is in your default runlevel along with HAL. This |
416 |
+ will also enable HAL to read Toshia and IBM acpi events which do not |
417 |
+ get sent via /proc/acpi/event</flag> |
418 |
+ <flag name='crypt'>Allows HAL to mount volumes that are encrypted using |
419 |
+ LUKS. <pkg>sys-fs/cryptsetup-luks</pkg> which has recently been renamed |
420 |
+ to <pkg>sys-fs/cryptsetup</pkg> allows you to create such encrypted |
421 |
+ volumes. HAL will be able to handle volumes that are removable or |
422 |
+ fixed.</flag> |
423 |
+ <flag name='dell'>Builds an installs the Dell addon, which reads data from |
424 |
+ the Dell SM BIOS via <pkg>sys-libs/libsmbios</pkg>. It will read your |
425 |
+ service tag information and your hardware backlight data as well as |
426 |
+ allow you to modify the backlight settings on a Dell laptop.</flag> |
427 |
+ <flag name='disk-partition'>Allows HAL to use libparted from |
428 |
+ <pkg>sys-apps/parted</pkg> to read raw partition data from your disks |
429 |
+ and process that data. Future versions of HAL (possibly 0.5.11 and |
430 |
+ higher) will allow you to create, modify, delete and format partitions |
431 |
+ from a GUI interface agnostic of your desktop environment.</flag> |
432 |
+ <flag name='doc'>Generates documentation that describes HAL's fdi |
433 |
+ format.</flag> |
434 |
+ <flag name='pcmcia'>Allows HAL to process PCMCIA/CardBus slot data which |
435 |
+ includes inserts and removals and act on these events.</flag> |
436 |
+ <flag name='selinux'>Installs SELinux policies and links HAL to the SELinux |
437 |
+ libraries.</flag> |
438 |
+</use> |
439 |
+</pkgmetadata> |
440 |
+</codesample> |
441 |
+ |
442 |
+</body> |
443 |
+</subsection> |
444 |
+<subsection> |
445 |
+<title>Fourth Example</title> |
446 |
+<body> |
447 |
+ |
448 |
+<p> |
449 |
+This example demonstrates the usage of the upstream element: |
450 |
+</p> |
451 |
+ |
452 |
+<codesample lang="sgml"> |
453 |
+<upstream> |
454 |
+ <maintainer status="inactive"> |
455 |
+ <name>Foo Bar</name> |
456 |
+ <email>foo@×××.bar</email> |
457 |
+ </maintainer> |
458 |
+ <maintainer status="active"> |
459 |
+ <name>Foo Gentoo</name> |
460 |
+ <email>foo@g.o</email> |
461 |
</maintainer> |
462 |
- <longdescription lang="en"> |
463 |
- HAL provides a view of the various hardware attached to a system. |
464 |
- In addition to this, HAL keeps detailed metadata for each piece of |
465 |
- hardware and provide hooks such that system- and desktop-level software |
466 |
- can react to changes in the hardware configuration in order to maintain |
467 |
- system policy. |
468 |
- </longdescription> |
469 |
- <use> |
470 |
- <flag name="laptop">Adds support for power management scripts |
471 |
- (<pkg>sys-power/pm-utils</pkg>)</flag> |
472 |
- <flag name="selinux">Installs SELinux policies and links HAL to the SELinux |
473 |
- libraries.</flag> |
474 |
- </use> |
475 |
- </pkgmetadata> |
476 |
+ <changelog>http://foo.bar/changelog.txt</changelog> |
477 |
+ <doc lang="en">http://foo.bar/doc/index.html</doc> |
478 |
+ <doc lang="de">http://foo.bar/doc/index.de.html</doc> |
479 |
+ <bugs-to>https://bugs.foo.bar</bugs-to> |
480 |
+ <remote-id type="freshmeat">foobar</remote-id> |
481 |
+ <remote-id type="sourceforge">foobar</remote-id> |
482 |
+</upstream> |
483 |
</codesample> |
484 |
|
485 |
+</body> |
486 |
+</subsection> |
487 |
+ |
488 |
+ |
489 |
<p> |
490 |
All new packages <b>must</b> include a <c>metadata.xml</c> file. That file |
491 |
should specify at least one herd or one maintainer. It is however recommended, |
492 |
@@ -67,7 +488,6 @@ should ensure that you have <c>dev-libs/libxml2</c> installed so that |
493 |
the XML can be validated. |
494 |
</p> |
495 |
|
496 |
-</body> |
497 |
</section> |
498 |
|
499 |
<section> |