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,10 +53,10 @@ <pkgmetadata> - 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 + 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 <longdescription>. @@ -65,10 +65,10 @@ <catmetadata> - 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 + 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 language. @@ -78,7 +78,7 @@ There must at least be one herd subtag. The contents of this tag must be - the name of a herd as specified in the herds.xml file or the "no-herd" herd. It must occur at least once. @@ -88,9 +88,9 @@ <maintainer> - Besides being member of a herd, a package can also be maintained directly. - The maintainers of a package can be specified with the - <maintainer> tag. This tag has one required subtag: + Besides being member of a herd, a package can also be maintained directly. + The maintainers of a package can be specified with the + <maintainer> tag. This tag has one required subtag: <email>. It has two optional subtags: <name>, and <description>. @@ -110,16 +110,42 @@ <description> - The description tag contains a description of the maintainership, or for - example a remark that someone interested can take over the maintainership. + The description tag contains a description of the maintainership, or for + example a remark that someone interested can take over the maintainership. It is optional. <longdescription> - This tag contains a description of the package. This is to augment the - DESCRIPTION field in the ebuilds themselves. + 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: <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,8 @@ lang - <description>, <longdescription> + <description>, <longdescription>, + <use> In every case where a description is required, there must be at @@ -152,21 +179,34 @@ restrict - <herd>, <maintainer>, - <longdescription> + <herd>, <maintainer>, + <longdescription>, <flag> - The restrict attribute allows to restrict the application of certain tags - to certain versions of a package. When this attribute is used, a tag - without this attribute must also exist. That tag without the restrict - attribute will serve as the default. The format of the restrict attribute - is that of the DEPEND flag, except that "<" and + The restrict attribute allows to restrict the application of certain tags + to certain versions of a package. When this attribute is used, a tag + without this attribute must also exist. That tag without the restrict + attribute will serve as the default. The format of the restrict attribute + 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> @@ -182,7 +222,7 @@

-In this first example we provide you with the metadata.xml for +In this first example we provide you with the metadata.xml for OpenOffice of which the ebuilds are completely managed by a herd called openoffice:

@@ -222,12 +262,13 @@

-If you want to add (or remove) yourself from a herd, edit herds.xml -located in [gentoo]/xml/htdocs/proj/en/metastructure/herds in Gentoo's CVS repository. Make sure you -know the e-mail alias the herd listens to (for instance the "sound" herd has -sound@gentoo.org) and add yourself to the -alias (by editing /var/mail/alias/misc/<alias name> on -dev.gentoo.org). +If you want to add (or remove) yourself from a herd, edit +herds.xml located in +[gentoo]/xml/htdocs/proj/en/metastructure/herds in Gentoo's CVS +repository. Make sure you know the e-mail alias the herd listens to (for +instance the "sound" herd has sound@gentoo.org) and add yourself +to the alias (by editing /var/mail/alias/misc/<alias name> +on dev.gentoo.org).

@@ -237,9 +278,9 @@

-As second example we view the metadata.xml of mirrorselect. -This ebuild is maintained by the tools-portage herd, but has a separate -maintainer. +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 +301,62 @@
 
 
 
+
+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>
+
+
+
+