1. Perché c'è il bisogno di metadata.xml
Il file metadata.xml ha lo scopo di fornire informazioni extra sulle ebuild. il file metadata.xml dovrebbe esistere nella directory di ogni pacchetto. Un file 'scheletro' può essere trovato come skel.metadata.xml nel portage tree.
Un file metadata.xml può contenere un certo numero di tag:
| tag | descrizione |
| <pkgmetadata> | Questo è l'elemento principale del file metadata.xml per i pacchetti. Non ha attributi. Il sottotag che richiede è: <herd>. Inoltre sono consentiti i seguenti tag: <email> per un'indirizzo email generico del gruppo, <maintainer>, e <longdescription>,<use>, e <upstream>. |
| <catmetadata> | Questo è l'elemento principale del file metadata.xml per le categorie, in base a GLEP 34. Non ha attributi, e contiene un certo numero di tag <longdescription>, ognuno per ogni lingua differente. |
| <herd> | Ci deve essere almeno un sottotag 'herd' (ndT 'gruppo', nel resto della guida verrà utilizzata questo termine). Il contenuto di questo tag deve corrispondere al nome di un gruppo così come specificato nel file herds.xml. oppure all'herd "no-herd". Deve essere presente almeno una volta. |
| <maintainer> | Oltre che far parte di un herd, un pacchetto può anche essere mantenuto direttamente. I responsabili di un pacchetto devono essere specificati con il tag <maintainer>. Questo tag richiede un sottotag: <email>. Ha due sottotag opzionali: <name>, e <description>. |
| <email> | Contiene l'indirizzo e-mail del responsabile del pacchetto. E' obbligatorio. |
| <name> | Contiene del testo libero con il nome del responsabile del pacchetto. E' opzionale. |
| <description> | Questo tag contiene una descrizione dello stato del pacchetto, o per esempio una nota indicante che se qualcuno è interessato può farsi carico del mantenimento del pacchetto. E' opzionale. |
| <longdescription> | Questo tag contiene una descrizione del pacchetto. Questo per aumentare il campo DESCRIPTION nelle ebuild. Questo tag ha due sottotag opzionali: <pkg> e <cat>. |
| <use> | Questo tag contiene le descrizione delle flag USE. Questo tag è opzionale e, se specificato, ha un sottotag richiesto: <flag>. |
| <flag> | Questo tag contiene una descrizione del modo in cui la flag USE menzionata influenza questo pacchetto. È richiesta se il tag <use> è specificato. Richiede inoltre che la flag USE sia nominata nell'attributo name. Questo tag ha due tag opzionali: <pkg> e <cat>. |
| <upstream> | Questo tag contiene informazioni riguardo il progetto/sviluppatori di origine ("upstream", NdT). |
| <maintainer> | Nome ed e-mail di un mantenitore "upstream". Tale tag può apparire più di una volta. |
| <name> | Il nome di un mantenitore "upstream" dovrebbe contenere un blocco di testo con il nome dell'upstream. Questo elemento è obbligatori per un mantenitore upstream e deve apparire solo una volta. |
| <email> | L'indirizzo email di un upstream dovrebbe apparire solo una volta. |
| <changelog> | Dovrebbe contenere un URL dov'è possibile reperire il changelog originale del pacchetto. L'URL deve essere indipendente dalla versione e deve puntare ad un changelog che viene aggiornato solamente sui nuovi rilasci del pacchetto corrispondente. (Ciò implica anche che uno può inserire un link ad un changelog aggiornato automaticamente solo un caso di snapshot vcs.) |
| <doc> | Dovrebbe contenere un URL dov'è può essere trovata la locazione della documentazione originale. Il link non deve puntare a nessuna documentazione di terze parti e deve essere indipendente dalla versione. Se la documentazione è disponibile in più di una lingua, può essere usato un attributo lang che segue le stesse regole di longdescription. |
| <bugs-to> | Dovrebbe contenere un luogo dove possono essere inseriti, un URL o indirizzo e-mail preceduto da mailto:. |
| <remote-id> | Dovrebbe specificare un tipo di indicatore di tracciamento del pacchetto e l'identificazione che corrisponde al pacchetto in questione. remote-id dovrebbe facilifare l'indicizzazione di informazioni come il proprio ID Freshmeat o nome CPAN. |
| <pkg> | Questo tag contiene un nome valido di pacchetto nel formato usato per DEPEND. |
| <cat> | Questo tag contiene un nome valido di categoria come definito in profiles/categories. |
Ci sono anche degli attributi che possono essere usati con questi tag. Sono tutti opzionali:
| attributo | tag | descrizione |
| lang | <description>,<longdescription>, <use>, <doc> | In ogni caso in cui sia richiesta una descrizione, ci deve essere almeno una descrizione in inglese. Se viene fornita una descrizione aggiuntiva in un'altra lingua, questo attributo viene utilizzato per specificare la lingua utilizzata. Il formato è quello di un codice a due caratteri in base alla lingua, come definito nella norma ISO-639-1. |
| restrict | <herd>, <maintainer>, <longdescription>, <flag> |
L'attributo restrict permette di limitare l'applicazione di alcuni tag a
determinate versioni del pacchetto. Quando questo attributo è utilizzato,
deve esistere anche un tag senza questo attributo. Il tag senza l'attributo
restrict verrà utilizzato come predefinito. Il formato dell'attributo
restrict è quello della flag DEPEND, eccetto che per "<" e per ">"
che devono essere specificati da < e >. Ad esempio, nel pacchetto sys-libs/db, restrict=">=sys-libs/db-3.2.9-r5" nel tag maintainer mostra che si stanno attualmente mantenendo tutte le versioni maggiori della 3.2.9-r5. |
| name | <flag> |
Questo attributo è richiesto sul tag <flag>. Contiene
semplicemente la flag USE.
Per esempio, nel pacchetto sys-apps/hal, <flag name='acpi'> Enables ACPI</flag> |
| status | <maintainer> | L'elemento upstream maintainer ha un attributo status, che può essere active ("attivo", NdT) o inactive ("inattivo", NdT). Questo attributo non è obbligatorio. La sua assenza può essere interpretata come informazione sconosciuta. Notare bene: Questo attributo è permesso solamente nell'elemento <upstream> <maintainer>! |
| type | <remote-id> | Una stringa di identificazione della sorgente "upstream". Una lista di stringhe valide viene tenuta all'interno di metadata.dtd. Gli sviluppatori dovrebbero inviare un'e-mail alla mailing list gentoo-dev prima di usare un nuovo tipo di valore. |
Nel primo esempio viene mostrato il metadata.xml di OpenOffice le cui ebuild sono completamente gestite da un gruppo chiamato openoffice:
Codice 1.1: Pacchetto mantenuto da un gruppo |
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE pkgmetadata SYSTEM "/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>
|
Il gruppo openoffice è definito nel file herds.xml dal Gentoo Metastructure Project:
Nota: Questo esempio potrà essere sorpassato quando verrà letto. E' solo un'esempio. |
Codice 1.1: Esempio Gruppo OpenOffice |
<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> |
Se ci si vuole aggiungere (o togliere) da un gruppo, modificare il file herds.xml che si trova in [gentoo]/xml/htdocs/proj/en/metastructure/herds nel repository CVS di Gentoo. Assicurarsi di conoscere l'alias e-mail corrispondente al gruppo (ad esempio il gruppo "sound" ha sound@gentoo.org) e aggiungersi all'alias (modificando /var/mail/alias/misc/<nome alias> su dev.gentoo.org).
Per il secondo esempio, verrà esaminato il file metadata.xml di app-portage/mirrorselect. Questa ebuild è mantenuta dall'herd tools-portage, ma ha un mantenitore distinto.
Codice 1.1: Pacchetto appartenente ad un Gruppo ma con Mantenitore distinto |
<?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>
|
Per il terzo esempio, verrà descritto il file metadata.xml di sys-apps/hal. Questa ebuild è mantenuta dall'herd gentopia e contiene le descrizione delle flag USE.
Codice 1.1: Descrizione flag USE |
<?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>
|
Questo esempio mostra l'uso dell'elemento upstream:
Codice 1.1: Descrizione per upstream |
<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>
|