Gentoo Attachment #137127 for bug #199788

View | Details | Raw Unified
Collapse All | Expand All

(-) hb-guide-metadata.xml?rev=1.9 (-18 / +113 lines)

Lines 10-17	Link Here

-->

-->

<sections>

<sections>

<version>1.0.4</version>

<version>1.0.5</version>

<date>2007-07-31</date>

<date>2007-11-27</date>

<section>

<section>

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

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

Lines 19-32	Link Here

<body>

<body>

<p>

<p>

The <c>metadata.xml</c> file has as its purpose to give extra information about

The <path>metadata.xml</path> file has as its purpose to give extra information about

ebuilds. The <c>metadata.xml</c> file should exist in every package directory.

ebuilds. The <path>metadata.xml</path> file should exist in every package directory.

A skel file can be found as <c>skel.metadata.xml</c> in the portage tree.

A skel file can be found as <path>skel.metadata.xml</path> in the root of the portage tree.

</p>

</p>

<note>

<note>

Please run <c>xmllint --valid metadata.xml</c> before committing a

Please run <c>xmllint --valid --noout metadata.xml</c> before committing a

<c>metadata.xml</c> file.  We hope to add support for <c>metadata.xml</c> to

<path>metadata.xml</path> file.  We hope to add support for <path>metadata.xml</path> to

repoman soon.

repoman soon.

</note>

</note>

Lines 40-46	Link Here

<body>

<body>

<p>

<p>

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

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

</p>

</p>

<table>

<table>

Lines 53-59	Link Here

    <brite>&lt;pkgmetadata&gt;</brite>

    <brite>&lt;pkgmetadata&gt;</brite>

  </ti>

  </ti>

  <ti>

  <ti>

    This is the root element of the metadata.xml file for packages. It has

    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>.

    no attributes. Its required subtag is: <brite>&lt;herd&gt;</brite>.

    Furthermore, the following subtags are allowed: <brite>&lt;email&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

    for a general herd email address, <brite>&lt;maintainer&gt;</brite>, and

Lines 65-71	Link Here

    <brite>&lt;catmetadata&gt;</brite>

    <brite>&lt;catmetadata&gt;</brite>

  </ti>

  </ti>

  <ti>

  <ti>

    This is the root element of the metadata.xml file for categories as per

    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

    <uri link="/proj/en/glep/glep-0034.html">GLEP 34</uri>. It has

    no attributes. It contains a number of

    no attributes. It contains a number of

    <brite>&lt;longdescription&gt;</brite> tags, each for a different

    <brite>&lt;longdescription&gt;</brite> tags, each for a different

Lines 119-125	Link Here

  <ti><brite>&lt;longdescription&gt;</brite></ti>

  <ti><brite>&lt;longdescription&gt;</brite></ti>

  <ti>

  <ti>

    This tag contains a description of the package. This is to augment the

    This tag contains a description of the package. This is to augment the

    DESCRIPTION field in the ebuilds themselves.

    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>

  </ti>

</tr>

</tr>

</table>

</table>

Lines 138-144	Link Here

<tr>

<tr>

  <ti>lang</ti>

  <ti>lang</ti>

  <ti>

  <ti>

    <brite>&lt;description&gt;</brite>, <brite>&lt;longdescription&gt;</brite>

    <brite>&lt;description&gt;</brite>, <brite>&lt;longdescription&gt;</brite>, <brite>&lt;use&gt;</brite>

  </ti>

  </ti>

  <ti>

  <ti>

    In every case where a description is required, there must be at

    In every case where a description is required, there must be at

Lines 153-159	Link Here

  <ti>restrict</ti>

  <ti>restrict</ti>

  <ti>

  <ti>

    <brite>&lt;herd&gt;</brite>, <brite>&lt;maintainer&gt;</brite>,

    <brite>&lt;herd&gt;</brite>, <brite>&lt;maintainer&gt;</brite>,

    <brite>&lt;longdescription&gt;</brite>

    <brite>&lt;longdescription&gt;</brite>, <brite>&lt;flag&gt;</brite>

  </ti>

  </ti>

  <ti>

  <ti>

    The restrict attribute allows to restrict the application of certain tags

    The restrict attribute allows to restrict the application of certain tags

Lines 163-172	Link Here

    is that of the DEPEND flag, except that "&lt;" and

    is that of the DEPEND flag, except that "&lt;" and

    "&gt;" need to be specified by &amp;lt; and &amp;gt;.<br />

    "&gt;" need to be specified by &amp;lt; and &amp;gt;.<br />

    <br />

    <br />

    For example in the db package

    For example in the <c>sys-libs/db</c> package,

    <c>restrict="&amp;gt;=sys-libs/db-3.2.9-r5"</c>

    <c>restrict="&gt;=sys-libs/db-3.2.9-r5"</c>

    on the maintainer tag shows that I'm currently maintaining all versions

    on the <brite>&lt;maintainer&gt;</brite> tag shows that I'm currently maintaining all versions

    bigger then 3.2.9-r5.

    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>

  </ti>

</tr>

</tr>

</table>

</table>

Lines 237-243	Link Here

<body>

<body>

<p>

<p>

As second example we view the <path>metadata.xml</path> of <c>mirrorselect</c>.

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

This ebuild is maintained by the <c>tools-portage</c> herd, but has a separate

maintainer.

maintainer.

</p>

</p>

Lines 260-264	Link Here

</body>

</body>

</subsection>

</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>

</section>

</sections>

</sections>

Attachment #137127: Developer Handbook Metadata.xml Documentation Updates for bug #199788