= Trac プラグイン = #TracPlugins
[[TracGuideToc]]

バージョン 0.9 以降、 Trac は [http://trac.edgewall.org/wiki/PluginList プラグイン機能] に対応し、組み込み機能を拡張できるようになりました。プラグインの機能は [http://trac.edgewall.org/wiki/TracDev/ComponentArchitecture コンポーネント設計] に基づいています。

== 必要条件 == #Requirements

Trac で Python-egg ベースのプラグインを使用するためには、 [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (バージョン 0.6) をインストールしなければなりません。

`setuptools` をインストールするために、ブートストラップモジュールである [http://peak.telecommunity.com/dist/ez_setup.py ez_setup.py] をダウンロードし、以下に示すように実行して下さい:
{{{
$ python ez_setup.py
}}}

もし `ez_setup.py` スクリプトが setuptools のインストールに失敗したら、 [http://www.python.org/pypi/setuptools PyPI] をダウンロードして手動でインストールしてください。

また、単一の `.py` ファイルで成り立つプラグインは、各 TracEnvironment かグローバルの `plugin` ディレクトリに配置します。 ''([http://trac.edgewall.org/milestone/0.10 milestone:0.10] 以降)'' TracIni#GlobalConfiguration を参照してください。

== Trac プラグインのインストール == #InstallingaTracPlugin

=== 単一のプロジェクト === #ForaSingleProject

プラグインは [http://peak.telecommunity.com/DevCenter/PythonEggs Python eggs] としてパッケージ化されています。つまり、拡張子が `.egg` となっている ZIP アーカイブのファイルです。

plugin のディストリビューションをダウンロードして `.egg` ファイルをビルドしたいのであれば、以下の通りにして下さい:
 * ソースをアンパックして下さい。それにより setup.py が提供されるでしょう。 
 * 以下のようにして実行してください:
{{{
$ python setup.py bdist_egg
}}}

*.egg ファイルが出力されているでしょう。実行した python の出力を調べて .egg ファイルがどこに作成されたか見つけてください。

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

この方法でインストールしたプラグインをアンインストールする場合、 `plugins` ディレクトリから egg を削除し、 Web サーバを再起動してください。

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

マルチプロジェクトを設定している場合、 Python インタプリタインスタンスのプールはプロジェクトの必要に応じて動的にアロケートされ、プラグインは Pyhton のモジュールシステムの一定の位置を占有しますので、最初にロードされたバージョンのプラグインが、他のすべてのプロジェクトでも使用されます。言い換えれば、マルチプロジェクトセットアップされたプロジェクト間では、あるプラグインの異なるバージョンを使用することはできません。プラグインは (下記の方法で) すべてのプロジェクト向けにインストールし、個々のプロジェクトで有効/無効を設定する方が安全でしょう。

=== すべてのプロジェクト === #ForAllProjects

==== 単一の .egg ファイル ==== #Withan.eggfile

いくつかのプラグイン (例えば [http://trac.edgewall.org/wiki/SpamFilter SpamFilter]) は `.egg` ファイルとしてダウンロードし、 `easy_install` プログラムでインストールすることができます:
{{{
easy_install TracSpamFilter
}}}

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

Zip で固められた Python egg をインストールし、 Web サーバに Python egg のキャッシュディレクトリに書き込み権限をつけているのにも関わらず、 Trac がパーミッションエラーを出したら、解凍した Python egg を単に置き直すことによって回避できます。 `easy_install` に `--always-unzip` オプションを付けるだけです:
{{{
easy_install --always-unzip TracSpamFilter-0.2.1dev_r5943-py2.4.egg
}}}
zip で固められた Python egg ファイルと同じ名前のディレクトリ (拡張子が `.egg` で終わっているもの) ができ、そのなかに解凍した中身が入っているでしょう。

Trac はまた、グローバルにインストールされたプラグインを検索します ''(0.10 以降)''。 TracIni#GlobalConfiguration を参照してください。

==== ソースから ==== #Fromsource

`easy_install` をソースからインストールする方法を以下に示します。Subversion のリポジトリか、 tarball/zip のソースを引数に与えてください。
{{{
easy_install http://svn.edgewall.com/repos/trac/sandbox/spam-filter
}}}

==== プラグインを有効にする ==== #Enablingtheplugin
個別の TracEnvironment にプラグインをインストールする場合と異なり、システム全体にインストールしたプラグインを有効にするためには、 [wiki:TracIni trac.ini] ファイルで明示的に指定しなければいけません。設定ファイルの `[inherit] plugins_dir` オプションに指定したパスにプラグインをインストールする場合も同じく、明示的に指定する必要があります。設定ファイルの `[components]` セクションに次のような記載を行います:
{{{
[components]
tracspamfilter.* = enabled
}}}

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

Note: プラグインのインストール後、 Web サーバを再起動する必要があります。

==== アンインストール ==== #Uninstalling

`easy_install` や `python setup.py` ではアンインストール機能は提供されていません。しかし、グローバルにインストールされた egg や参照を削除するための簡単な方法があります:
 1. setuptools でインストールした場合、 `easy_install -m [plugin name]` を実行し、 `$PYTHONLIB/site-packages/easy-install.pth`　から参照を削除します。
 1. 実行可能ファイルを `/usr/bin`, `/usr/local/bin`, `C:\\Python*\\Scripts` などから削除します。実行可能ファイルが分からない場合、 `setup.py` の `[console-script]` を参照します。
 1. インストールされた場所 (通常 `$PYTHONLIB/site-packages/` 配下) の .egg ファイルやディレクトリを削除します。
 1. Web サーバを再起動する。

egg の場所が分らない場合、探すためには以下の方法を使います (この方法は、どのようなパッケージでも使えます) - `myplugin` の箇所は、プラグインのネームスペースで置き換えてください。ネームスペースはプラグインの有効化の時に使用した名前と同じになります。
{{{
>>> import myplugin
>>> print myplugin.__file__
/opt/local/python24/lib/site-packages/myplugin-0.4.2-py2.4.egg/myplugin/__init__.pyc
}}}

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

プラグインは Python eggs のランタイム (`pkg_resources`) によって解凍される必要があります。それらの内容がファイルシステム上に実際に存在する必要があるからです。通常は現在のユーザのホーム