第 17 章 パッケージ定義ファイル package.xml
パッケージ定義ファイル package.xml の解説
| package.xml バージョン 1.0 は非推奨です |
|
package.xml 1.0 は非推奨です。package.xml バージョン 2.0 を使用してください。 ドキュメントは package.xml 2.0 ドキュメント にあります。 |
パッケージ定義ファイル 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 です。 他の文字、たとえば é など、 を使用するには、エンティティを用います（この場合は é ）。
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
パッケージ定義ファイルの作成
|
例 17-1基本的な package.xml
|
この package.xml は、必要な要素をすべて含んでおり、 テンプレートとして使用できます。 多くの場合、タグ間の文字データを変更するだけで、この例を自作のパッケージに適用できます。
|
例 17-2ネストしたディレクトリの例
|
この例では、便利な機能が使われています。パッケージ中に 同じタイプのファイルだけを含むディレクトリがある場合、 role 属性を <dir> タグに記述することで、 個別の <file> タグにいちいち記述しないですみます。
このセクションで得た知識に基づいて、 パッケージ定義ファイルを作成可能になったことでしょう。 この話題について、さらに疑問がある場合は、 メーリングリスト で 質問してください。
ファイルの役割
<file> タグ中の type 属性により ファイルのタイプを指定します。これにより、ファイルがインストール される場所が決まります。
表 17-1指定可能な値
| 値 | インストール ディレクトリ | |
|---|---|---|
| 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> タグで定義します。
|
例 17-3依存性を明示した package.xml 次の例は、PHP 4.3.0 以降および XML_Parser 1.0 に対する 依存性を記述する方法を示しています。
|
type 属性
type 属性には、次が指定できます。
表 17-2type に指定可能な値
| 値 | 意味 | 例 | |
|---|---|---|---|
| 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 属性には、インストール先のシステム特性との関連を指定します。
表 17-3rel に指定可能な値
| 値 | 意味 | 使用可能な 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. |