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

package.xml version 1.0 est obsolète

package.xml 1.0 est obsolète, utilisez plutôt package.xml version 2.0, la documentation peut être trouvée sur la page package.xml 2.0.

Le fichier de définition de package package.xml est, comme son nom l'indique, un fichier XML contenant toutes les informations sur le package PEAR.

Ce chapitre va décrire les éléments composant un fichier de définition et les procédures permettant de créer un tel fichier pour votre package.

Le package PEAR_PackageFileManager simplifie la création de fichier de description. Vous pouvez installer PEAR_PackageFileManager gâce à la commande

      
$ pear install PEAR_PackageFileManager
      
     

Balises à utiliser

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

Caractères autorisés

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.

Validation

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

Créer un fichier de définition de package

package.xml de base

<?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>foo@example.com</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.

Exemple pour des sous répertoires

<?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

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

Valeurs possibles
Valeur répertoire de destination
php fichier source PHP le répertoire est défini par le nom du package
ext Extension, librairie dynamique Le répertoire des extensions PHP ou PHP_PEAR_EXTENSION_DIR si il est défini
doc Fichier de documentation {PEAR_documentation_dir}/Nom_Du_package/
data Fichiers de données du package (graphiques, tables de données, etc) {PEAR_data_dir}/Nom_Du_package/
test Fichiers de tests du package (tests unitaires, etc) {PEAR_test_dir}/Nom_Du_package/
script Scripts shell du package Le répertoire des binaires de PHP ou PHP_PEAR_BIN_DIR si il est défini
src and extsrc Code source C ou C++ Pas copiés directement - utilisés pour créer une extension

Définir les dépendances

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>:

Dépendances du package package.xml

L'exemple suivant montre comment spécifier des dépendances pour XML_Parser 1.0. avec PHP 4.3.0 ou supérieur.

<?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>

L'attribut type

Les types suivants sont acceptés:

valuers pour type
Valeur description Exemple
pkg Package dépendant d'un package donné "HTML_Flexy"
ext Extension dépendant d'une extension PHP "curl"
php PHP dépendant d'une version de PHP "4.2"
prog Programme dépendant d'un certain programme accessible via le path du système. Ceci n'est pas supporté par l'installeur PEAR. "latex"
os Système d'exploitation dépendant d'un système d'exploitation "Linux"
sapi API du serveur dépendant de l'API du serveur. Ceci n'est pas supporté par l'installeur PEAR. "Apache"
zend Zend dépendant d'une version de l'API Zend. Ceci n'est pas supporté par l'installeur PEAR. "2"

La DTD pour le fichier de définition accepte d'autres types, mais ceux-ci ne sont pas encore supportés.

L'attribut rel

L'attribut rel permet de définir une relation entre les capacités existantes et celles nécessaires.

valeurs de rel
Valeur Description Peut être utilisé avec
has dispose les capacités existantes doivent en disposer - l'attribut version est ignoré pkg, ext, php, prog, os, sapi, zend
eq égal les capacités existantes doivent correspondre à la valeur de la version pkg, ext, php, prog, os, sapi, zend
lt inférieur les capacités existantes doivent être inférieures à la valeur de la version pkg, ext, php, zend
le inférieur ou égal les capacités existantes doivent être inférieures ou égales à la valeur de la version pkg, ext, php, zend
gt supérieur les capacités existantes doivent être supérieures à la valeur de la version pkg, ext, php, zend
ge supérieur ou égal les capacités existantes doivent être supérieures ou égales à la valeur de la version pkg, ext, php, zend
not conflit de dépendance Les conflits de dépendance avec le paquet, les deux ne peuvent cp-exister. Version est ignoré. ext, php

Has sera utilisé comme valeur par défaut. Notez que cela nécessite PEAR 1.4.0 et supérieure.

L'attribut version

L'attribut version permet de définir la version utilisée pour la comparaison

L'attribut optional

L'attribut optional peut être utilisé lorsqu'une dépendance n'est pas indispensable mais que la présence du package donne accès à des fonctionnalités avancées. Les seules valeurs acceptées sont "yes" et "no". Si l'attribut optional n'est pas présent, la dépendance est indispensable. Lorsque optional="yes" est utilisé, les messages suivants apparaîtront à l'installation:

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

Le fichier de définition de package package.xml (Previous) Coding Standards (Next)
Last updated: Sun, 29 Aug 2010 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

There are no user contributed notes for this page.