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 は標準ライブラリで、きれいに書かれていてとても
シンプルですので、これから始めると良いでしょう; それから
File::Copy のようなもう少し複雑なものを見てください。
オブジェクト指向のコードを書こうと思っているなら、
WWW::Mechanize や Mail::* モジュールがよい例となります。
そうすれば、モジュールがどのようにレイアウトされ、書かれているか、大体 わかってくるはずです。
(新しいものかどうかチェックする)
CPAN にはたくさんのモジュールがありますから、あなたが寄与しようとしている モジュールとそっくりなものがあっても、見過ごしてしまうかも知れません。 http://search.cpan.org をよく見て、 車輪の再発明をしていないかどうか確認しましょう!
(必要性を議論する)
あなたはそれを気に入っているでしょう。
他のみんなも、それを必要とすると思っているでしょう。
でも、実際にはそんなに需要はないかもしれません。
自分のモジュールがどの程度需要があるのか不安だったら、
comp.lang.perl.modules に投稿してみましょう。
それでもだめなら、modules@perl.org のモジュールメーリングリストに
聞いてみましょう。
このメーリングリストはクローズドで、待ち時間が長いことに
気を付けてください。
レスポンスが返ってくるまでには、しばらく待つ必要があるかもしれません。
(名前を決める)
CPAN に含まれる Perl モジュールには、命名階層があり、それに合わせる 必要があります。 これがどのように整理されているかの詳細は、perlmodlib を参照してください。 また、CPAN やモジュールリストを見て回って、どんなものか触れてみてください。 少なくとも、これだけは覚えておいてください: モジュール名は大文字で 始める (This::That のように)、 カテゴリに適合している、そして、 目的を簡潔に説明している。
(もう一度チェック)
そうしている間に、書こうとしているモジュールに似たモジュールを本当に 見過ごしていないか、確認してください。
整理が付いて、そのモジュールは必要とされていて、まだ存在しないと 確信したら、コードを書きはじめましょう。
(Step-by-step: モジュールを作る)
(module-starter か h2xs からはじめる)
module-starter ユーティリティは Module::Starter CPAN パッケージの一部として配布されています。 最近のモジュール開発の「ベストプラクティス」に基づいた、新しいモジュールを 開始するために必要な全てのファイルの雛形を含むディレクトリを作ります; これはコマンドラインから起動されるので:
module-starter --module=Foo::Bar \
--author="Your Name" --email=yourname@cpan.org
Module::Starter パッケージを CPAN から インストールしたくない場合は、h2xs はより古いツールで、本来は XS モジュールの開発のためのもので、Perl に同梱されています。
ピュア Perl のための h2xs の典型的な起動方法は:
h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar
-A は Autoloader を省略し、-X は XS を省略し、
--skip-exporter は Exporter コードを省略し、--use-new-tests は
近代的なテスト環境を設定し、-n はモジュールの名前を指定します。
(strict と warnings を使う)
モジュールのコードは warning と strict クリーンでなくてはなりません。 どんな状況でそのモジュールが利用されるかわかりませんから。 それに、warning や strict クリーンでないコードなんて、 配布したくないでしょう?
(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 のままにしておきましょう。
(Exporter を使う - 賢く!)
Exporter は、シンボルやサブルーチンをモジュールから
呼び出し側の名前空間にエクスポートする標準的な方法がわかるでしょう。
たとえば、use Net::Acme qw(&frob) と書けば、frob サブルーチンを
インポートします。
パッケージ変数の @EXPORT によって、呼び出し側が単純に
use Net::Acme と書いたときに、どのシンボルがエクスポートされるかが
決まります。
ほとんどの場合は、ここには何もいれないでしょう。
一方、@EXPORT_OK をつかうと、どの変数をエクスポートしてもよいかを
指定できます。
たくさんのシンボルをエクスポートしたい場合は、%EXPORT_TAGS を
使って、エクスポートのセットを定義しましょう。
詳しくは Exporter を参照してください。
(plain old documentation を使う)
仕事はペーパーワークがすむまでは、終わりではありません。
モジュールのドキュメントを書くための時間が必要です。
module-starter か h2xs を利用すれば、テンプレートを作ってくれますので、
それを埋めればよいです;
フォーマットがよくわからなければ、まずは perlpod を見てください。
モジュールをどのように使うかのおおまかな概要、そして文法の説明や、
それぞれのサブルーチンやメソッドの機能説明を提供してください。
開発者のノートとして Perl のコメントを利用し、エンドユーザへの
ノートには POD を使ってください。
(テストを書く)
ぜひユニットテストコードを作って、あなたのモジュールが、いろんな
プラットフォーム上の Perl で、意図した通りにうまく動くことを確認しましょう。
CPAN にモジュールをアップロードすると、たくさんのテスターがモジュールを
ビルドして、テストの結果をあなたに送ってくれるでしょう。
ここでもまた、module-starter と h2xs を使えば、後で拡張可能な、
テストフレームワークが提供されます。
単にコンパイルが通るかだけでなく、いろいろとテストしましょう。
Test::Simple と Test::More は、テスト
スイートを書くときの開始点としてよいものです。
(README を書く)
CPAN にアップロードするときは、README ファイルが自動で抽出されて、 あなたの CPAN ディレクトリに置かれます。 また、モジュールリストに載った場合には、by-module や by-category の メインディレクトリにも配置されます。 このファイルに、そのモジュールのすることの詳細や、一つ前のリリースからの 変更点を書いておくと良いでしょう。
(Step-by-step: モジュールを配布する)
(CPAN ユーザ ID を取得する)
CPAN でモジュールを配布するには、CPAN ID が必要です。
http://pause.perl.org/ に訪れて、"Request PAUSE Account" を選択し、
リクエストが PAUSE 管理者に承認されるのを待ちましょう。
perl Makefile.PL; make test; make dist
ここでも、module-starter や h2xs はすべてやってくれます。
モジュールをインストールするときによく見る、標準的な Makefile.PL が
できています。
これが生成する Makefile に dist ターゲットがあります。
モジュールがテストにパスしたことを確認したら(いつでも確認することは
よいことです)、make dist を実行すれば、Makefile はアップロード準備の
整った tarball ファイルを生成してくれます。
(tarball をアップロードする)
CPAN ID を取得できたときに届く email に、PAUSE (the Perl Authors Upload SErver) へのログイン方法が載っています。 メニューから選択して、モジュールをCPANにアップロードできます。
(モジュールリストにアナウンスする)
アップロードしたら、あなたのディレクトリにあるだけでは人目を引きません。 他のの CPAN モジュールと同じように載せたければ、PAUSE の "Register Namespace" に行く必要があります。 登録されると、あなたのモジュールは CPAN のモジュール別およびカテゴリ別の リストに表示されます。
(clpa にアナウンスする)
リリースしたことを世界中にアナウンスしたいという野望があるなら、
モデレートされている、comp.lang.perl.announce ニュースグループに
アナウンスを投稿してみましょう。
(バグをなおす!)
ユーザが集まってくると、バグレポートが送られて来ます。 運がよければ、パッチを送ってくれるでしょう。 ソフトウェアプロジェクトのメンテナンスという喜びが待っています ...
Simon Cozens, simon@cpan.org
Updated by Kirrily "Skud" Robert, skud@cpan.org
perlmod, perlmodlib, perlmodinstall, h2xs, strict, Carp, Exporter, perlpod, Test::Simple, Test::More ExtUtils::MakeMaker, Module::Build, Module::Starter http://www.cpan.org/ , http://mathforum.org/~ken/perl_modules.html にある、 Ken Williams による自作のモジュールをビルドするためのチュートリアル。