Trac プラグイン

バージョン 0.9 以降、 Trac はプラグイン機能に対応し、組み込み機能を拡張できるようになりました。プラグインの機能は ​コンポーネント設計 に基づいています。

必要条件

Python egg が基になっている Trac のプラグインを使用するためには、 ​setuptools (バージョン 0.6) をインストールしなければなりません。

プラグインは単一の .py ファイルから成り立っていて、各 TracEnvironment かグローバルの plugin ディレクトリに配置します。 (​milestone:0.10 以降)

setuptools をインストールするために、ブートストラップモジュールである ​ez_setup.py をダウンロードし、以下に示すように実行して下さい:

$ python ez_setup.py

もし ez_setup.py スクリプトが setuptools のインストールに失敗したら、 ​PyPI をダウンロードして手動でインストールしてください。

Trac プラグインのインストール

単一のプロジェクト

プラグインは ​Python eggs としてパッケージ化されています。つまり、拡張子が .egg となっている ZIP アーカイブのファイルです。プラグインのソースコードディストリビューションをダウンロードした場合は、以下のコマンドを実行して下さい:

$ python setup.py bdist_egg

.egg ファイルをビルドできます。

一度、プラグインアーカイブを作成したら、 TracEnvironment の plugins ディレクトリにコピーする必要があります。また、 Web サーバーが egg プラグインを読み取るのに必要なパーミッションをつけてください。

Python egg をビルドするための Python のバージョンと Trac を動かしている Python のバージョンが一致しなければなりません。 例えば、 Trac を Python のバージョン 2.3 以前で動かしていて、 2.4 にアップグレードしたときに、 Python egg は認識されなくなるでしょう。

すべてのプロジェクト

単一の .egg ファイル

いくつかのプラグイン (例えば ​WebAdmin) は .egg ファイルとしてダウンロードし、 easy_install プログラムでインストールすることができます:

easy_install TracWebAdmin-0.1.1dev_r2765-py2.3.egg

もし、システムに easy_install がなくてプラグインをインストールするには上記の必要条件のセクションを見て下さい。 Windows ユーザは Scripts ディレクトリを Python をインストールしたディレクトリ (例えば、 C:\Python23\Scripts) を環境変数 PATH に加えなければなりません。 (より詳しい情報は、 ​easy_install の Windows Notes を参照して下さい。)

zipで固められた Python egg をインストールし、 Web サーバに Python egg のキャッシュディレクトリに書き込み権限をつけているのにも関わらず、 Trac がパーミッションエラーを出したら、 解凍した Python egg を単に置き直すことによって回避できます。 easy_install に --always-unzip オプションを付けるだけです:

easy_install --always-unzip TracWebAdmin-0.1.1dev_r2765-py2.3.egg

zip で固められた Python egg ファイルと同じ名前のディレクトリ (拡張子が .egg で終わっているもの) ができ、そのなかに解凍した中身が入っているでしょう。

Trac はまた $prefix/share/trac/plugins 配下に、グローバルにインストールされたプラグインを検索します (0.10 以降)。

ソースから

Subversion からダウンロードしたプラグインのソースや zip で固められたソースファイルはソース中に含まれている setup.py を使用してインストールできます:

$ python setup.py install

プラグインを有効にする

個別の TracEnvironment にプラグインをインストールする場合と異なり、システム全体にインストールしたプラグインを有効にするためには、 trac.ini ファイルで明示的に指定しなければいけません。これは設定ファイルの [components] セクションに次のような記載を行います:

[components]
webadmin.* = enabled

オプションの名前はプラグインの Python パッケージ名です。これはプラグインのドキュメンテーションに指定されていなければいけませんが、ソースを見れば簡単に見つけることが出来ます。(最上位のディレクトリにあるファイル __init__.py を探してください。)

Note: プラグインのインストール後、 Apache を再起動する必要があるでしょう。

プラグインのキャッシュの設定

いくつかのプラグインは Python eggs のランタイム (pkg_resources) によって解凍される必要があります。というのもそれらの内容がファイルシステム上に実際に存在する必要があるからです。通常、 Python eggs は現在のユーザのホームディレクトリに解凍されますが、それにより問題が発生するかもしれません。その場合、環境変数 PYTHON_EGG_CACHE を設定してデフォルトのロケーションを上書きすることができます。

PYTHON_EGG_CACHE を SetEnv ディレクティブを使用して Apache に設定するには以下のようにします:

SetEnv PYTHON_EGG_CACHE /path/to/dir

これは CGI と mod_python のどちらをフロントエンドにしようと動作します。このディレクティブに Trac Environment へのパスに設定し、例えば同じ <Location> ブロックにおいてください。

例 (CGI用):

 <Location /trac>
   SetEnv TRAC_ENV /path/to/projenv
   SetEnv PYTHON_EGG_CACHE /path/to/dir
 </Location>

例 (mod_python用):

 <Location /trac>
   SetHandler mod_python
   ...
   SetEnv PYTHON_EGG_CACHE /path/to/dir
 </Location>

Note: これは mod_env モジュールが必要です。

FastCGI で、 Web サーバに設定するためには、 -initial-env オプションやサーバーが指定している方法で、環境変数を設定する必要があります。

Subversion の フックスクリプトについて

もし、 Trac エンジンを呼び出すような Subversion の フックスクリプト - Trac の配布物の /contrib ディレクトリで提供されている post-commit フックスクリプトなど - を設定していたら、プラグインと同様にスクリプトの中で環境変数 PYTHON_EGG_CACHE を定義して下さい。

トラブルシューティング

setuptools は正しくインストールされていますか？

これコマンドラインで実行してみてください:

$ python -c "import pkg_resources"

もし、コマンドラインから 何も かえって来なければ、 setuptools はインストール されています。そうでなければ、 Trac を動かす前に setuptools をインストールする必要があります。

Python egg は正しいバージョンですか？

Python egg はファイル名の中で Python のバージョンをエンコードします。例えば、 MyPlugin-1.0-py2.4.egg は Python 2.4 用の Python egg であり、異なる Python のバージョン (2.3 や 2.5) で動かそうとしても 動かない でしょう。

また、ダウンロードした Python egg ファイル が本当に ZIP アーカイブであるかどうかを確認して下さい。もし Trac サイトからダウンロードしたとしたら、 HTML プレビューページを代わりにダウンロードしているかもしれません。

プラグインは有効になっていますか？

グローバル領域にプラグインをインストールした場合 (TracEnvironment の plugin ディレクトリ内 ではなく) 、 trac.ini に明確に有効にする設定をしなければなりません。以下の事項を確認して下さい:

• [components] セクションに必要な行数を追加したか。
• パッケージ / モジュール名は正しいか
• もし、(クラスに対して) モジュールを参照しているならば、必要に応じて、 ".*" を追加しているかどうか。
• 正しい値、 "enabled" になっているかどうか。例えば、 "enable" ではなく。

Python egg ファイルのパーミッションのチェック

Trac はもちろん Python egg ファイルを読めなければいけません。分かってるよね。;-)

ログファイルのチェック

Trac で logging を有効にし、ログレベルを DEBUG に設定し、プラグインがロードされるときのログメッセージを見て下さい。

---

See also TracGuide, ​プラグイン一覧, ​コンポーネント設計