Introduction au fichier de définition de package package.xml

La balise de premier niveau composant un fichier package.xml est la balise <package version="1.0">. Les balises de sous niveau permises sont :

• <name>: le nom du package.

• <summary>: courte description du package

• <description>: description complète du package

• <license>: la licence du package (LGPL, PHP License etc.).

• <maintainers>: Information sur les gestionnaires du package

  • maintainer: Information sur un gestionnaire. (peut être utilisée plusieurs fois.)

    • <user>: Le nom du compte utilisateur.

    • <role>: Le rôle de l'utilisateur pendant le développement du package (lead, developer ou helper.)

    • <name>: Le vrai nom de l'utilisateur.

    • <email>: L'adresse email de l'utilisateur.

• <release>: Informations sur la version courante.

  • <version>: Numéro de version courante.

  • <state>: L'état de la version (stable, beta, alpha, devel, ou snapshot.)

  • <date>: La date de création de la version.

  • <license>: La license sous laquelle le code est disponible.

  • <notes>: Notes

  • <filelist>

    • <file name="xxx" role="xxx" />: Nom du fichier

    • <dir name="xxx" [role="xxx"]>: Nom d'un sous répertoire. Ce sous répertoire peut contenir des éléments <file role="xxx">.

    • <deps>: Liste des dépendances du package.

      • <dep type="xxx" rel="yyy" optional="yes">name</dep> : Pour plus d'informations sur les dépendances, lisez la section suivante.

  • <changelog>: Informations de changelog sur le package.

    • <release>

      • <version>: Numéro de version courante.

      • <state>: L'état de la version. release.

      • <date>: Date de création

      • <notes>: Informations de changelog

Les lettres autorisés dans les éléments sont A-Z et a-z. Les autres caractères, comme é doivent être remplacés par leurs entités (dans ce cas : &eacute;).

Si vous créez votre fichier package.xml en utilisant le PEAR_PackageFileManager, mettez à jour votre installation de PEAR à la version 1.4.0a2 ou supérieure et vous n'aurez plus à vous souciez de cela car le gestionnaire de fichier s'occupe de cela automatiquement.

Si vous écrivez vos fichiers package.xml manuellement, vous devrez entrer les entités vous-même. Une liste des entités les plus communes peut être trouvée sur : http://www.evolt.org/article/A_Simple_Character_Entity_Chart/17/21234/. Si le caractère dont vous avez besoin n'est pas dans cette liste, allez sur http://www.oasis-open.org/docbook/xmlcharent/0.1/index.shtml et cherchez sur les autres listes d'entités.

Pour valider vos fichiers package.xml, vous pouvez utiliser l'utilitaire xmllint fourni avec libxml2.

xmllint --dtdvalid http://pear.php.net/dtd/package-1.0 --noout package.xml

<?xml version="1.0" encoding="ISO-8859-1" ?>
<package version="1.0">
 <name>argent_facile</name>
 <summary>faites de l'argent facile</summary>
 <description>
  Ce package vous aide à faire de l'argent facile.
 </description>
 <license>PHP License</license>
 <maintainers>
  <maintainer>
   <user>foo</user>
   <name>Joe Foo</name>
   <email>[email protected]</email>
   <role>lead</role>
  </maintainer>
 </maintainers>

 <release>
  <version>1.0</version>
  <date>2002-05-27</date>
  <state>stable</state>
  <notes>
   Ceci est la première version.
  </notes>
  <filelist>
   <dir name="/" baseinstalldir="Argent">
    <file role="php" name="Fast.php" />
   </dir>
  </filelist>
 </release>
</package>

Ce fichier package.xml peut vous servir de modèle. Il contient tous les éléments nécessaires. Il vous suffit de changer les textes pour vous en servir avec votre package.

<?xml version="1.0" encoding="ISO-8859-1" ?>

[...]

 <release>
  <version>1.0</version>
  <date>2002-07-23</date>
  <state>stable</state>
  <notes>
   Ceci est la première version.
  </notes>
  <filelist>
   <dir name="/" baseinstalldir="Argent">
    <file role="php" name="Fast.php" />
    <dir name="Calculator">
     <file name="Calculator.php" role="php" />
     <file name="Currency.php" role="php" />
     <file name="Stocks.php" role="php" />
    </dir>
    <dir name="docs" role="doc">
     <file name="README.txt" role="doc" />
     <file name="tutorial.txt" role="doc" />
     <dir name="examples">
      <file name="NASDAQ.php" role="php" />
      <file name="DAX.php" role="php" />
     </dir>
   </dir>
  </filelist>
 </release>
</package>

Dans cet exemple, nous pouvons découvrir une caractéristique intéressante: Lorsqu'un répertoire de votre package ne contient que des fichiers du même type, vous pouvez utiliser l'attribut rôle directement dans la balise <dir> au lieu de l'ajouter à chaque balise <file>.

Avec les connaissances que vous venez d'acquérir sur ce chapitre, vous devriez maintenant être capable de créer un fichier de définition pour votre package. Si vous avez des questions à ce sujet, n'hésitez pas à les poser sur la mailinglist.

L'attribut role dans la balise <file> définit le type du fichier et l'endroit où il devrait être installé.

Le gestionnaire de package PEAR permet de vérifier les différentes caractéristiques du système. Il vous est possible de définir des dépendances avec la balise <dep>:

<?xml version="1.0" encoding="ISO-8859-1" ?>

[...]
 </release>
 <deps>
  <dep type="php" rel="ge" version="4.3.0" />
  <dep type="pkg" rel="has" version="1.0">XML_Parser</dep>
 </deps>
</package>

      
       $ pear install <package>
       Optional dependencies:
       Package `XML_Tree' is recommended to utilize some features.
       Package `MDB' is recommended to utilize some features.