名前¶

perlnewmod - 新しいモジュールを配布するには

説明¶

このドキュメントは、Perl モジュールを書き、配布する準備をして、CPAN を 通じて取得可能にするためのアドバイスです。

Perl が実際にこんなに強力な理由の1つとして、Perl ハッカーたちが、自分 の直面した問題への解決策を共有しようとしていることが挙げられるでしょう。 だから、みんなが同じ問題に悩む必要はないわけです。

これが実現されているのは、多くの場合あるソリューションを抽象化して、 Perl モジュールにしているということです。もしこれがなんのことかわから なければ、このドキュメントの残りはあまり役には立たないでしょうし、今ま でにたくさんの便利なコードを見逃していることでしょう。perlmod, perlmodlib, perlmodinstall をよく読んで、ここに戻って来てくださ い。

もし、あなたがやるべきことに関するモジュールが存在せず、自分でコードを 書かないといけないとなったときには、そのソリューションをモジュールに詰 め込んで CPAN にアップロードすることを検討してください。そうすれば、他 のみんなの利益になります。

警告¶

ここでは主にピュアPerl のモジュールについて説明し、XS モジュールについ ては触れません。XS モジュールは、通常とは若干異なる目的で利用されるた め、配布する際には別の問題について考慮する必要があります。つまり、糊付 け(glue)の対象となるライブラリの人気、他のOSへのポータビリティなどです。 しかし、モジュールの準備やパッケージング、配布の説明は、XS モジュール にも同様に当てはまるでしょう。

なにをモジュールにしたらいい？¶

他の人に便利になるものなら、どんなコードでもモジュールにするべきです。 みんなが使っているライブラリに足りないものを補って、しかも他の人が自分 のプログラムに直接組み込めるものならなんでもOKです。あなたのコードのう ち、単独でとりだして、他のものに組み込めるものがあれば、それはモジュー ルの候補になりえるでしょう。

例をとってみましょう。ローカルのフォーマットからデータを読みだし、Perl のハッシュリファレンスのハッシュにして、ツリー構造にして、ツリーを操作 してそれぞれのノードを Acme Transmogrifier Server にパイプするとします。

さて、Acme Transmogrifier をもっている人はあんまりいないとしましょう。 ですから、そのプロトコルを話すコードをスクラッチから書かなくてはならな いでしょう。そんな時、それをモジュールにしたいはずです。どのレベルで操 作するかはあなた次第です。Net::SMTP のようなプロトコルレベルのモジュー ルから、Mail::Send のような高レベルで操作するモジュールまで。決定す るのはあなたですが、サーバプロトコルに特化したモジュールをつくりたいで しょう。

あなたのローカルデータフォーマットに興味がある人はいません。だからそれ は無視しましょう。ただ、その中間データはどうしましょう。Perl 変数から ツリー構造を作って、それをトラバースするのはよくあることです。それに、 もしそういったモジュールを誰もかいてないのであれば、そのコードもまたモ ジュール化したくなるでしょう。

さあ、どんなものをモジュール化すればいいのか、だんだんわかってきたでしょ う。これからそれをどうやってやるのか見てみましょう。

Step-by-step: 地面の整備¶

コードを書きはじめるまえに、やっておきたいことがいくつかあります。

見てまわる

たくさんのモジュールをみて、どんな風に書かれているかみてみましょう。 Text::Tabs は標準ライブラリで、きれいに書かれていてとてもシンプルで すので、これからはじめるとよいでしょう。次に Time::Zone や File::Copy、それにもしオブジェクト指向のコードを書こうと思っている なら、Mail::* のいくつかをみてみるとよいでしょう。

そうすれば、モジュールがどのようにレイアウトされ、書かれているか、大体 わかってくるはずです。

新しいものかどうかチェックする

CPAN にはたくさんのモジュールがありますから、あなたがコントリビュート しようとしているモジュールとそっくりなものがあっても、見過ごしてしまう かも知れません。モジュールリストや by-module ディレクトリをよくみて、 車輪の再発明をしていないかどうか確認しましょう!

必要性を議論する

あなたはそれを気に入っているでしょう。他のみんなも、それを必要とすると 思っているでしょう。でも、実際にはそんなに需要はないかもしれません。自 分のモジュールがどの程度需要があるのか不安だったら、 comp.lang.perl.modules に投稿してみましょう。それでもだめなら、 [email protected] のモジュールメーリングリストに聞いてみましょう。こ のメーリングリストはクローズドで、待ち時間が長いことに気を付けてくださ い。レスポンスが返ってくるまでには、しばらく待つ必要があるかもしれませ ん。

名前を決める

CPAN にふくまれる Perl モジュールには、ネーミング階層があり、それに合 わせる必要があります。これがどのように整理されているかの詳細は、 perlmodlib をみてください。また、CPAN やモジュールリストを見て回っ て、どんなものか触れてみてください。少なくとも、これだけは覚えておいて ください: モジュール名は大文字ではじめる (This::That のように), カテゴ リに適合している、そして、目的を簡潔に説明している。

もう一度チェック

そうしている間に、書こうとしているモジュールに似たモジュールを本当に見 過ごしていないか、確認してください。

整理が付いて、そのモジュールは必要とされていて、まだ存在しないと確信し たら、コードを書きはじめましょう。

Step-by-step: モジュールを作る¶

h2xs からはじめる

h2xsは、もともとは CヘッダファイルをXS モジュールにするためのユーティ リティだったのですが、ピュア Perl モジュール用のスケルトンをつくるユー ティリティとしても便利です。もし Autoloader (大きなモジュールを小さ なルーチンに分割するモジュール) が必要なければ、以下のように実行します:

    h2xs -AX -n Net::Acme

-A は Autoloader を省略し、-X は XS を省略します。-n でモジュー ルの名前を指定します。

Use strict and warnings

モジュールのコードは warning と strict クリーンでなくてはなりません。 どんな状況でそのモジュールが利用されるかわかりませんから。それに、 warning や strict クリーンでないコードなんて、配布したくないでしょう?

Use Carp

Carp モジュールを使うと、エラーメッセージを呼び出し側の視点から出力 することが出来ます。そのモジュールではなく、呼び出し側の問題であること を示せるのです。たとえば、このようにすると:

    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.

こうするには、Carp をつかって、warn を carp に置き換えます。 もし die する必要があるなら、croak を使いましょう。ただ、本当に あなたのモジュールの責任によるチェックの場合は、warn や die のま まにしておきましょう。

Use Exporter - かしこく!

h2xs は Exporter の切れ端を提供します。これによって、シンボルや サブルーチンをモジュールから呼び出し側の名前空間にエクスポートする標準 的な方法がわかるでしょう。たとえば、use Net::Acme qw(&frob) と書け ば、frob サブルーチンをインポートします。

パッケージ変数の @EXPORT によって、呼び出し側が単純に use Net::Acme と書いたときに、どのシンボルがエクスポートされるかが決まり ます。ほとんどの場合は、ここには何もいれくないでしょう。一方、 @EXPORT_OK をつかうと、どの変数をエクスポートしてもよいかを指定でき ます。たくさんのシンボルをエクスポートしたい場合は、%EXPORT_TAGS を つかって、エクスポートのセットを定義しましょう。詳しくは Exporter を見てください。

plain old documentation をつかう

仕事はペーパーワークがすむまでは、終わりではありません。モジュールのド キュメントを書くための時間が必要です。h2xs を利用すれば、テンプレー トをつくってくれますので、それを埋めればよいです。フォーマットがよくわ からなければ、まずは perlpod を見てください。モジュールをどのように 使うかのおおまかな概要、そしてシンタックスの説明や、それぞれのサブルー チンやメソッドの機能説明を提供してください。開発者のノートとして Perl のコメントを利用し、エンドユーザへのノートには POD を使ってください。

テストを書く

ぜひユニットテストコードをつくって、あなたのモジュールが、いろんなプラッ トフォーム上の Perl で、意図した通りにうまく動くことを確認しましょう。 CPAN にモジュールをアップロードすると、たくさんのテスターがモジュール をビルドして、テストの結果をあなたに送ってくれるでしょう。ここでもまた、 h2xs をつかえば、あとで拡張可能な、テストフレームワークが提供されま す。単にコンパイルが通るかだけでなく、いろいろとテストしましょう。

README を書く

CPAN にアップロードするときは、README ファイルが自動で抽出されて、あな たの CPAN ディレクトリにおかれます。また、モジュールリストに載った場合 には、by-module や by-category のメインディレクトリにも配置され ます。このファイルに、そのモジュールのすることの詳細や、一つ前のリリー スからの変更点を書いておくと良いでしょう。

Step-by-step: モジュールを配布する¶

CPAN ユーザ IDを取得する

CPAN でモジュールを配布するには、CPAN ID が必要です。どうやって取得す るかは、http://www.cpan.org/modules/04pause.html (もしくはそのミラー) の指示を読んでください。

perl Makefile.PL; make test; make dist

ここでも、h2xs はすべてやってくれます。モジュールをインストールする ときによくみる、標準的な Makefile.PL ができています。これが生成する Makefile に dist ターゲットがあります。

モジュールがテストにパスしたことを確認したら(いつでも確認することはよ いことです)、 make dist を実行すれば、Makefile はアップロード準備の ととのった tarball ファイルを生成してくれます。

tarball をアップロードする

CPAN ID を取得できたときに届く email に、PAUSE (the Perl Authors Upload SErver) へのログイン方法が載っています。メニューから選択して、 モジュールをCPANにアップロードできます。

モジュールリストにアナウンスする

アップロードしたら、あなたのディレクトリにあるだけでは人目を引きません。 のこりの 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

それに、モジュールの説明と、これがリストに含まれるべき理由を記述します。 何も答えが返って来なければ、次の更新で、モジュールリストに掲載されるで しょう。[email protected] に subscribe しようとしないようにしてくだ さい。これはメーリングリストではないのです。我慢してください。

clpa にアナウンスする

リリースしたことを世界中にアナウンスしたいという野望があるなら、モデレー トされている、comp.lang.perl.announce ニュースグループにアナウンス を投稿してみましょう。

バグをなおす!

ユーザが集まってくると、バグレポートが送られて来ます。運がよければ、パッ チを送ってくれるでしょう。ソフトウェアプロジェクトのメンテナンスという 喜びが待っています ...

作者¶

Simon Cozens, [email protected]

SEE ALSO¶

perlmod, perlmodlib, perlmodinstall, h2xs, strict, Carp, Exporter, perlpod, Test, ExtUtils::MakeMaker, http://www.cpan.org/, Ken Williams' tutorial on building your own module at http://mathforum.org/~ken/perl_modules.html