Changes between Version 2 and Version 3 of TracPlugins


Ignore:
Timestamp:
2009/12/25 16:21:56 (14 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • TracPlugins

    v2 v3  
    1 = Trac プラグイン = 
     1= Trac プラグイン = #TracPlugins 
    22[[TracGuideToc]] 
    33 
    4 バージョン 0.9 以降、 Trac はプラグイン機能に対応し、組み込み機能を拡張できるようになりました。プラグインの機能は [http://trac.edgewall.org/wiki/TracDev/ComponentArchitecture コンポーネント設計] に基づいています。 
     4バージョン 0.9 以降、 Trac は [http://trac.edgewall.org/wiki/PluginList プラグイン機能] に対応し、組み込み機能を拡張できるようになりました。プラグインの機能は [http://trac.edgewall.org/wiki/TracDev/ComponentArchitecture コンポーネント設計] に基づいています。 
    55 
    6 == 必要条件 == 
     6== 必要条件 == #Requirements 
    77 
    8 Python egg が基になっている Trac のプラグインを使用するためには、 [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (バージョン 0.6) をインストールしなければなりません。 
    9  
    10 プラグインは単一の `.py` ファイルから成り立っていて、各 TracEnvironment かグローバルの `plugin` ディレクトリに配置します。 ''([http://trac.edgewall.org/milestone/0.10 milestone:0.10] 以降)'' 
     8Trac で Python-egg ベースのプラグインを使用するためには、 [http://peak.telecommunity.com/DevCenter/setuptools setuptools] (バージョン 0.6) をインストールしなければなりません。 
    119 
    1210`setuptools` をインストールするために、ブートストラップモジュールである [http://peak.telecommunity.com/dist/ez_setup.py ez_setup.py] をダウンロードし、以下に示すように実行して下さい: 
    … …  
    1715もし `ez_setup.py` スクリプトが setuptools のインストールに失敗したら、 [http://www.python.org/pypi/setuptools PyPI] をダウンロードして手動でインストールしてください。 
    1816 
    19 == Trac プラグインのインストール == 
     17また、単一の `.py` ファイルで成り立つプラグインは、各 TracEnvironment かグローバルの `plugin` ディレクトリに配置します。 ''([http://trac.edgewall.org/milestone/0.10 milestone:0.10] 以降)'' TracIni#GlobalConfiguration を参照してください。 
    2018 
    21 === 単一のプロジェクト === 
     19== Trac プラグインのインストール == #InstallingaTracPlugin 
    2220 
    23 プラグインは [http://peak.telecommunity.com/DevCenter/PythonEggs Python eggs] としてパッケージ化されています。つまり、拡張子が `.egg` となっている ZIP アーカイブのファイルです。プラグインのソースコードディストリビューションをダウンロードした場合は、以下のコマンドを実行して下さい: 
     21=== 単一のプロジェクト === #ForaSingleProject 
     22 
     23プラグインは [http://peak.telecommunity.com/DevCenter/PythonEggs Python eggs] としてパッケージ化されています。つまり、拡張子が `.egg` となっている ZIP アーカイブのファイルです。 
     24 
     25plugin のディストリビューションをダウンロードして `.egg` ファイルをビルドしたいのであれば、以下の通りにして下さい: 
     26 * ソースをアンパックして下さい。それにより setup.py が提供されるでしょう。  
     27 * 以下のようにして実行してください: 
    2428{{{ 
    2529$ python setup.py bdist_egg 
    2630}}} 
    27 `.egg` ファイルをビルドできます。 
     31 
     32*.egg ファイルが出力されているでしょう。実行した python の出力を調べて .egg ファイルがどこに作成されたか見つけてください。 
    2833 
    2934一度、プラグインアーカイブを作成したら、 [wiki:TracEnvironment TracEnvironment] の `plugins` ディレクトリにコピーする必要があります。また、 Web サーバーが egg プラグインを読み取るのに必要なパーミッションをつけてください。 
     35 
     36この方法でインストールしたプラグインをアンインストールする場合、 `plugins` ディレクトリから egg を削除し、 Web サーバを再起動してください。 
    3037 
    3138Python egg をビルドするための Python のバージョンと  
    … …  
    3542Python egg は認識されなくなるでしょう。 
    3643 
    37 === すべてのプロジェクト === 
     44マルチプロジェクトを設定している場合、 Python インタプリタインスタンスのプールはプロジェクトの必要に応じて動的にアロケートされ、プラグインは Pyhton のモジュールシステムの一定の位置を占有しますので、最初にロードされたバージョンのプラグインが、他のすべてのプロジェクトでも使用されます。言い換えれば、マルチプロジェクトセットアップされたプロジェクト間では、あるプラグインの異なるバージョンを使用することはできません。プラグインは (下記の方法で) すべてのプロジェクト向けにインストールし、個々のプロジェクトで有効/無効を設定する方が安全でしょう。 
    3845 
    39 ==== 単一の .egg ファイル ==== 
     46=== すべてのプロジェクト === #ForAllProjects 
    4047 
    41 いくつかのプラグイン (例えば [http://trac.edgewall.org/wiki/WebAdmin WebAdmin]) は `.egg` ファイルとしてダウンロードし、 `easy_install` プログラムでインストールすることができます: 
     48==== 単一の .egg ファイル ==== #Withan.eggfile 
     49 
     50いくつかのプラグイン (例えば [http://trac.edgewall.org/wiki/SpamFilter SpamFilter]) は `.egg` ファイルとしてダウンロードし、 `easy_install` プログラムでインストールすることができます: 
    4251{{{ 
    43 easy_install TracWebAdmin-0.1.1dev_r2765-py2.3.egg 
     52easy_install TracSpamFilter 
    4453}}} 
    4554 
    4655もし、システムに `easy_install` がなくてプラグインをインストールするには上記の必要条件のセクションを見て下さい。 Windows ユーザは `Scripts` ディレクトリを Python をインストールしたディレクトリ (例えば、 `C:\Python23\Scripts`) を環境変数 `PATH` に加えなければなりません。 (より詳しい情報は、 [http://peak.telecommunity.com/DevCenter/EasyInstall#windows-notes easy_install の Windows Notes] を参照して下さい。) 
    4756 
    48 zipで固められた Python egg をインストールし、 Web サーバに Python egg のキャッシュディレクトリに書き込み権限をつけているのにも関わらず、 Trac がパーミッションエラーを出したら、 解凍した Python egg を単に置き直すことによって回避できます。 `easy_install` に `--always-unzip` オプションを付けるだけです: 
     57Zip で固められた Python egg をインストールし、 Web サーバに Python egg のキャッシュディレクトリに書き込み権限をつけているのにも関わらず、 Trac がパーミッションエラーを出したら、解凍した Python egg を単に置き直すことによって回避できます。 `easy_install` に `--always-unzip` オプションを付けるだけです: 
    4958{{{ 
    50 easy_install --always-unzip TracWebAdmin-0.1.1dev_r2765-py2.3.egg 
     59easy_install --always-unzip TracSpamFilter-0.2.1dev_r5943-py2.4.egg 
    5160}}} 
    5261zip で固められた Python egg ファイルと同じ名前のディレクトリ (拡張子が `.egg` で終わっているもの) ができ、そのなかに解凍した中身が入っているでしょう。 
    5362 
    54 Trac はまた `$prefix/share/trac/plugins` 配下に、グローバルにインストールされたプラグインを検索します ''(0.10 以降)''。 
     63Trac はまた、グローバルにインストールされたプラグインを検索します ''(0.10 以降)''。 TracIni#GlobalConfiguration を参照してください。 
    5564 
    56 ==== ソースから ==== 
     65==== ソースから ==== #Fromsource 
    5766 
    58 Subversion からダウンロードしたプラグインのソースや zip で固められたソースファイルはソース中に含まれている `setup.py` を使用してインストールできます: 
     67`easy_install` をソースからインストールする方法を以下に示します。Subversion のリポジトリか、 tarball/zip のソースを引数に与えてください。 
    5968{{{ 
    60 $ python setup.py install 
     69easy_install http://svn.edgewall.com/repos/trac/sandbox/spam-filter 
    6170}}} 
    6271 
    63 ==== プラグインを有効にする ==== 
    64 個別の TracEnvironment にプラグインをインストールする場合と異なり、システム全体にインストールしたプラグインを有効にするためには、 [wiki:TracIni trac.ini] ファイルで明示的に指定しなければいけません。これは設定ファイルの `[components]` セクションに次のような記載を行います: 
     72==== プラグインを有効にする ==== #Enablingtheplugin 
     73個別の TracEnvironment にプラグインをインストールする場合と異なり、システム全体にインストールしたプラグインを有効にするためには、 [wiki:TracIni trac.ini] ファイルで明示的に指定しなければいけません。設定ファイルの `[inherit] plugins_dir` オプションに指定したパスにプラグインをインストールする場合も同じく、明示的に指定する必要があります。設定ファイルの `[components]` セクションに次のような記載を行います: 
    6574{{{ 
    6675[components] 
    67 webadmin.* = enabled 
     76tracspamfilter.* = enabled 
    6877}}} 
    6978 
    70 オプションの名前はプラグインの Python パッケージ名です。これはプラグインのドキュメンテーションに指定されていなければいけませんが、ソースを見れば簡単に見つけることが出来ます。(最上位のディレクトリにあるファイル `__init__.py` を探してください。) 
     79オプションの名前はプラグインの Python パッケージ名です。これはプラグインのドキュメンテーションに指定されていなければいけませんが、ソースを見れば簡単に見つけることが出来ます。 (最上位のディレクトリにあるファイル `__init__.py` を探してください。) 
    7180 
    72 Note: プラグインのインストール後、 Apache を再起動する必要があるでしょう。 
     81Note: プラグインのインストール後、 Web サーバを再起動する必要があります。 
    7382 
    74 == プラグインのキャッシュの設定 == 
     83==== アンインストール ==== #Uninstalling 
    7584 
    76 いくつかのプラグインは Python eggs のランタイム (`pkg_resources`) によって解凍される必要があります。というのもそれらの内容がファイルシステム上に実際に存在する必要があるからです。通常、 Python eggs は現在のユーザのホームディレクトリに解凍されますが、それにより問題が発生するかもしれません。その場合、環境変数 `PYTHON_EGG_CACHE` を設定してデフォルトのロケーションを上書きすることができます。 
     85`easy_install` や `python setup.py` ではアンインストール機能は提供されていません。しかし、グローバルにインストールされた egg や参照を削除するための簡単な方法があります: 
     86 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]` を参照します。 
     88 1. インストールされた場所 (通常 `$PYTHONLIB/site-packages/` 配下) の .egg ファイルやディレクトリを削除します。 
     89 1. Web サーバを再起動する。 
     90 
     91egg の場所が分らない場合、探すためには以下の方法を使います (この方法は、どのようなパッケージでも使えます) - `myplugin` の箇所は、プラグインのネームスペースで置き換えてください。ネームスペースはプラグインの有効化の時に使用した名前と同じになります。 
     92{{{ 
     93>>> import myplugin 
     94>>> print myplugin.__file__ 
     95/opt/local/python24/lib/site-packages/myplugin-0.4.2-py2.4.egg/myplugin/__init__.pyc 
     96}}} 
     97 
     98== プラグインのキャッシュの設定 == #SettingupthePluginCache 
     99 
     100プラグインは Python eggs のランタイム (`pkg_resources`) によって解凍される必要があります。それらの内容がファイルシステム上に実際に存在する必要があるからです。通常は現在のユーザのホームディレクトリの '.python-eggs' に解凍されますが、それにより問題が発生するかもしれません。その場合、環境変数 `PYTHON_EGG_CACHE` を設定してデフォルトのロケーションを上書きすることができます。 
    77101 
    78102`PYTHON_EGG_CACHE` を `SetEnv` ディレクティブを使用して Apache に設定するには以下のようにします: 
    … …  
    100124}}} 
    101125 
    102  ''Note: これは `mod_env` モジュールが必要です。'' 
     126 ''Note: !SetEnv を使用するためには、 Apache で `mod_env` モジュールが有効になっている必要があります。 `mod_python` が設定される Location ブロックでは !SetEnv ディレクティブも使用できます。'' 
    103127 
    104128[wiki:TracFastCgi FastCGI] で、 Web サーバに設定するためには、 `-initial-env` オプションやサーバーが指定している方法で、環境変数を設定する必要があります。 
    105129 
    106 === Subversion の フックスクリプトについて === 
     130 ''Note: プロジェクトディレクトリを設定するために、既に -initial-env を使用している場合は、 [wiki:TracFastCgi TracFastCgi] に例示されるように、必要に応じて -initial-env ディレクティブを !FastCgiConfig ディレクティブに加えてください。'' 
     131 
     132{{{ 
     133FastCgiConfig -initial-env TRAC_ENV=/var/lib/trac -initial-env PYTHON_EGG_CACHE=/var/lib/trac/plugin-cache 
     134}}} 
     135 
     136=== Subversion の フックスクリプトについて === #Abouthookscripts 
    107137 
    108138もし、 Trac エンジンを呼び出すような Subversion の フックスクリプト - Trac の配布物の `/contrib` ディレクトリで提供されている post-commit フックスクリプトなど - を設定していたら、プラグインと同様にスクリプトの中で環境変数 `PYTHON_EGG_CACHE` を定義して下さい。 
    109139 
    110 == トラブルシューティング == 
     140== トラブルシューティング == #Troubleshooting 
    111141 
    112 === setuptools は正しくインストールされていますか？ === 
     142=== setuptools は正しくインストールされていますか？ === #Issetuptoolsproperlyinstalled 
    113143 
    114 これコマンドラインで実行してみてください: 
     144以下のコマンドを実行してみてください: 
    115145{{{ 
    116146$ python -c "import pkg_resources" 
    … …  
    119149もし、コマンドラインから '''何も''' かえって来なければ、 setuptools はインストール '''されています'''。そうでなければ、 Trac を動かす前に setuptools をインストールする必要があります。 
    120150 
    121 === Python egg は正しいバージョンですか？ === 
     151=== Python egg は正しいバージョンですか？ === #DidyougetthecorrectversionofthePythonegg 
    122152 
    123153Python egg はファイル名の中で Python のバージョンをエンコードします。例えば、 `MyPlugin-1.0-py2.4.egg` は Python 2.4 用の Python egg であり、異なる Python のバージョン (2.3 や 2.5) で動かそうとしても '''動かない''' でしょう。 
    … …  
    125155また、ダウンロードした Python egg ファイル が本当に ZIP アーカイブであるかどうかを確認して下さい。もし Trac サイトからダウンロードしたとしたら、 HTML プレビューページを代わりにダウンロードしているかもしれません。 
    126156 
    127 === プラグインは有効になっていますか？ === 
     157=== プラグインは有効になっていますか？ === #Isthepluginenabled 
     158 
    128159 
    129160グローバル領域にプラグインをインストールした場合 (TracEnvironment の `plugin` ディレクトリ内 ''ではなく'') 、 [TracIni trac.ini] に明確に有効にする設定をしなければなりません。以下の事項を確認して下さい: 
    130161 * `[components]` セクションに必要な行数を追加したか。 
    131162 * パッケージ / モジュール名は正しいか 
    132  * もし、(クラスに対して) モジュールを参照しているならば、必要に応じて、 ".*" を追加しているかどうか。 
    133163 * 正しい値、 "enabled" になっているかどうか。例えば、 "enable" ではなく。 
    134164 
    135 === Python egg ファイルのパーミッションのチェック === 
     165=== Python egg ファイルのパーミッションのチェック === #Checkthepermissionsontheeggfile 
    136166 
    137 Trac はもちろん Python egg ファイルを読めなければいけません。分かってるよね。;-) 
     167Trac は Python egg ファイルを読めなければなりません。 
    138168 
    139 === ログファイルのチェック === 
     169=== ログファイルのチェック === #Checkthelogfiles 
    140170 
    141 Trac で [TracLogging logging] を有効にし、ログレベルを `DEBUG` に設定し、プラグインがロードされるときのログメッセージを見て下さい。 
     171Trac で [wiki:TracLogging logging] を有効にし、ログレベルを `DEBUG` に設定し、プラグインがロードされるときのログメッセージを見て下さい。 
     172 
     173=== 必要な権限を持っていることを確認してください === #Verifyyouhaveproperpermissions 
     174 
     175いくつかのプラグインでは、その機能を使用するために特別な権限を要求します。たとえば [http://trac.edgewall.org/wiki/WebAdmin WebAdmin] では、ナビゲーションバーに表示するためには TRAC_ADMIN 権限が必要になります。 
     176 
     177=== 読み込むプラグインのバージョンを間違えていませんか ? === #Isthewrongversionofthepluginloading 
     178 
     179複数のプロジェクトがある場合に plugins ディレクトリにプラグインを置くなら確実に正しいバージョンのプラグインがロードされていることを確認する必要があります。ここにいくつかの基本的なルールがあります: 
     180 * 実行中の 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 
     187plugins に対するログが出力されず、 egg が読み込み可能であり、 Python のバージョンが正しく、 ''その上で'' egg がグローバルにインストールされて (そして trac.ini で使用可能に設定されて) いても、なぜかプラグインが動かず、なんのエラーメッセージも表示されない場合は、 [http://trac.edgewall.org/wiki/IrcChannel IrcChannel] で質問してください。 
    142188 
    143189----