Why the need for metadata.xml?

Why the need for metadata.xml? @@ -19,14 +19,14 @@

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

-Please run xmllint --valid metadata.xml before committing a -metadata.xml file. We hope to add support for metadata.xml to +Please run xmllint --valid --noout metadata.xml before committing a +metadata.xml file. We hope to add support for metadata.xml to repoman soon. @@ -40,7 +40,7 @@

-A metadata.xml file can contain a number of tags: +A metadata.xml file can contain a number of tags:

@@ -53,7 +53,7 @@ <pkgmetadata> - This is the root element of the metadata.xml file for packages. It has + This is the root element of the metadata.xml file for packages. It has no attributes. Its required subtag is: <herd>. Furthermore, the following subtags are allowed: <email> for a general herd email address, <maintainer>, and @@ -65,7 +65,7 @@ <catmetadata> - This is the root element of the metadata.xml file for categories as per + This is the root element of the metadata.xml file for categories as per GLEP 34. It has no attributes. It contains a number of <longdescription> tags, each for a different @@ -119,7 +119,33 @@ <longdescription> 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: <pkg>. + + + + <use> + + This tag contains descriptions of USE flags. + This tag is optional and, if specified, has one required subtag: + <flag>. + + + + <flag> + + This tag contains a description of how the named USE flag affects this + package. It is required if the <use> tag is specified. + It also requires the USE flag to be named in the name attribute. + This tag has one optional subtag: <pkg>. + + + + <pkg> + + This tag contains a package name in the format of category/package. For + example, <pkg>sys-apps/hal</pkg>.

@@ -138,7 +164,7 @@ lang - <description>, <longdescription> + <description>, <longdescription>, <use> In every case where a description is required, there must be at @@ -153,7 +179,7 @@ restrict <herd>, <maintainer>, - <longdescription> + <longdescription>, <flag> The restrict attribute allows to restrict the application of certain tags @@ -163,10 +189,23 @@ is that of the DEPEND flag, except that "<" and ">" need to be specified by < and >.

- For example in the db package - restrict=">=sys-libs/db-3.2.9-r5" - on the maintainer tag shows that I'm currently maintaining all versions - bigger then 3.2.9-r5. + For example in the sys-libs/db package, + restrict=">=sys-libs/db-3.2.9-r5" + on the <maintainer> tag shows that I'm currently maintaining all versions + greater than 3.2.9-r5. + + + + name + + <name> + + + This attribute is required on the <flag> tag. It + simply contains the USE flag. +

+ For example in the sys-apps/hal package, + <flag name='acpi'>Enables ACPI (longer description in the actual file)</flag> @@ -237,7 +276,7 @@

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

@@ -260,5 +299,61 @@ + +Third Example + + +

+For the third example, we will describe the metadata.xml of +sys-apps/hal. This ebuild is maintained by the gentopia herd +and contains USE flag descriptions. +

+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+<pkgmetadata>
+<herd>gentopia</herd>
+<maintainer>
+    <email>cardoe@gentoo.org</email>
+</maintainer>
+<maintainer>
+    <email>steev@gentoo.org</email>
+</maintainer>
+<maintainer>
+    <email>compnerd@gentoo.org</email>
+</maintainer>
+<use>
+    <flag name='acpi'>Enables HAL to attempt to read from /proc/acpi/event, if
+        unavailable, HAL will read events from <pkg>sys-power/acpid</pkg>. 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</flag>
+    <flag name='crypt'>Allows HAL to mount volumes that are encrypted using
+        LUKS. <pkg>sys-fs/cryptsetup-luks</pkg> which has recently been renamed
+        to <pkg>sys-fs/cryptsetup</pkg> allows you to create such encrypted
+        volumes. HAL will be able to handle volumes that are removable or
+        fixed.</flag>
+    <flag name='dell'>Builds an installs the Dell addon, which reads data from
+        the Dell SM BIOS via <pkg>sys-libs/libsmbios</pkg>. 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.</flag>
+    <flag name='disk-partition'>Allows HAL to use libparted from
+        <pkg>sys-apps/parted</pkg> 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.</flag>
+    <flag name='doc'>Generates documentation that describes HAL's fdi
+        format.</flag>
+    <flag name='pcmcia'>Allows HAL to process PCMCIA/CardBus slot data which
+        includes inserts and removals and act on these events.</flag>
+    <flag name='selinux'>Installs SELinux policies and links HAL to the SELinux
+        libraries.</flag>
+</use>
+</pkgmetadata>
+

+ + +