パッケージ定義ファイル package.xml の解説

package.xml バージョン 1.0 は非推奨です

package.xml 1.0 は非推奨です。package.xml バージョン 2.0 を使用しましょう。 ドキュメントは package.xml 2.0 ドキュメント にあります。

2007 年 4 月現在、世の中の 99.8% 以上の環境で PEAR 1.4 以降が利用されています。 したがって、もう後方互換性を気にする必要はありません。

パッケージ定義ファイル package.xml は、 その名が示す通り、ある PEAR パッケージについての情報が記載された 整形式の XML ファイルです。

このセクションでは、パッケージ定義に使用可能な要素について述べ、 自作のパッケージに対して定義ファイルを作成する方法について解説します。

PEAR_PackageFileManager パッケージを使えば、package.xml の作成が容易になります。 通常と同様、次のコマンドで PEAR_PackageFileManager をインストールできます。

      
$ pear install PEAR_PackageFileManager
      
     

使用可能な要素

package.xml のトップレベル要素は <package version="1.0"> です。 副要素として使用可能なものは次の通り。

  • <name>: パッケージの名称
  • <summary>: パッケージについての解説の短い要約
  • <description>: パッケージについての完全な解説
  • <license>: パッケージのライセンス (LGPL, PHP License など).
  • <maintainers>: パッケージのメンテナに関する情報

    • <maintainer>: メンテナ各人に関する情報 (複数回記述可能)

      • <user>: メンテナのユーザアカウント名
      • <role>: メンテナのパッケージ開発における役割 (lead, developer, helper のいずれか)
      • <name>: メンテナの本名
      • <email>: メンテナのメールアドレス
  • <release>: 現リリースに関する情報

    • <version>: リリースのバージョン番号
    • <state>: リリースの状態 (stable, beta, alpha, devel もしくは snapshot のいずれか)
    • <date>: リリースされた日時
    • <license>: コードに適用された ライセンス
    • <notes>: リリースノート
    • <filelist>

      • <file name="xxx" role="xxx" />: ファイル名
      • <dir name="xxx" [role="xxx"]>: サブディレクトリ名。このサブディレクトリには <file role="xxx"> 要素を再度含むことができます。
  • <deps>: パッケージの依存性のリスト

    • <dep type="xxx" rel="yyy" optional="yes">name</dep> : 依存性に関するより詳細な情報については 下記 を参照してください。

  • <changelog>: パッケージに関する更新履歴的情報

    • <release>

      • <version>: 対象リリースのバージョン
      • <state>: 対象リリースの状態
      • <date>: 対象リリースの日付
      • <notes>: 更新履歴の情報

使用可能な文字

要素内で使用可能な文字は A-Z および a-z です。 他の文字、たとえば é など、 を使用するには、エンティティを用います(この場合は &eacute;)。

package.xml ファイルを PEAR_PackageFileManager を使って作成する場合には、 インストールされた PEAR をバージョン 1.4.0a2 以降にしておくと良いでしょう。 FileManager が自動的に処理しますので、使用可能な文字について心配しなくてすみます。

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 の検証には、 libxml2 に同梱されているツール xmllint を使用します。

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" name="Fast.php" />
   </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" 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">
     <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>
   </dir>
  </filelist>
 </release>
</package>

この例では、便利な機能が使われています。パッケージ中に 同じタイプのファイルだけを含むディレクトリがある場合、 role 属性を <dir> タグに記述することで、 個別の <file> タグにいちいち記述しないですみます。

このセクションで得た知識に基づいて、 パッケージ定義ファイルを作成可能になったことでしょう。 この話題について、さらに疑問がある場合は、 メーリングリストで 質問してください。

ファイルの役割

<file> タグ中の type 属性により ファイルのタイプを指定します。これにより、ファイルがインストール される場所が決まります。

指定可能な値
  インストール ディレクトリ
php PHP ソースファイル パッケージ名によって決定されます
ext 拡張モジュール。ダイナミックライブラリ PHP 拡張モジュールのディレクトリ、または PHP_PEAR_EXTENSION_DIR で定義されたディレクトリ
doc ドキュメントファイル {PEAR_documentation_dir}/パッケージ名/
data パッケージ関連データファイル群(画像やデータ表など) {PEAR_data_dir}/パッケージ名/
test パッケージ関連テストファイル(ユニットテストなど) {PEAR_test_dir}/パッケージ名/
script パッケージ関連シェルスクリプト群 PHP バイナリディレクトリ、または PHP_PEAR_BIN_DIR で指定されたディレクトリ
src and extsrc C または C++ のソースコード 直接はコピーされません - 拡張モジュールのビルドの際に使用されます

依存性の定義

PEAR パッケージのインストールの際に、PEAR パッケージマネージャに インストール先のシステム特性をチェックさせることが可能です。 インストールに当たって必要な(もしくは推奨される)システム特性を <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 属性には、次が指定できます。

type に指定可能な値
  意味
pkg パッケージ 特定のパッケージに依存 "HTML_Flexy"
ext 拡張モジュール 特定の PHP 拡張モジュールに依存 "curl"
php PHP 特定の PHP バージョンに依存 "4.2"
prog プログラム システムパス中にある特定のプログラムに依存(PEAR インストーラでは未サポート) "latex"
os オペレーティングシステム 特定の(バージョンの)OS に依存 "Linux"
sapi サーバ API 特定のサーバ API に依存(PEAR インストーラでは未サポート) "Apache"
zend Zend 特定の Zend API バージョンに依存(PEAR インストーラでは未サポート) "2"

パッケージ定義ファイルの DTD では他のタイプもサポートするようになっていますが、 まだ実際に実装されるにいたっていません。

rel 属性

rel 属性には、インストール先のシステム特性との関連を指定します。

rel に指定可能な値
  意味 使用可能な type 属性
has 保持 インストール先のシステムが要求された特性を保持している。version 属性は無視されます。 pkg, ext, php, prog, os, sapi, zend
eq 合致 インストール先のシステム特性が version 属性値と合致している。 pkg, ext, php, prog, os, sapi, zend
lt 未満 インストール先のシステム特性が version 属性値より小さい。 pkg, ext, php, zend
le 以下 インストール先のシステム特性が version 属性値以下である。 pkg, ext, php, zend
gt より大きい インストール先のシステム特性が version 属性値より大きい。 pkg, ext, php, zend
ge 以上 インストール先のシステム特性が version 属性値以上である。 pkg, ext, php, zend
not 衝突 依存性が本パッケージと衝突しており、共存できない。 version 属性は無視されます。 ext, php

値を指定しない場合、 has が指定されたことになります。 rel 属性を用いるには PEAR 1.4.0 かそれ以降が必要です。

version 属性

version は、 rel 属性で比較されるバージョン値を指定します。

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: Mon, 01 Sep 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.