perlnewmod - 新しいモジュールを配布するには
このドキュメントは、Perl モジュールを書き、配布する準備をして、CPAN を 通じて取得可能にするためのアドバイスです。
Perl が実際にこんなに強力な理由の 1 つとして、Perl ハッカーたちが、自分の 直面した問題への解決策を共有しようとしていることが挙げられるでしょう; だから、みんなが同じ問題に悩む必要はないわけです。
これが実現されているのは、多くの場合あるソリューションを抽象化して、 Perl モジュールにしているということです。 もしこれがなんのことかわからなければ、このドキュメントの残りはあまり 役には立たないでしょうし、今までにたくさんの便利なコードを 見逃していることでしょう。 perlmod, perlmodlib, perlmodinstall をよく読んで、ここに戻って 来てください。
もし、あなたがやるべきことに関するモジュールが存在せず、自分でコードを 書かないといけないとなったときには、そのソリューションをモジュールに 詰め込んで CPAN にアップロードすることを検討してください; そうすれば、他のみんなの利益になります。
また、モジュールを作るときのベストプラクティスについて perlmodstyle を 見てみるべきでしょう。
ここでは主にピュア Perl のモジュールについて説明し、XS モジュールについては 触れません。 XS モジュールは、通常とは若干異なる目的で利用されるため、配布する際には 別の問題について考慮する必要があります; つまり、糊付け(glue)の対象となる ライブラリの人気、他の OS へのポータビリティなどです。 しかし、モジュールの準備やパッケージング、配布の説明は、XS モジュールにも 同様に当てはまるでしょう。
他の人に便利になるものなら、どんなコードでもモジュールにするべきです。 みんなが使っているライブラリに足りないものを補って、しかも他の人が自分の プログラムに直接組み込めるものならなんでも OK です。 あなたのコードのうち、単独でとりだして、他のものに組み込めるものがあれば、 それはモジュールの候補になりえるでしょう。
例をとってみましょう。 ローカルのフォーマットからデータを読みだし、Perl のハッシュリファレンスの ハッシュにして、ツリー構造にして、ツリーを操作してそれぞれのノードを Acme Transmogrifier Server にパイプするとします。
さて、Acme Transmogrifier をもっている人はあんまりいないとしましょう; ですから、そのプロトコルを話すコードをスクラッチから書く必要があるでしょう - そんな時、それをモジュールにしたいはずです。 どのレベルで操作するかはあなた次第です: Net::SMTP のような プロトコルレベルのモジュールから、Mail::Send のような高レベルで 操作するモジュールまで。 決定するのはあなたですが、サーバプロトコルに特化したモジュールを 作りたいでしょう。
あなたのローカルデータフォーマットに興味がある人はいないので、それは 無視しましょう。 ただ、その中間データはどうしましょう? Perl 変数からツリー構造を作って、それをトラバースするのはよくあることで、 もしそういったモジュールを誰も書いてないのであれば、そのコードも またモジュール化したくなるでしょう。
さあ、どんなものをモジュール化すればいいのか、だんだんわかってきたでしょう。 これからそれをどうやってやるのか見てみましょう。
コードを書きはじめる前に、やっておきたいことがいくつかあります。
たくさんのモジュールを見て、どんな風に書かれているかみてみましょう。 Text::Tabs は標準ライブラリで、きれいに書かれていてとても シンプルですので、これから始めると良いでしょう; それから File::Copy のようなもう少し複雑なものを見てください。 オブジェクト指向のコードを書こうと思っているなら、 WWW::Mechanize や Mail::* モジュールがよい例となります。
そうすれば、モジュールがどのようにレイアウトされ、書かれているか、大体 わかってくるはずです。
CPAN にはたくさんのモジュールがありますから、あなたが寄与しようとしている モジュールとそっくりなものがあっても、見過ごしてしまうかも知れません。 http://metacpan.org をよく見て、 車輪の再発明をしていないかどうか確認しましょう!
あなたはそれを気に入っているでしょう。 他のみんなも、それを必要とすると思っているでしょう。 でも、実際にはそんなに需要はないかもしれません。 自分のモジュールがどの程度需要があるのか不安だったら、 module-authors@perl.org メーリングリスト (購読するには module-authors-subscribe@perl.org にメールを送ってください; さらなる情報やアーカイブへのリンクは https://lists.perl.org/list/module-authors.html を参照してください) に尋ねてみましょう。
CPAN に含まれる Perl モジュールには、命名階層があり、それに合わせる 必要があります。 これがどのように整理されているかの詳細は、perlmodlib を参照してください; また、CPAN やモジュールリストを見て回って、どんなものか触れてみてください。 少なくとも、これだけは覚えておいてください: モジュール名は大文字で 始める (This::That のように)、 カテゴリに適合している、そして、 目的を簡潔に説明している。
そうしている間に、書こうとしているモジュールに似たモジュールを本当に 見過ごしていないか、確認してください。
整理が付いて、そのモジュールは必要とされていて、まだ存在しないと 確信したら、コードを書きはじめましょう。
module-starter ユーティリティは Module::Starter CPAN パッケージの一部として配布されています。 最近のモジュール開発の「ベストプラクティス」に基づいた、新しいモジュールを 開始するために必要な全てのファイルの雛形を含むディレクトリを作ります; これはコマンドラインから起動されるので:
module-starter --module=Foo::Bar \
--author="Your Name" --email=yourname@cpan.orgModule::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 はモジュールの名前を指定します。
モジュールのコードは warning と strict クリーンでなくてはなりません; どんな状況でそのモジュールが利用されるかわかりませんから。 それに、warning や strict クリーンでないコードなんて、 配布したくないでしょう?
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 は、シンボルやサブルーチンをモジュールから 呼び出し側の名前空間にエクスポートする標準的な方法がわかるでしょう。 たとえば、use Net::Acme qw(&frob) と書けば、frob サブルーチンを インポートします。
パッケージ変数の @EXPORT によって、呼び出し側が単純に use Net::Acme と書いたときに、どのシンボルがエクスポートされるかが 決まります - ほとんどの場合は、ここには何もいれないでしょう。 一方、@EXPORT_OK をつかうと、どの変数をエクスポートしてもよいかを 指定できます。 たくさんのシンボルをエクスポートしたい場合は、%EXPORT_TAGS を 使って、エクスポートのセットを定義しましょう - 詳しくは Exporter を 参照してください。
仕事はペーパーワークがすむまでは、終わりではありません; モジュールのドキュメントを書くための時間が必要です。 module-starter か h2xs を利用すれば、テンプレートを作ってくれますので、 それを埋めればよいです; フォーマットがよくわからなければ、まずは perlpod を見てください。 モジュールをどのように使うかのおおまかな概要、そして文法の説明や、 それぞれのサブルーチンやメソッドの機能説明を提供してください。 開発者のノートとして Perl のコメントを利用し、エンドユーザへの ノートには POD を使ってください。
ぜひユニットテストコードを作って、あなたのモジュールが、いろんな プラットフォーム上の Perl で、意図した通りにうまく動くことを確認しましょう; CPAN にモジュールをアップロードすると、たくさんのテスターがモジュールを ビルドして、テストの結果をあなたに送ってくれるでしょう。 ここでもまた、module-starter と h2xs を使えば、後で拡張可能な、 テストフレームワークが提供されます - 単にコンパイルが通るかだけでなく、 いろいろとテストしましょう。 Test::Simple と Test::More は、テスト スイートを書くときの開始点としてよいものです。
CPAN にアップロードするときは、README ファイルが自動で抽出されて、 あなたの CPAN ディレクトリに置かれます。 また、モジュールリストに載った場合には、by-module や by-category の メインディレクトリにも配置されます。 このファイルに、そのモジュールのすることの詳細を書いておくと良いでしょう。
一つ前のリリースからのユーザーに見える変更点を Changes ファイルに加えます。
CPAN でモジュールを配布するには、CPAN ID が必要です。 http://pause.perl.org/ に訪れて、"Request PAUSE Account" を選択し、 リクエストが PAUSE 管理者に承認されるのを待ちましょう。
perl Makefile.PL; make test; make distcheck; make distここでも、module-starter や h2xs はすべてやってくれます。 モジュールをインストールするときによく見る、標準的な Makefile.PL が できています; これが生成する Makefile に dist ターゲットがあります。
モジュールがテストにパスしたことを確認したら(いつでも確認することは よいことです)、全てが OK かを確認するために make distcheck として、 それから make dist を実行すれば、Makefile はアップロード準備の 整った tarball ファイルを生成してくれます。
CPAN ID を取得できたときに届く email に、PAUSE (the Perl Authors Upload SErver) へのログイン方法が載っています。 メニューから選択して、モジュールをCPANにアップロードできます。
あるいは CPAN の CPAN::Uploader 配布の一部である cpan-upload スクリプトも使えます。
ユーザが集まってくると、バグレポートが送られて来ます。 運がよければ、パッチを送ってくれるでしょう。 ソフトウェアプロジェクトのメンテナンスという喜びが待っています ...
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 による自作のモジュールをビルドするためのチュートリアル。