[ << ]
[ < ]
[ Home ]
[ > ]
[ >> ]
4. Gentoo Metadata
Content:
4.a. Why the need for metadata.xml?
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.
4.b. Metadata Structure
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. Its required subtag is:
<herd>. Furthermore, the following subtags are
allowed: <email> for a general herd email address,
<maintainer>,
<longdescription>,
<use>, and
<upstream>.
|
|
<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>
|
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.
|
|
<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 alos 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.
|
4.c. 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:
Code Listing 3.1: Herd-managed package |
<?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!
|
Code Listing 3.2: OpenOffice Herd 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.
Code Listing 3.3: Herd & individually maintained package |
<?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.
Code Listing 3.4: 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:
Code Listing 3.5: Upstream description |
<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>
|
[ << ]
[ < ]
[ Home ]
[ > ]
[ >> ]
The contents of this document are licensed under the Creative Commons -
Attribution / Share Alike license.
|
