Введение

Файл описания пакета, package.xml, как становится понятно из его имени - это XML-файл, который содержит всю информацию о пакете из PEAR.

В этой главе описываются элементы, которые могут присутствовать в файле описания пакета, а также обсуждаются способы создания такого файла для вашего пакета.

Допустимые элементы

Корневым элементом файла package.xml является элемент <package version="1.0">. Допускаются следующие вложенные элементы:

  • <name>: Имя пакета.
  • <summary>: Краткое описание пакета.
  • <description>: Полное описание пакета.
  • <license>: Лицензия (PHP License, LGPL и т.п.). Более подробная информация о допустимых лицензиях в PEAR содержится в FAQ.
  • <maintainers>: Информация о создателях пакета.

    • <maintainer>: Информация о каждом создателе отдельно (может присутствовать несколько раз, для каждого разработчика).

      • <user>: Имя аккаунта разработчика.
      • <role>: Роль разработчика в процессе создания пакета. Может принимать значения: lead, developer, contributor, helper.)
      • <name>: Настоящее имя разработчика.
      • <email>: Адрес электронной почты.
  • <release>: Информация о текущем релизе.

    • <version>: Номер версии релиза.
    • <state>: Статус релиза. (Может быть alpha, beta, stable, devel или snapshot)
    • <date>: Дата релиза.
    • <notes>: Комментарии к релизу
    • <filelist>

      • <file role="xxx">: Имя файла
      • <dir name="xxx" [role="xxx"]>: Имя поддиректории. Поддиректория, в свою очередь, может содержать другие элементы <file role="xxx">.
    • <deps>: Список зависимостей пакета.

      • <dep type="xxx" rel="yyy" optional="yes">name</dep> : Более подробную информацию о зависимостях можно найти ниже.

  • <changelog>: Changelog(история изменений) пакета.

    • <release>

      • <version>: Версия конкретного релиза.
      • <state>: Статус конкретного релиза.
      • <date>: Дата конкретного релиза.
      • <notes>: Комментарии к релизу.

Допустимые символы

Внутри элементов допустимы буквы A-Z и a-z. Остальные символы, такие как é должны задаваться через сущности (entities) (в данном случае: &eacute;).

При использовании PEAR_PackageFileManager версии 1.4.0a2 и выше для создания package.xml, файл менеджер подставит сущности для недопустимых символов автоматически.

При написании файла описания пакета вручную, вам придётся вводить сущности самим. Список наиболее часто используемых сущностей находится на: http://www.evolt.org/article/A_Simple_Character_Entity_Chart/17/21234/ Если нужных вам символов в этом списке нет, попробуйте поискать их в других http://www.oasis-open.org/docbook/xmlcharent/0.1/index.shtml .

Проверка

После создания файла package.xml, его синтаксис можно проверить с помощью команды

         
$ pear package-validate package.xml
         
       

краткая версия - pear pv package.xml).

Также можно использовать утилиту xmllint, которая идёт в составе libxml2.

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

Создание файла описания пакета

Образец package.xml

<?xml version="1.0" encoding="ISO-8859-1" ?>
<package version="1.0">
 <name>Money_Fast</name>
 <summary>Make money fast.</summary>
 <description>
  This package helps you to make money pretty fast.
 </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>
   This is the first release.
  </notes>
  <filelist>
   <dir name="/" baseinstalldir="Money">
    <file role="php">Fast.php</file>
   </dir>
  </filelist>
 </release>
</package>

Этот файл package.xml может послужить вам шаблоном, т.к. он уже содержит все необходимые поля. В большинстве случаев, вам нужно будет всего лишь поменять текст между тэгами, чтобы использовать пример в вашем пакете.

Вложенные директории

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

[...]

 <release>
  <version>1.0</version>
  <date>2002-07-23</date>
  <state>stable</state>
  <notes>
   This is the first release.
  </notes>
  <filelist>
   <dir name="/" baseinstalldir="Money">
    <file role="php">Fast.php</file>
    <dir name="Calculator" role="php">
     <file>Calculator.php</file>
     <file>Currency.php</file>
     <file>Stocks.php</file>
    </dir>
    <dir name="docs" role="doc">
     <file>README.txt</file>
     <file>tutorial.txt</file>
     <dir name="examples" role="doc">
      <file role="php">NASDAQ.php</file>
      <file role="php">DAX.php</file>
     </dir>
    </dir>
   </dir>
  </filelist>
 </release>
</package>

В этом примере демонстрируется очень удобный прием: когда в какой-то из ваших директорий содержатся файлы только одного типа, вы можете использовать атрибут "role" у элемента <dir> вместо того, чтобы добавлять его у каждому элементу <file>.

После прочтения данной главы вы уже можете создавать файл описания пакета. Если у вас все еще есть вопросы по этому поводу - задавайте их в листе рассылки.

Типы файлов

Атрибут role в элементе <file> задаёт тип файла и его месторасположение при инсталляции

Возможные значения
Значение   Директория инсталляции
php Исходный текст PHP директория определяется по имени пакета
ext Расширение, динамически подгружаемая библиотека директория расширений PHP или PHP_PEAR_EXTENSION_DIR, если определена
doc Файл документации {PEAR_documentation_dir}/Package_Name/
data Файлы данных пакета (графика, таблицы, и т.п.) {PEAR_data_dir}/Package_Name/
test Тестовые файлы пакета (unit-тесты и пр.) {PEAR_test_dir}/Package_Name/
script Системные (shell) скрипты пакета непосредственно директория PHP или PHP_PEAR_BIN_DIR, если определена
src and extsrc Исходный код на C или C++ напрямую не копируется - используется для сборки расширения

Определение зависимостей

PEAR Package Manager или менеджер пакетов позволяет задавать различные требования к системе. Вы можете определить зависимости от этих требований с помощью элемента <dep>:

package.xml с зависимостями

Следующий пример показывает, как прописать зависимости от версии PHP не ниже 4.3.0, и от пакета XML_Parser 1.0.

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

Атрибут type

Поддерживаются следующие типы зависимостей:

значения type
Значение   Смысл Пример
pkg Пакет зависимость от определённого пакета "HTML_Flexy"
ext Расширение зависимость от определённого расширения PHP "curl"
php PHP зависимость от версии PHP "4.2"
prog Программа зависимость от определённой программы в системном пути. Не поддерживается инсталлятором PEAR. "latex"
os Операционная система требование конкретной ОС "Linux"
sapi Server API зависимость от определёного Server API. Не поддерживается инсталлятором PEAR. "Apache"
zend Zend требование конкретной версии Zend API. Не поддерживается инсталлятором PEAR. "2"

DTD для файла описания пакета включает и другие типы, которые пока не поддерживаются.

Атрибут rel

Атрибут rel определяет отношение между существующей возможностью и требованием.

значения rel
Значение   Смысл Используется с
has has существующая возможность должна иметь требование - атрибут version игнорируется pkg, ext, php, prog, os, sapi, zend
eq equal существующая возможность должна в точности соответствовать номеру версии pkg, ext, php, prog, os, sapi, zend
lt less than версия существующей возможности должна быть меньше указанной pkg, ext, php, zend
le less than or equal версия существующей возможности должна быть меньше или равна указанной pkg, ext, php, zend
gt greater than версия существующей возможности должна быть больше указанной pkg, ext, php, zend
ge greater than or equal версия существующей возможности должна быть больше или равна указанной pkg, ext, php, zend
not conflicting dependency зависимость конфликтует с пакетом, они не могут существовать вместе, версия игнорируется. ext, php

Has используется, если не определено других значений. Стоит отметить, что rel обязателен для PEAR 1.4.0 и выше.

Атрибут version

Атрибут version определяет версию для сравнения.

Атрибут optional

Атрибут optional может быть указан в случае, когда зависимость не требуется для работы, но её присутствие расширяет функциональность пакета. Допустимые значения "yes" и "no". Если атрибут optional не указан, то зависимость является обязательной. Когда используется optional="yes", это вызовёт сообщения при инсталляции наподобие:

      
$ pear install <package>
Optional dependencies:
Package `XML_Tree' is recommended to utilize some features.
Package `MDB' is recommended to utilize some features.
      
     
Файл описания пакета - package.xml (Previous) Coding Standards (Next)
Last updated: Sat, 26 Jul 2014 — 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.