Gentoo Development Guide
Package and Category metadata.xml
The metadata.xml file is used to specify additional data about a
package or category.
Package Metadata
For packages, metadata.xml can specify a long description and
maintainer information. If a long description in any language is
provided, an English long description must be present. A typical
example might look like:
A metadata.xml file can contain a number of tags:
| tag | description |
| <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. |
There are also some attributes that can be used with these tags. They are all optional:
| attribute | tags | description |
| 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. |
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:
Note
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>
Category Metadata
For categories, metadata.xml specifies a long description (in
English and optionally in other languages). The format is specified
formally in
GLEP 34, and the character set must be UTF-8 as specified
by GLEP
31. A typical example:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE catmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
<catmetadata>
<longdescription lang="en">
The app-vim category contains plugins and syntax file
packages for the Vim text editor.
</longdescription>
<longdescription lang="de">
Die Kategorie app-vim enthält Plugins und Syntax-Pakete
für den Vim Texteditor.
</longdescription>
</catmetadata>
When creating a new category, creating a metadata.xml file
along with a <longdescription> in English is
mandatory. Translations are handled by any interested developer
who speaks a language sufficiently well.
The correct way to commit a category metadata.xml file
is currently:
xmllint --noout --valid metadata.xml glep31check metadata.xml cvs commit -m "Adding category metadata.xml for my-category" metadata.xml
