Attachment #137127 for bug #199788




-->

<sections>
<version>1.0.5</version>
<date>2007-11-27</date>

<section>
<title>Why the need for metadata.xml?</title>

<body>

<p>
The <path>metadata.xml</path> file has as its purpose to give extra information about
ebuilds. The <path>metadata.xml</path> file should exist in every package directory.
A skel file can be found as <path>skel.metadata.xml</path> in the root of the portage tree.
</p>

<note>
Please run <c>xmllint --valid --noout metadata.xml</c> before committing a
<path>metadata.xml</path> file.  We hope to add support for <path>metadata.xml</path> to 
repoman soon.
</note>


<body>

<p>
A <path>metadata.xml</path> file can contain a number of tags:
</p>

<table>

    <brite>&lt;pkgmetadata&gt;</brite>
  </ti>
  <ti>
    This is the root element of the <path>metadata.xml</path> file for packages. It has 
    no attributes. Its required subtag is: <brite>&lt;herd&gt;</brite>. 
    Furthermore, the following subtags are allowed: <brite>&lt;email&gt;</brite> 
    for a general herd email address, <brite>&lt;maintainer&gt;</brite>, and 

    <brite>&lt;catmetadata&gt;</brite>
  </ti>
  <ti>
    This is the root element of the <path>metadata.xml</path> file for categories as per 
    <uri link="/proj/en/glep/glep-0034.html">GLEP 34</uri>. It has 
    no attributes. It contains a number of 
    <brite>&lt;longdescription&gt;</brite> tags, each for a different 

  <ti><brite>&lt;longdescription&gt;</brite></ti>
  <ti>
    This tag contains a description of the package. This is to augment the 
    DESCRIPTION field in the ebuilds themselves. This tag has one optional
    subtag: <brite>&lt;pkg&gt;</brite>.
  </ti>
</tr>
<tr>
  <ti><brite>&lt;use&gt;</brite></ti>
  <ti>
    This tag contains descriptions of <uri 
      link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE flags</uri>.
    This tag is optional and, if specified, has one required subtag:
    <brite>&lt;flag&gt;</brite>.
  </ti>
</tr>
<tr>
  <ti><brite>&lt;flag&gt;</brite></ti>
  <ti>
    This tag contains a description of how the named USE flag affects this
    package. It is required if the <brite>&lt;use&gt;</brite> tag is specified.
    It also requires the USE flag to be named in the <c>name</c> attribute.
    This tag has one optional subtag: <brite>&lt;pkg&gt;</brite>.
  </ti>
</tr>
<tr>
  <ti><brite>&lt;pkg&gt;</brite></ti>
  <ti>
    This tag contains a package name in the format of category/package. For
    example, <c>&lt;pkg&gt;sys-apps/hal&lt;/pkg&gt;</c>.
  </ti>
</tr>
</table>

<tr>
  <ti>lang</ti>
  <ti>
    <brite>&lt;description&gt;</brite>, <brite>&lt;longdescription&gt;</brite>, <brite>&lt;use&gt;</brite>
  </ti>
  <ti>
    In every case where a description is required, there must be at

  <ti>restrict</ti>
  <ti>
    <brite>&lt;herd&gt;</brite>, <brite>&lt;maintainer&gt;</brite>, 
    <brite>&lt;longdescription&gt;</brite>, <brite>&lt;flag&gt;</brite>
  </ti>
  <ti>
    The restrict attribute allows to restrict the application of certain tags 

    is that of the DEPEND flag, except that "&lt;" and 
    "&gt;" need to be specified by &amp;lt; and &amp;gt;.<br />
    <br />
    For example in the <c>sys-libs/db</c> package,
    <c>restrict="&gt;=sys-libs/db-3.2.9-r5"</c> 
    on the <brite>&lt;maintainer&gt;</brite> tag shows that I'm currently maintaining all versions 
    greater than <c>3.2.9-r5</c>.
  </ti>
</tr>
<tr>
  <ti>name</ti>
  <ti>
    <brite>&lt;name&gt;</brite>
  </ti>
  <ti>
    This attribute is required on the <brite>&lt;flag&gt;</brite> tag. It
    simply contains the USE flag.
    <br /><br />
    For example in the sys-apps/hal package,
    <c>&lt;flag name='acpi'&gt;Enables ACPI (longer description in the actual file)&lt;/flag&gt;</c>
  </ti>
</tr>
</table>

<body>

<p>
For the second example, we view the <path>metadata.xml</path> of <c>app-portage/mirrorselect</c>.
This ebuild is maintained by the <c>tools-portage</c> herd, but has a separate
maintainer.
</p>


</body>
</subsection>
<subsection>
<title>Third Example</title>
<body>

<p>
For the third example, we will describe the <path>metadata.xml</path> of
<c>sys-apps/hal</c>. This ebuild is maintained by the <c>gentopia</c> herd
and contains USE flag descriptions.
</p>
<pre caption="USE flag descriptions">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"&gt;
&lt;pkgmetadata&gt;
&lt;herd&gt;gentopia&lt;/herd&gt;
&lt;maintainer&gt;
    &lt;email&gt;cardoe@gentoo.org&lt;/email&gt;
&lt;/maintainer&gt;
&lt;maintainer&gt;
    &lt;email&gt;steev@gentoo.org&lt;/email&gt;
&lt;/maintainer&gt;
&lt;maintainer&gt;
    &lt;email&gt;compnerd@gentoo.org&lt;/email&gt;
&lt;/maintainer&gt;
&lt;use&gt;
    &lt;flag name='acpi'&gt;Enables HAL to attempt to read from /proc/acpi/event, if
        unavailable, HAL will read events from &lt;pkg&gt;sys-power/acpid&lt;/pkg&gt;. If
        you need multiple acpi readers, ensure acpid is in your default
        runlevel (rc-update add acpid default) along with HAL. This will also
        enable HAL to read Toshiba and IBM acpi events which do not get sent
        via /proc/acpi/event&lt;/flag&gt;
    &lt;flag name='crypt'&gt;Allows HAL to mount volumes that are encrypted using
        LUKS. &lt;pkg&gt;sys-fs/cryptsetup-luks&lt;/pkg&gt; which has recently been renamed
        to &lt;pkg&gt;sys-fs/cryptsetup&lt;/pkg&gt; allows you to create such encrypted
        volumes. HAL will be able to handle volumes that are removable or
        fixed.&lt;/flag&gt;
    &lt;flag name='dell'&gt;Builds an installs the Dell addon, which reads data from
        the Dell SM BIOS via &lt;pkg&gt;sys-libs/libsmbios&lt;/pkg&gt;. It will read your
        service tag information and your hardware backlight data as well as
        allow you to modify the backlight settings on a Dell laptop.&lt;/flag&gt;
    &lt;flag name='disk-partition'&gt;Allows HAL to use libparted from
        &lt;pkg&gt;sys-apps/parted&lt;/pkg&gt; to read raw partition data from your disks
        and process that data. Future versions of HAL (possibly 0.5.11 and
        higher) will allow you to create, modify, delete and format partitions
        from a GUI interface agnostic of your desktop environment.&lt;/flag&gt;
    &lt;flag name='doc'&gt;Generates documentation that describes HAL's fdi
        format.&lt;/flag&gt;
    &lt;flag name='pcmcia'&gt;Allows HAL to process PCMCIA/CardBus slot data which
        includes inserts and removals and act on these events.&lt;/flag&gt;
    &lt;flag name='selinux'&gt;Installs SELinux policies and links HAL to the SELinux
        libraries.&lt;/flag&gt;
&lt;/use&gt;
&lt;/pkgmetadata&gt;
</pre>

</body>
</subsection>
</section>
</sections>

Return to bug 199788

Lines 10-17 Link Here

(-)hb-guide-metadata.xml?rev=1.9 (-18 / +113 lines)
10	-->	10	-->
11		11
12	<sections>	12	<sections>
13	<version>1.0.4</version>	13	<version>1.0.5</version>
14	<date>2007-07-31</date>	14	<date>2007-11-27</date>
15		15
16	<section>	16	<section>
17	<title>Why the need for metadata.xml?</title>	17	<title>Why the need for metadata.xml?</title>
Lines 19-32 Link Here
19	<body>	19	<body>
20		20
21	<p>	21	<p>
22	The <c>metadata.xml</c> file has as its purpose to give extra information about	22	The <path>metadata.xml</path> file has as its purpose to give extra information about
23	ebuilds. The <c>metadata.xml</c> file should exist in every package directory.	23	ebuilds. The <path>metadata.xml</path> file should exist in every package directory.
24	A skel file can be found as <c>skel.metadata.xml</c> in the portage tree.	24	A skel file can be found as <path>skel.metadata.xml</path> in the root of the portage tree.
25	</p>	25	</p>
26		26
27	<note>	27	<note>
28	Please run <c>xmllint --valid metadata.xml</c> before committing a	28	Please run <c>xmllint --valid --noout metadata.xml</c> before committing a
29	<c>metadata.xml</c> file. We hope to add support for <c>metadata.xml</c> to	29	<path>metadata.xml</path> file. We hope to add support for <path>metadata.xml</path> to
30	repoman soon.	30	repoman soon.
31	</note>	31	</note>
32		32
Lines 40-46 Link Here
40	<body>	40	<body>
41		41
42	<p>	42	<p>
43	A <c>metadata.xml</c> file can contain a number of tags:	43	A <path>metadata.xml</path> file can contain a number of tags:
44	</p>	44	</p>
45		45
46	<table>	46	<table>
Lines 53-59 Link Here
53	<brite><pkgmetadata></brite>	53	<brite><pkgmetadata></brite>
54	</ti>	54	</ti>
55	<ti>	55	<ti>
56	This is the root element of the metadata.xml file for packages. It has	56	This is the root element of the <path>metadata.xml</path> file for packages. It has
57	no attributes. Its required subtag is: <brite><herd></brite>.	57	no attributes. Its required subtag is: <brite><herd></brite>.
58	Furthermore, the following subtags are allowed: <brite><email></brite>	58	Furthermore, the following subtags are allowed: <brite><email></brite>
59	for a general herd email address, <brite><maintainer></brite>, and	59	for a general herd email address, <brite><maintainer></brite>, and
Lines 65-71 Link Here
65	<brite><catmetadata></brite>	65	<brite><catmetadata></brite>
66	</ti>	66	</ti>
67	<ti>	67	<ti>
68	This is the root element of the metadata.xml file for categories as per	68	This is the root element of the <path>metadata.xml</path> file for categories as per
69	<uri link="/proj/en/glep/glep-0034.html">GLEP 34</uri>. It has	69	<uri link="/proj/en/glep/glep-0034.html">GLEP 34</uri>. It has
70	no attributes. It contains a number of	70	no attributes. It contains a number of
71	<brite><longdescription></brite> tags, each for a different	71	<brite><longdescription></brite> tags, each for a different
Lines 119-125 Link Here
119	<ti><brite><longdescription></brite></ti>	119	<ti><brite><longdescription></brite></ti>
120	<ti>	120	<ti>
121	This tag contains a description of the package. This is to augment the	121	This tag contains a description of the package. This is to augment the
122	DESCRIPTION field in the ebuilds themselves.	122	DESCRIPTION field in the ebuilds themselves. This tag has one optional
		123	subtag: <brite><pkg></brite>.
		124	</ti>
		125	</tr>
		126	<tr>
		127	<ti><brite><use></brite></ti>
		128	<ti>
		129	This tag contains descriptions of <uri
		130	link="/doc/en/handbook/handbook-x86.xml?part=2&chap=2">USE flags</uri>.
		131	This tag is optional and, if specified, has one required subtag:
		132	<brite><flag></brite>.
		133	</ti>
		134	</tr>
		135	<tr>
		136	<ti><brite><flag></brite></ti>
		137	<ti>
		138	This tag contains a description of how the named USE flag affects this
		139	package. It is required if the <brite><use></brite> tag is specified.
		140	It also requires the USE flag to be named in the <c>name</c> attribute.
		141	This tag has one optional subtag: <brite><pkg></brite>.
		142	</ti>
		143	</tr>
		144	<tr>
		145	<ti><brite><pkg></brite></ti>
		146	<ti>
		147	This tag contains a package name in the format of category/package. For
		148	example, <c><pkg>sys-apps/hal</pkg></c>.
123	</ti>	149	</ti>
124	</tr>	150	</tr>
125	</table>	151	</table>
Lines 138-144 Link Here
138	<tr>	164	<tr>
139	<ti>lang</ti>	165	<ti>lang</ti>
140	<ti>	166	<ti>
141	<brite><description></brite>, <brite><longdescription></brite>	167	<brite><description></brite>, <brite><longdescription></brite>, <brite><use></brite>
142	</ti>	168	</ti>
143	<ti>	169	<ti>
144	In every case where a description is required, there must be at	170	In every case where a description is required, there must be at
Lines 153-159 Link Here
153	<ti>restrict</ti>	179	<ti>restrict</ti>
154	<ti>	180	<ti>
155	<brite><herd></brite>, <brite><maintainer></brite>,	181	<brite><herd></brite>, <brite><maintainer></brite>,
156	<brite><longdescription></brite>	182	<brite><longdescription></brite>, <brite><flag></brite>
157	</ti>	183	</ti>
158	<ti>	184	<ti>
159	The restrict attribute allows to restrict the application of certain tags	185	The restrict attribute allows to restrict the application of certain tags
Lines 163-172 Link Here
163	is that of the DEPEND flag, except that "<" and	189	is that of the DEPEND flag, except that "<" and
164	">" need to be specified by &lt; and &gt;.<br />	190	">" need to be specified by &lt; and &gt;.<br />
165	<br />	191	<br />
166	For example in the db package	192	For example in the <c>sys-libs/db</c> package,
167	<c>restrict="&gt;=sys-libs/db-3.2.9-r5"</c>	193	<c>restrict=">=sys-libs/db-3.2.9-r5"</c>
168	on the maintainer tag shows that I'm currently maintaining all versions	194	on the <brite><maintainer></brite> tag shows that I'm currently maintaining all versions
169	bigger then 3.2.9-r5.	195	greater than <c>3.2.9-r5</c>.
		196	</ti>
		197	</tr>
		198	<tr>
		199	<ti>name</ti>
		200	<ti>
		201	<brite><name></brite>
		202	</ti>
		203	<ti>
		204	This attribute is required on the <brite><flag></brite> tag. It
		205	simply contains the USE flag.
		206	<br /><br />
		207	For example in the sys-apps/hal package,
		208	<c><flag name='acpi'>Enables ACPI (longer description in the actual file)</flag></c>
170	</ti>	209	</ti>
171	</tr>	210	</tr>
172	</table>	211	</table>
Lines 237-243 Link Here
237	<body>	276	<body>
238		277
239	<p>	278	<p>
240	As second example we view the <path>metadata.xml</path> of <c>mirrorselect</c>.	279	For the second example, we view the <path>metadata.xml</path> of <c>app-portage/mirrorselect</c>.
241	This ebuild is maintained by the <c>tools-portage</c> herd, but has a separate	280	This ebuild is maintained by the <c>tools-portage</c> herd, but has a separate
242	maintainer.	281	maintainer.
243	</p>	282	</p>
Lines 260-264 Link Here
260		299
261	</body>	300	</body>
262	</subsection>	301	</subsection>
		302	<subsection>
		303	<title>Third Example</title>
		304	<body>
		305
		306	<p>
		307	For the third example, we will describe the <path>metadata.xml</path> of
		308	<c>sys-apps/hal</c>. This ebuild is maintained by the <c>gentopia</c> herd
		309	and contains USE flag descriptions.
		310	</p>
		311	<pre caption="USE flag descriptions">
		312	<?xml version="1.0" encoding="UTF-8"?>
		313	<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
		314	<pkgmetadata>
		315	<herd>gentopia</herd>
		316	<maintainer>
		317	<email>cardoe@gentoo.org</email>
		318	</maintainer>
		319	<maintainer>
		320	<email>steev@gentoo.org</email>
		321	</maintainer>
		322	<maintainer>
		323	<email>compnerd@gentoo.org</email>
		324	</maintainer>
		325	<use>
		326	<flag name='acpi'>Enables HAL to attempt to read from /proc/acpi/event, if
		327	unavailable, HAL will read events from <pkg>sys-power/acpid</pkg>. If
		328	you need multiple acpi readers, ensure acpid is in your default
		329	runlevel (rc-update add acpid default) along with HAL. This will also
		330	enable HAL to read Toshiba and IBM acpi events which do not get sent
		331	via /proc/acpi/event</flag>
		332	<flag name='crypt'>Allows HAL to mount volumes that are encrypted using
		333	LUKS. <pkg>sys-fs/cryptsetup-luks</pkg> which has recently been renamed
		334	to <pkg>sys-fs/cryptsetup</pkg> allows you to create such encrypted
		335	volumes. HAL will be able to handle volumes that are removable or
		336	fixed.</flag>
		337	<flag name='dell'>Builds an installs the Dell addon, which reads data from
		338	the Dell SM BIOS via <pkg>sys-libs/libsmbios</pkg>. It will read your
		339	service tag information and your hardware backlight data as well as
		340	allow you to modify the backlight settings on a Dell laptop.</flag>
		341	<flag name='disk-partition'>Allows HAL to use libparted from
		342	<pkg>sys-apps/parted</pkg> to read raw partition data from your disks
		343	and process that data. Future versions of HAL (possibly 0.5.11 and
		344	higher) will allow you to create, modify, delete and format partitions
		345	from a GUI interface agnostic of your desktop environment.</flag>
		346	<flag name='doc'>Generates documentation that describes HAL's fdi
		347	format.</flag>
		348	<flag name='pcmcia'>Allows HAL to process PCMCIA/CardBus slot data which
		349	includes inserts and removals and act on these events.</flag>
		350	<flag name='selinux'>Installs SELinux policies and links HAL to the SELinux
		351	libraries.</flag>
		352	</use>
		353	</pkgmetadata>
		354	</pre>
		355
		356	</body>
		357	</subsection>
263	</section>	358	</section>
264	</sections>	359	</sections>