Why the need for metadata.xml?

1.0.9 2012-04-27

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.

Metadata Structure

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

<pkgmetadata> This is the root element of the metadata.xml file for packages. It has no attributes. The following subtags are allowed: <herd>, <maintainer>, <longdescription>, <use>, and <upstream>. There should be at least one <herd> or <maintainer> subtag. <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 language. <herd> If a package is maintained by one or more herds, names of these herds can be specified with the <herd> tag. The names used in this tag must be the same as specified in the herds.xml file. <maintainer> Besides being part 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>. <email> This contains the e-mail address of the maintainer. It is required. <name> This contains freetext with the name of the maintainer. It is optional. <description> 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 has two optional subtags: <pkg> and <cat>. <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 two optional subtags: <pkg> and <cat>. <upstream> This tag contains information about the upstream developers/project. <maintainer> Name and e-mail of an upstream maintainer. May appear more than once. <name> The name of an upstream maintainer should contain a block of text with upstream's name. This element is mandatory for an upstream maintainer and must appear only once. <email> The email address of an upstream may appear only once. <changelog> Should contain a URL where the location of the upstream changelog can be found. The URL must be version independent and must point to a changelog which is only updated on new releases of the corresponding package. (This also implies that one can link to an automatically updated changelog in case of vcs snapshots only.) <doc> Should contain a URL where the location of the upstream documentation can be found. The link must not point to any third party documentation and must be version independent. If the documentation is available in more than one language, a lang attribute can be used which follows the same rules as the one for longdescription. <bugs-to> Should contain a place where bugs can be filed, a URL or an e-mail address prefixed with mailto:. <remote-id> Should specify a type of package identification tracker and the identification that corresponds to the package in question. remote-id should make it easier to index information such as its Freshmeat ID or its CPAN name. <pkg> This tag contains a valid package name in the format of a DEPEND. <cat> This tag contains a valid category name as defined in profiles/categories.

tag	description

There are also some attributes that can be used with these tags. They are all optional:

lang <description>, <longdescription>, <use>, <doc> In every case where a description is required, there must be at least an english description. If an additional description in another language is given, this attribute is used to specify the language used. The format is the two-character language code as defined by the ISO-639-1 norm. restrict <herd>, <maintainer>, <longdescription>, <flag> The restrict attribute allows one 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 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 then 3.2.9-r5. name <flag> 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</flag> status <maintainer> The upstream maintainer element has a status attribute, which is one of active or inactive. This attribute is not mandatory. The absence of it shall be interpreted as unknown. Please note: This attribute is only allowed in the <upstream> <maintainer> element! type <remote-id> A string identifying the type of upstream source. A list of valid strings are kept in metadata.dtd. Developers should email the gentoo-dev mailing list before using a new type value.

attribute	tags	description

Metadata Examples First Example

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:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
<pkgmetadata>
  <herd>openoffice</herd>
  <longdescription>
    OpenOffice is the  opensource version of staroffice.
    This ebuild allows you to compile it yourself. Unfortunately this
    compilation can take up to a day depending on the speed of your
    computer. It will however make a snappier openoffice than the binary
    version.
  </longdescription>
</pkgmetadata>

The openoffice herd is defined in herds.xml by the Gentoo Metastructure Project:

This example may be outdated when you read it. It's just an example!

<herd>
  <name>openoffice</name>
  <email>openoffice@gentoo.org</email>
  <description>Openoffice related packages</description>
  <maintainer><email>pauldv@gentoo.org</email></maintainer>
  <maintainer><email>suka@gentoo.org</email></maintainer>
</herd>

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

Second Example

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

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
<pkgmetadata>
  <herd>tools-portage</herd>
  <maintainer>
    <email>johnm@gentoo.org</email>
    <name>John Mylchreest</name>
  </maintainer>
  <longdescription>
    This utility is used to select the fastest mirror (distfiles) and provide a
    nicer front-end for mirror selection (both rsync + distfiles) to a user.
  </longdescription>
</pkgmetadata>

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>compnerd@gentoo.org</email>
</maintainer>
<maintainer>
	<email>steev@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 along with HAL. This
	will also enable HAL to read Toshia 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>

Fourth Example

This example demonstrates the usage of the upstream element:

<upstream>
        <maintainer status="inactive">
                <name>Foo Bar</name>
                <email>foo@bar.bar</email>
        </maintainer>
        <maintainer status="active">
                <name>Foo Gentoo</name>
                <email>foo@gentoo.org</email>
        </maintainer>
        <changelog>http://foo.bar/changelog.txt</changelog>
        <doc lang="en">http://foo.bar/doc/index.html</doc>
        <doc lang="de">http://foo.bar/doc/index.de.html</doc>
        <bugs-to>https://bugs.foo.bar</bugs-to>
        <remote-id type="freshmeat">foobar</remote-id>
        <remote-id type="sourceforge">foobar</remote-id>
</upstream>