=encoding euc-jp =head1 名前 perlnewmod - 新しいモジュールを配布するには =head1 説明 このドキュメントは、Perl モジュールを書き、配布する準備をして、CPAN を 通じて取得可能にするためのアドバイスです。 Perl が実際にこんなに強力な理由の1つとして、Perl ハッカーたちが、自分 の直面した問題への解決策を共有しようとしていることが挙げられるでしょう。 だから、みんなが同じ問題に悩む必要はないわけです。 これが実現されているのは、多くの場合あるソリューションを抽象化して、 Perl モジュールにしているということです。もしこれがなんのことかわから なければ、このドキュメントの残りはあまり役には立たないでしょうし、今ま でにたくさんの便利なコードを見逃していることでしょう。L, L, L をよく読んで、ここに戻って来てくださ い。 もし、あなたがやるべきことに関するモジュールが存在せず、自分でコードを 書かないといけないとなったときには、そのソリューションをモジュールに詰 め込んで CPAN にアップロードすることを検討してください。そうすれば、他 のみんなの利益になります。 =head2 警告 ここでは主にピュアPerl のモジュールについて説明し、XS モジュールについ ては触れません。XS モジュールは、通常とは若干異なる目的で利用されるた め、配布する際には別の問題について考慮する必要があります。つまり、糊付 け(glue)の対象となるライブラリの人気、他のOSへのポータビリティなどです。 しかし、モジュールの準備やパッケージング、配布の説明は、XS モジュール にも同様に当てはまるでしょう。 =head2 なにをモジュールにしたらいい？ 他の人に便利になるものなら、どんなコードでもモジュールにするべきです。 みんなが使っているライブラリに足りないものを補って、しかも他の人が自分 のプログラムに直接組み込めるものならなんでもOKです。あなたのコードのう ち、単独でとりだして、他のものに組み込めるものがあれば、それはモジュー ルの候補になりえるでしょう。 例をとってみましょう。ローカルのフォーマットからデータを読みだし、Perl のハッシュリファレンスのハッシュにして、ツリー構造にして、ツリーを操作 してそれぞれのノードを Acme Transmogrifier Server にパイプするとします。 さて、Acme Transmogrifier をもっている人はあんまりいないとしましょう。 ですから、そのプロトコルを話すコードをスクラッチから書かなくてはならな いでしょう。そんな時、それをモジュールにしたいはずです。どのレベルで操 作するかはあなた次第です。L のようなプロトコルレベルのモジュー ルから、L のような高レベルで操作するモジュールまで。決定す るのはあなたですが、サーバプロトコルに特化したモジュールをつくりたいで しょう。 あなたのローカルデータフォーマットに興味がある人はいません。だからそれ は無視しましょう。ただ、その中間データはどうしましょう。Perl 変数から ツリー構造を作って、それをトラバースするのはよくあることです。それに、 もしそういったモジュールを誰もかいてないのであれば、そのコードもまたモ ジュール化したくなるでしょう。 さあ、どんなものをモジュール化すればいいのか、だんだんわかってきたでしょ う。これからそれをどうやってやるのか見てみましょう。 =head2 Step-by-step: 地面の整備 コードを書きはじめるまえに、やっておきたいことがいくつかあります。 =over 3 =item 見てまわる たくさんのモジュールをみて、どんな風に書かれているかみてみましょう。 L は標準ライブラリで、きれいに書かれていてとてもシンプルで すので、これからはじめるとよいでしょう。次に L や L、それにもしオブジェクト指向のコードを書こうと思っている なら、C のいくつかをみてみるとよいでしょう。 そうすれば、モジュールがどのようにレイアウトされ、書かれているか、大体 わかってくるはずです。 =item 新しいものかどうかチェックする CPAN にはたくさんのモジュールがありますから、あなたがコントリビュート しようとしているモジュールとそっくりなものがあっても、見過ごしてしまう かも知れません。モジュールリストや F ディレクトリをよくみて、 車輪の再発明をしていないかどうか確認しましょう! =item 必要性を議論する あなたはそれを気に入っているでしょう。他のみんなも、それを必要とすると 思っているでしょう。でも、実際にはそんなに需要はないかもしれません。自 分のモジュールがどの程度需要があるのか不安だったら、 C に投稿してみましょう。それでもだめなら、 C のモジュールメーリングリストに聞いてみましょう。こ のメーリングリストはクローズドで、待ち時間が長いことに気を付けてくださ い。レスポンスが返ってくるまでには、しばらく待つ必要があるかもしれませ ん。 =item 名前を決める CPAN にふくまれる Perl モジュールには、ネーミング階層があり、それに合 わせる必要があります。これがどのように整理されているかの詳細は、 L をみてください。また、CPAN やモジュールリストを見て回っ て、どんなものか触れてみてください。少なくとも、これだけは覚えておいて ください: モジュール名は大文字ではじめる (This::That のように), カテゴ リに適合している、そして、目的を簡潔に説明している。 =item もう一度チェック そうしている間に、書こうとしているモジュールに似たモジュールを本当に見 過ごしていないか、確認してください。 整理が付いて、そのモジュールは必要とされていて、まだ存在しないと確信し たら、コードを書きはじめましょう。 =back =head2 Step-by-step: モジュールを作る =over 3 =item F からはじめる Lは、もともとは CヘッダファイルをXS モジュールにするためのユーティ リティだったのですが、ピュア Perl モジュール用のスケルトンをつくるユー ティリティとしても便利です。もし L (大きなモジュールを小さ なルーチンに分割するモジュール) が必要なければ、以下のように実行します: h2xs -AX -n Net::Acme C<-A> は Autoloader を省略し、C<-X> は XS を省略します。C<-n> でモジュー ルの名前を指定します。 =item Use L and L モジュールのコードは warning と strict クリーンでなくてはなりません。 どんな状況でそのモジュールが利用されるかわかりませんから。それに、 warning や strict クリーンでないコードなんて、配布したくないでしょう? =item Use L L モジュールを使うと、エラーメッセージを呼び出し側の視点から出力 することが出来ます。そのモジュールではなく、呼び出し側の問題であること を示せるのです。たとえば、このようにすると: warn "No hostname given"; ユーザはこのようなメッセージを見ることになります: No hostname given at /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm line 123. これでは、あなたのモジュールが何か間違ったことをしているように見えます。 代わりに、ユーザに責任をなすりつけられるのです。このように出力します: No hostname given at bad_code, line 10. こうするには、L をつかって、C を C に置き換えます。 もし C する必要があるなら、C を使いましょう。ただ、本当に あなたのモジュールの責任によるチェックの場合は、C や C のま まにしておきましょう。 =item Use L - かしこく! C は L の切れ端を提供します。これによって、シンボルや サブルーチンをモジュールから呼び出し側の名前空間にエクスポートする標準 的な方法がわかるでしょう。たとえば、C と書け ば、C サブルーチンをインポートします。 パッケージ変数の C<@EXPORT> によって、呼び出し側が単純に C と書いたときに、どのシンボルがエクスポートされるかが決まり ます。ほとんどの場合は、ここには何もいれくないでしょう。一方、 C<@EXPORT_OK> をつかうと、どの変数をエクスポートしてもよいかを指定でき ます。たくさんのシンボルをエクスポートしたい場合は、C<%EXPORT_TAGS> を つかって、エクスポートのセットを定義しましょう。詳しくは L を見てください。 =item plain old documentation をつかう 仕事はペーパーワークがすむまでは、終わりではありません。モジュールのド キュメントを書くための時間が必要です。C を利用すれば、テンプレー トをつくってくれますので、それを埋めればよいです。フォーマットがよくわ からなければ、まずは L を見てください。モジュールをどのように 使うかのおおまかな概要、そしてシンタックスの説明や、それぞれのサブルー チンやメソッドの機能説明を提供してください。開発者のノートとして Perl のコメントを利用し、エンドユーザへのノートには POD を使ってください。 =item テストを書く ぜひユニットテストコードをつくって、あなたのモジュールが、いろんなプラッ トフォーム上の Perl で、意図した通りにうまく動くことを確認しましょう。 CPAN にモジュールをアップロードすると、たくさんのテスターがモジュール をビルドして、テストの結果をあなたに送ってくれるでしょう。ここでもまた、 C をつかえば、あとで拡張可能な、テストフレームワークが提供されま す。単にコンパイルが通るかだけでなく、いろいろとテストしましょう。 =item README を書く CPAN にアップロードするときは、README ファイルが自動で抽出されて、あな たの CPAN ディレクトリにおかれます。また、モジュールリストに載った場合 には、F や F のメインディレクトリにも配置され ます。このファイルに、そのモジュールのすることの詳細や、一つ前のリリー スからの変更点を書いておくと良いでしょう。 =back =head2 Step-by-step: モジュールを配布する =over 3 =item CPAN ユーザ IDを取得する CPAN でモジュールを配布するには、CPAN ID が必要です。どうやって取得す るかは、C (もしくはそのミラー) の指示を読んでください。 =item C ここでも、C はすべてやってくれます。モジュールをインストールする ときによくみる、標準的な C ができています。これが生成する Makefile に C ターゲットがあります。 モジュールがテストにパスしたことを確認したら(いつでも確認することはよ いことです)、 C を実行すれば、Makefile はアップロード準備の ととのった tarball ファイルを生成してくれます。 =item tarball をアップロードする CPAN ID を取得できたときに届く email に、PAUSE (the Perl Authors Upload SErver) へのログイン方法が載っています。メニューから選択して、 モジュールをCPANにアップロードできます。 =item モジュールリストにアナウンスする アップロードしたら、あなたのディレクトリにあるだけでは人目を引きません。 のこりの CPAN モジュールと同じように載せたければ、モジュールリストにそ のことを伝えます。一番良い方法は、モジュールリストと同じスタイルで Email をこんな感じでかくことです: Net::Acme bdpOP Interface to Acme Frobnicator servers FOOBAR ^ ^^^^^ ^ ^ | ||||| モジュールの説明 あなたのID | ||||| | ||||\-ライセンス: (p)standard Perl, (g)GPL, (b)BSD, | |||| (l)LGPL, (a)rtistic, (o)ther | |||| | |||\- インタフェース: (O)OP, (r)eferences, (h)ybrid, (f)unctions | ||| | ||\-- 言語: (p)ure Perl, C(+)+, (h)ybrid, (C), (o)ther | || Module |\--- サポート: (d)eveloper, (m)ailing list, (u)senet, (n)one Name | \---- 開発状況: (i)dea, (c)onstructions, (a)lpha, (b)eta, (R)eleased, (M)ature, (S)tandard それに、モジュールの説明と、これがリストに含まれるべき理由を記述します。 何も答えが返って来なければ、次の更新で、モジュールリストに掲載されるで しょう。C に subscribe しようとしないようにしてくだ さい。これはメーリングリストではないのです。我慢してください。 =item clpa にアナウンスする リリースしたことを世界中にアナウンスしたいという野望があるなら、モデレー トされている、C ニュースグループにアナウンス を投稿してみましょう。 =item バグをなおす! ユーザが集まってくると、バグレポートが送られて来ます。運がよければ、パッ チを送ってくれるでしょう。ソフトウェアプロジェクトのメンテナンスという 喜びが待っています ... =back =head1 AUTHOR Simon Cozens, C =head1 SEE ALSO L, L, L, L, L, L, L, L, L, L, http://www.cpan.org/, Ken Williams' tutorial on building your own module at http://mathforum.org/~ken/perl_modules.html