Changes between Version 1 and Version 2 of TracPlugins


Ignore:
Timestamp:
09/18/14 10:48:12 (5 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TracPlugins

    v1 v2  
    1 = Trac プラグイン = #TracPlugins 
     1= Trac プラグイン = #Tracplugins  
    22[[TracGuideToc]] 
    33 
    4 バージョン 0.9 以降、 Trac は [http://trac.edgewall.org/wiki/PluginList プラグイン機能] に対応し、組み込み機能を拡張できるようになりました。プラグインの機能は [http://trac.edgewall.org/wiki/TracDev/ComponentArchitecture コンポーネント設計] に基づいています。 
    5  
    6 == 必要条件 == #Requirements 
     4バージョン 0.9 以降の Trac は[http://trac.edgewall.org/wiki/PluginList プラグイン機能] による機能拡張が可能です。プラグイン機能は、 [http://trac.edgewall.org/wiki/TracDev/ComponentArchitecture コンポーネント設計] に基づき、 [http://trac.edgewall.org/wiki/TracDev/PluginDevelopment プラグインの開発] ページに記載されているような特性を持っています。 
     5 
     6== プラグインを見つける == #Plugindiscovery 
     7 
     8ユーザの視点からいうと、プラグインはスタンドアロンの .py ファイルか .egg パッケージのどちらかです。 Trac は グローバルで共有するプラグインのディレクトリ ([TracIni#GlobalConfiguration グローバルな設定] 参照) とローカルの TracEnvironment の `plugins` ディレクトリに対して、プラグインを探します。グローバルにインストールされているプラグインを定義するコンポーネントは trac.ini ファイルの [[TracIni#components-section| [components] ]] セクションで明確に有効にするべきです。 
     9 
     10== Trac eggs ファイルにおける必要条件 == #RequirementsforTraceggs 
    711 
    812Trac で Python-egg ベースのプラグインを使用するためには、 [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (バージョン 0.6) をインストールしなければなりません。 
    913 
    1014`setuptools` をインストールするために、ブートストラップモジュールである [http://peak.telecommunity.com/dist/ez_setup.py ez_setup.py] をダウンロードし、以下に示すように実行して下さい: 
     15 
    1116{{{ 
    1217$ python ez_setup.py 
     
    1520もし `ez_setup.py` スクリプトが setuptools のインストールに失敗したら、 [http://www.python.org/pypi/setuptools PyPI] をダウンロードして手動でインストールしてください。 
    1621 
    17 また、単一の `.py` ファイルで成り立つプラグインは、各 TracEnvironment かグローバルの `plugin` ディレクトリに配置します。 ''([http://trac.edgewall.org/milestone/0.10 milestone:0.10] 以降)'' TracIni#GlobalConfiguration を参照してください。 
    18  
    19 == Trac プラグインのインストール == #InstallingaTracPlugin 
    20  
    21 === 単一のプロジェクト === #ForaSingleProject 
    22  
    23 プラグインは [http://peak.telecommunity.com/DevCenter/PythonEggs Python eggs] としてパッケージ化されています。つまり、拡張子が `.egg` となっている ZIP アーカイブのファイルです。 
    24  
    25 plugin のディストリビューションをダウンロードして `.egg` ファイルをビルドしたいのであれば、以下の通りにして下さい: 
    26  * ソースをアンパックして下さい。それにより setup.py が提供されるでしょう。  
    27  * 以下のようにして実行してください: 
     22また、単一の `.py` ファイルで成り立つプラグインは、各プロジェクトの `plugins` ディレクトリか共有の `plugins` ディレクトリに配置します。 
     23 
     24== Trac プラグインのインストール == #InstallingaTracplugin 
     25 
     26=== 単一のプロジェクト === #Forasingleproject 
     27 
     28プラグインは一般的に [http://peak.telecommunity.com/DevCenter/PythonEggs Python eggs] としてパッケージ化されています。つまり、拡張子が `.egg` となっている .zip アーカイブのファイルです。 
     29 
     30プラグインのディストリビューションをダウンロードして `.egg` ファイルをビルドしたい場合:  
     31 
     32 * ソースをアンパックして下さい。それにより `setup.py` が提供されるでしょう。 
     33 * 以下のようにして実行してください:  
     34 
    2835{{{ 
    2936$ python setup.py bdist_egg 
    3037}}} 
    3138 
    32 *.egg ファイルが出力されているでしょう。実行した python の出力を調べて .egg ファイルがどこに作成されたか見つけてください。 
    33  
    34 一度、プラグインアーカイブを作成したら、 [wiki:TracEnvironment TracEnvironment] の `plugins` ディレクトリにコピーする必要があります。また、 Web サーバーが egg プラグインを読み取るのに必要なパーミッションをつけてください。 
     39*.egg ファイルが出力されるはずです。実行した python の出力を調べて .egg ファイルがどこに作成されたか見つけてください。 
     40 
     41一度、プラグインアーカイブを作成したら、 [wiki:TracEnvironment TracEnvironment] の `plugins` ディレクトリにコピーする必要があります。また、 Web サーバーが egg プラグインを読み取るのに必要なパーミッションを持っているか確認してください。そして Web サーバを再起動してください。 [wiki:TracStandalone "tracd" というスタンドアロンサーバー] を使用している方は、tracd を再起動してください。  
    3542 
    3643この方法でインストールしたプラグインをアンインストールする場合、 `plugins` ディレクトリから egg を削除し、 Web サーバを再起動してください。 
    3744 
    38 Python egg をビルドするための Python のバージョンと  
    39 Trac を動かしている Python のバージョンが一致しなければなりません。 
    40 例えば、 Trac を Python のバージョン 2.3 以前で動かしていて、 
    41 2.4 にアップグレードしたときに、  
    42 Python egg は認識されなくなるでしょう。 
    43  
    44 マルチプロジェクトを設定している場合、 Python インタプリタインスタンスのプールはプロジェクトの必要に応じて動的にアロケートされ、プラグインは Pyhton のモジュールシステムの一定の位置を占有しますので、最初にロードされたバージョンのプラグインが、他のすべてのプロジェクトでも使用されます。言い換えれば、マルチプロジェクトセットアップされたプロジェクト間では、あるプラグインの異なるバージョンを使用することはできません。プラグインは (下記の方法で) すべてのプロジェクト向けにインストールし、個々のプロジェクトで有効/無効を設定する方が安全でしょう。 
    45  
    46 === すべてのプロジェクト === #ForAllProjects 
     45Note: Python egg をビルドするための Python のバージョンと Trac を動かしている Python のバージョンが一致しなければなりません。例えば、 Trac を Python のバージョン 2.5 以前で動かしていて、 2.6 にアップグレードしたときに、Python egg は認識されなくなるでしょう。 
     46 
     47Note: マルチプロジェクトを設定している場合、 Python インタプリタインスタンスのプールはプロジェクトの必要に応じて動的にアロケートされ、プラグインは Pyhton のモジュールシステムの一定の位置を占有しますので、最初にロードされたバージョンのプラグインが、他のすべてのプロジェクトでも使用されます。言い換えれば、マルチプロジェクトセットアップされたプロジェクト間では、あるプラグインの異なるバージョンを使用することはできません。プラグインは (下記の方法で) すべてのプロジェクト向けにインストールし、個々のプロジェクトで有効/無効を設定する方が安全でしょう。 
     48 
     49=== すべてのプロジェクト === #Forallprojects 
    4750 
    4851==== 単一の .egg ファイル ==== #Withan.eggfile 
    4952 
    50 いくつかのプラグイン (例えば [http://trac.edgewall.org/wiki/SpamFilter SpamFilter]) は `.egg` ファイルとしてダウンロードし、 `easy_install` プログラムでインストールすることができます: 
     53いくつかのプラグイン (例えば [http://trac.edgewall.org/wiki/SpamFilter SpamFilter]) は `.egg` ファイルとしてダウンロードし、 `easy_install` プログラムでインストールすることができます:  
    5154{{{ 
    5255easy_install TracSpamFilter 
    5356}}} 
    5457 
    55 もし、システムに `easy_install` がなくてプラグインをインストールするには上記の必要条件のセクションを見て下さい。 Windows ユーザは `Scripts` ディレクトリを Python をインストールしたディレクトリ (例えば、 `C:\Python23\Scripts`) を環境変数 `PATH` に加えなければなりません。 (より詳しい情報は、 [http://peak.telecommunity.com/DevCenter/EasyInstall#windows-notes easy_install の Windows Notes] を参照して下さい。) 
    56  
    57 Zip で固められた Python egg をインストールし、 Web サーバに Python egg のキャッシュディレクトリに書き込み権限をつけているのにも関わらず、 Trac がパーミッションエラーを出したら、解凍した Python egg を単に置き直すことによって回避できます。 `easy_install` に `--always-unzip` オプションを付けるだけです: 
    58 {{{ 
    59 easy_install --always-unzip TracSpamFilter-0.2.1dev_r5943-py2.4.egg 
     58システムに `easy_install` がない場合、インストールするために上記の必要なセクションを見てください。 Windows ユーザは Python をインストールした `Scripts` ディレクトリ (例えば、 `C:\Python24\Scripts`) を環境変数 `PATH` に加えなければなりません。 (より詳しい情報は、 [http://peak.telecommunity.com/DevCenter/EasyInstall#windows-notes easy_install の Windows Notes] を参照してください。)  
     59 
     60zip で固められた Python egg をインストールした後で Trac がパーミッションエラーを出し、 web サーバによって書き込み可能な Python egg のキャッシュディレクトリを提供したくないときは、 Python egg を解凍することで問題を回避できます。`easy_install` に `--always-unzip` オプションを付けるだけです: 
     61{{{ 
     62easy_install --always-unzip TracSpamFilter-0.4.1_r10106-py2.6.egg 
    6063}}} 
    6164zip で固められた Python egg ファイルと同じ名前のディレクトリ (拡張子が `.egg` で終わっているもの) ができ、そのなかに解凍した中身が入っているでしょう。 
    6265 
    63 Trac はまた、グローバルにインストールされたプラグインを検索します ''(0.10 以降)''。 TracIni#GlobalConfiguration を参照してください 
     66Trac は共有の plugins ディレクトリにインストールされたプラグインも検索します ''(0.10 以降)''。 TracIni#GlobalConfiguration を参照してください。この方法は複数の (しかし全てではない) Environment にまたがってプラグインをインストールする最も簡単な方法になります 
    6467 
    6568==== ソースから ==== #Fromsource 
    6669 
    67 `easy_install` をソースからインストールする方法を以下に示します。Subversion のリポジトリか、 tarball/zip のソースを引数に与えてください。 
    68 {{{ 
    69 easy_install http://svn.edgewall.com/repos/trac/sandbox/spam-filter 
    70 }}} 
    71  
    72 ==== プラグインを有効にする ==== #Enablingtheplugin 
    73 個別の TracEnvironment にプラグインをインストールする場合と異なり、システム全体にインストールしたプラグインを有効にするためには、 [wiki:TracIni trac.ini] ファイルで明示的に指定しなければいけません。設定ファイルの `[inherit] plugins_dir` オプションに指定したパスにプラグインをインストールする場合も同じく、明示的に指定する必要があります。設定ファイルの `[components]` セクションに次のような記載を行います: 
     70`easy_install` を使ってソースからインストールすることができます。Subversion のリポジトリ又は ソースの tarball/zip を引数に与えてください。 
     71{{{ 
     72easy_install http://svn.edgewall.com/repos/trac/plugins/0.12/spam-filter-captcha 
     73}}} 
     74 
     75==== プラグインを有効にする ==== #Enablingtheplugin  
     76 
     77個別の TracEnvironment にプラグインをインストールする場合と異なり、システム全体にインストールしたプラグインを有効にするためには、 [wiki:TracIni trac.ini] ファイルで明示的に指定しなければいけません。設定ファイルの `[inherit] plugins_dir` オプションに指定した共有の plugins ディレクトリにプラグインをインストールする場合も同じく、明示的に指定する必要があります。 
     78 
     79設定ファイルの `[components]` セクションに次のような記述を加えれば完了です: 
    7480{{{ 
    7581[components] 
     
    7783}}} 
    7884 
    79 オプションの名前はプラグインの Python パッケージ名です。これはプラグインのドキュメンテーションに指定されていなければいけませんが、ソースを見れば簡単に見つけることが出来ます。 (最上位のディレクトリにあるファイル `__init__.py` を探してください。) 
     85オプションの名前はプラグインの Python パッケージ名です。これはプラグインのドキュメンテーションに指定されていなければいけませんが、ソースを見れば簡単に見つけることが出来ます。 (最上位のディレクトリにあるファイル `__init__.py` を探してください。)  
    8086 
    8187Note: プラグインのインストール後、 Web サーバを再起動する必要があります。 
     
    8490 
    8591`easy_install` や `python setup.py` ではアンインストール機能は提供されていません。しかし、グローバルにインストールされた egg や参照を削除するための簡単な方法があります: 
     92 
    8693 1. setuptools でインストールした場合、 `easy_install -m [plugin name]` を実行し、 `$PYTHONLIB/site-packages/easy-install.pth` から参照を削除します。 
    87  1. 実行可能ファイルを `/usr/bin`, `/usr/local/bin`, `C:\\Python*\\Scripts` などから削除します。実行可能ファイルが分からない場合、 `setup.py` の `[console-script]` を参照します 
     94 1. `/usr/bin`, `/usr/local/bin`, `C:\\Python*\\Scripts` などから実行可能ファイルを削除します。実行可能ファイルが分からない場合、 `setup.py` の `[console-script]` を参照してください 
    8895 1. インストールされた場所 (通常 `$PYTHONLIB/site-packages/` 配下) の .egg ファイルやディレクトリを削除します。 
    89  1. Web サーバを再起動する 
    90  
    91 egg の場所が分らない場合、探すためには以下の方法を使います (この方法は、どのようなパッケージでも使えます) - `myplugin` の箇所は、プラグインのネームスペースで置き換えてください。ネームスペースはプラグインの有効化の時に使用した名前と同じになります。 
     96 1. Web サーバを再起動します 
     97 
     98egg の場所が分らない場合、探すためには以下の方法を使います (この方法は、どのようなパッケージでも使えます)`myplugin` の箇所は、プラグインのネームスペースで置き換えてください。ネームスペースはプラグインの有効化の時に使用した名前と同じになります。 
    9299{{{ 
    93100>>> import myplugin 
     
    96103}}} 
    97104 
    98 == プラグインのキャッシュの設定 == #SettingupthePluginCache 
    99  
    100 プラグインは Python eggs のランタイム (`pkg_resources`) によって解凍される必要があります。それらの内容がファイルシステム上に実際に存在する必要があるからです。通常は現在のユーザのホームディレクトリの '.python-eggs' に解凍されますが、それにより問題が発生するかもしれません。その場合、環境変数 `PYTHON_EGG_CACHE` を設定してデフォルトのロケーションを上書きすることができます。 
    101  
    102 `PYTHON_EGG_CACHE` を `SetEnv` ディレクティブを使用して Apache に設定するには以下のようにします: 
     105== プラグインのキャッシュの設定 == #Settinguptheplugincache 
     106 
     107いくつかのプラグインは、 その内容がファイルシステム上に存在するように、Python eggs のランタイム (`pkg_resources`) によって解凍する必要があります。通常は現在のユーザのホームディレクトリの `.python-eggs` に解凍されますが、それにより問題が発生するかもしれません。その場合、環境変数 `PYTHON_EGG_CACHE` を設定してデフォルトのロケーションを上書きすることができます。 
     108 
     109`PYTHON_EGG_CACHE` を `SetEnv` ディレクティブを使用して Apache に設定する方法: 
    103110{{{ 
    104111SetEnv PYTHON_EGG_CACHE /path/to/dir 
     
    136143=== Subversion の フックスクリプトについて === #Abouthookscripts 
    137144 
    138 もし、 Trac エンジンを呼び出すような Subversion の フックスクリプト - Trac の配布物の `/contrib` ディレクトリで提供されている post-commit フックスクリプトなど - を設定していたら、プラグインと同様にスクリプトの中で環境変数 `PYTHON_EGG_CACHE` を定義して下さい。 
     145もし、 Trac エンジンを呼び出すような Subversion の フックスクリプト (Trac の配布物の `/contrib` ディレクトリで提供されている post-commit フックスクリプトなど) を設定していたら、プラグインと同様にスクリプトの中で環境変数 `PYTHON_EGG_CACHE` を定義してください。 
    139146 
    140147== トラブルシューティング == #Troubleshooting 
     
    151158=== Python egg は正しいバージョンですか? === #DidyougetthecorrectversionofthePythonegg 
    152159 
    153 Python egg はファイル名の中で Python のバージョンをエンコードします。例えば、 `MyPlugin-1.0-py2.4.egg` は Python 2.4 用の Python egg であり、異なる Python のバージョン (2.3 や 2.5) で動かそうとしても '''動かない''' でしょう。 
    154  
    155 また、ダウンロードした Python egg ファイル が本当に ZIP アーカイブであるかどうかを確認して下さい。もし Trac サイトからダウンロードしたとしたら、 HTML プレビューページを代わりにダウンロードしているかもしれません。 
     160Python egg はファイル名の中で Python のバージョンをエンコードします。例えば、 `MyPlugin-1.0-py2.5.egg` は Python 2.5 用の Python egg であり、異なる Python のバージョン (2.4 や 2.6) で動かそうとしても '''動かない''' でしょう。 
     161 
     162また、ダウンロードした Python egg ファイル が本当に .zip アーカイブであるかどうかを確認して下さい。もし Trac サイトからダウンロードしたとしたら、 HTML プレビューページを代わりにダウンロードしているかもしれません。 
    156163 
    157164=== プラグインは有効になっていますか? === #Isthepluginenabled 
    158165 
    159  
    160 グローバル領域にプラグインをインストールした場合 (TracEnvironment の `plugin` ディレクトリ内 ''ではなく'') 、 [TracIni trac.ini] に明確に有効にする設定をしなければなりません。以下の事項を確認して下さい: 
    161  * `[components]` セクションに必要な行数を追加したか。 
    162  * パッケージ / モジュール名は正しいか 
    163  * 正しい値、 "enabled" になっているかどうか。例えば、 "enable" ではなく 
    164  
    165 === Python egg ファイルのパーミッションのチェック === #Checkthepermissionsontheeggfile 
    166  
    167 Trac は Python egg ファイルを読なければなりません。 
     166グローバル領域にプラグインをインストールした場合 (Environment の `plugins` ディレクトリ内 ''ではなく'') 、 [TracIni trac.ini] に明確に有効にする設定をしなければなりません。以下の事項を確認して下さい:  
     167 
     168 * ...`[components]` セクションに必要な行数を追加したか。 
     169 * ...パッケージ / モジュール名は正しいか。 
     170 * ..."enable" や "Enable" ではなく、正しい値 "enabled" になっているかどうか 
     171 
     172=== Python egg ファイルのパーミッションのチェック === #Checkthepermissionsonthe.eggfile  
     173 
     174Trac は Python egg ファイルを読み込み可能でなければなりません。 
    168175 
    169176=== ログファイルのチェック === #Checkthelogfiles 
     
    177184=== 読み込むプラグインのバージョンを間違えていませんか ? === #Isthewrongversionofthepluginloading 
    178185 
    179 複数のプロジェクトがある場合に plugins ディレクトリにプラグインを置くなら確実に正しいバージョンのプラグインがロードされていることを確認する必要があります。ここにいくつかの基本的なルールがあります: 
     186複数のプロジェクトがある場合に plugins ディレクトリにプラグインを置くなら、確実に正しいバージョンのプラグインがロードされていることを確認する必要があります。ここにいくつかの基本的なルールがあります: 
     187 
    180188 * 実行中の Trac サーバ (すなわち各々の Python プロセス) にはプラグインの 1 バージョンだけがロードできます。 Python の名前空間とモジュールリストは (プラグインが`有効 (enabled)` になっているか `無効 (disabled)` になっているかに関わらず) 全プロジェクトで共有されるでしょう。そしてそれは複製をハンドルすることができません。 
    181  * グローバルにインストールされたプラグイン (通常は `setup.py install`) はグローバルな plugins ディレクトリあるいはプロジェクト毎の plugins ディレクトリ内のどんなバージョンも無視するでしょう。グローバルにインストールされたプラグインは、他のどのプラグインよりも前に動作するでしょう。 
    182  * Trac サーバが (`TRAC_ENV_PARENT_DIR` セットアップのように) 複数のプロジェクトをホスティングした場合、異なったプロジェクトで異なるバージョンのプラグインを使用していると、どのバージョンのプラグインが使用されるかは不明です。異なるバージョンのプラグインのうちいずれか一つがロードされるでしょう。そしてロードされたプラグインは全てのプロジェクトで共有されます。 Trac は基本的に一番最初にリクエストを受けたプロジェクトからプラグインをロードします。 
    183  * Python の site-packages 内に複数のバージョンをリストしておく (すなわち `setup.py install` を使用してインストールする) のは素晴らしいことです。 - setuptools は最も新しいバージョンを確実にインストールします。しかし、複数バージョンのプラグインをグローバルな plugins ディレクトリや、プロジェクト毎の plugins ディレクトリに格納しないでください。 - Trac はプラグインを探すときに バージョン番号、格納された日付などを気にしません。この場合 Trac がどのプラグインを最初に見つけ出すかを確実に指定する方法はありません。 
    184  
    185 === 上記のすべてに失敗した場合 === #Ifalloftheabovefailed 
    186  
    187 plugins に対するログが出力されず、 egg が読み込み可能であり、 Python のバージョンが正しく、 ''その上で'' egg がグローバルにインストールされて (そして trac.ini で使用可能に設定されて) いても、なぜかプラグインが動かず、なんのエラーメッセージも表示されない場合は、 [http://trac.edgewall.org/wiki/IrcChannel IrcChannel] で質問してください。 
     189 * グローバルにインストールされたプラグイン (通常は `setup.py install`) は共有 plugins ディレクトリあるいはプロジェクト毎の plugins ディレクトリ内のどんなバージョンも無視するでしょう。グローバルにインストールされたプラグインは、他のどのプラグインよりも''先に''動作するでしょう。 
     190 * Trac サーバが (`TRAC_ENV_PARENT_DIR` セットアップのように) 複数のプロジェクトをホスティングした場合、異なったプロジェクトで異なるバージョンのプラグインを使用していると、どのバージョンのプラグインが使用されるかは不明です。異なるバージョンのプラグインのうちいずれか一つがロードされるでしょう。そしてロードされたプラグインは全てのプロジェクトで共有されます。 Trac は通常一番最初にリクエストを受けたプロジェクトからプラグインをロードします。 
     191 * Python の site-packages 内に複数のバージョンをリストしておく (すなわち `setup.py install` を使用してインストールする) のは素晴らしいことです。 - setuptools は最も新しいバージョンを確実にインストールします。しかし、複数バージョンのプラグインを共有 plugins ディレクトリや、プロジェクト毎の plugins ディレクトリに格納しないでください。 - Trac はプラグインを探すときに バージョン番号、格納された日付などを気にしません。この場合 Trac がどのプラグインを最初に見つけ出すかを確実に指定する方法はありません。 
     192 
     193=== 上記のすべてに失敗した場合 === #Ifalloftheabovefailed  
     194 
     195plugins に対するログが出力されず、 egg が読み込み可能であり、 Python のバージョンが正しく、 ''その上で'' egg がグローバルにインストールされて (そして trac.ini で使用可能に設定されて) ''いても''、なぜかプラグインが動かず、なんのエラーメッセージも表示されない場合は、 [http://trac.edgewall.org/wiki/IrcChannel IrcChannel] で質問してください。 
     196 
     197== web ベースのプラグイン管理 == #Web-basedpluginadministration 
     198 
     199!WebAdmin プラグイン (0.11 から標準付属) を導入することで、 `TRAC_ADMIN` 権限を持ったユーザは web 上でプラグインの設定が行えるようになります:  
     200 
     201* インストールされたプラグインの有効/無効を設定する 
     202* Python egg をアップロードすることでプラグインをインストールする 
     203 
     204セキュリティ上の理由から 2 番目の機能を無効にしたいときには、`trac.ini` の `[components]` セクションに以下の一行を追記してください。 
     205{{{ 
     206trac.admin.web_ui.PluginAdminPanel = disabled 
     207}}} 
     208この設定はパネル全体を無効にしてしまうため、1 番目の機能も使用できなくなります。 
    188209 
    189210----