名前¶

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 変数からツリー構造を作って、それをトラバースするのはよくあることで、 もしそういったモジュールを誰も書いてないのであれば、そのコードも またモジュール化したくなるでしょう。

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

Step-by-step: 地ならし¶

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

Look around

(見てまわる)

Dig into a bunch of modules to see how they're written. I'd suggest starting with Text::Tabs, since it's in the standard library and is nice and simple, and then looking at something a little more complex like File::Copy. For object oriented code, WWW::Mechanize or the Email::* modules provide some good examples.

たくさんのモジュールを見て、どんな風に書かれているかみてみましょう。 Text::Tabs は標準ライブラリで、きれいに書かれていてとても シンプルですので、これから始めると良いでしょう; それから File::Copy のようなもう少し複雑なものを見てください。 オブジェクト指向のコードを書こうと思っているなら、 WWW::Mechanize や Mail::* モジュールがよい例となります。

These should give you an overall feel for how modules are laid out and written.

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

Check it's new

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

There are a lot of modules on CPAN, and it's easy to miss one that's similar to what you're planning on contributing. Have a good plough through http://metacpan.org and make sure you're not the one reinventing the wheel!

CPAN にはたくさんのモジュールがありますから、あなたが寄与しようとしている モジュールとそっくりなものがあっても、見過ごしてしまうかも知れません。 http://metacpan.org をよく見て、 車輪の再発明をしていないかどうか確認しましょう!

Discuss the need

(必要性を議論する)

You might love it. You might feel that everyone else needs it. But there might not actually be any real demand for it out there. If you're unsure about the demand your module will have, consider asking the module-authors@perl.org mailing list (send an email to module-authors-subscribe@perl.org to subscribe; see http://lists.perl.org/list/module-authors.html for more information and a link to the archives).

あなたはそれを気に入っているでしょう。 他のみんなも、それを必要とすると思っているでしょう。 でも、実際にはそんなに需要はないかもしれません。 自分のモジュールがどの程度需要があるのか不安だったら、 module-authors@perl.org メーリングリスト (購読するには module-authors-subscribe@perl.org にメールを送ってください; さらなる情報やアーカイブへのリンクは http://lists.perl.org/list/module-authors.html を参照してください) に尋ねてみましょう。

Choose a name

(名前を決める)

Perl modules included on CPAN have a naming hierarchy you should try to fit in with. See perlmodlib for more details on how this works, and browse around CPAN and the modules list to get a feel of it. At the very least, remember this: modules should be title capitalised, (This::Thing) fit in with a category, and explain their purpose succinctly.

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

Check again

(もう一度チェック)

While you're doing that, make really sure you haven't missed a module similar to the one you're about to write.

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

When you've got your name sorted out and you're sure that your module is wanted and not currently available, it's time to start coding.

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

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

Start with module-starter or h2xs

(module-starter か h2xs からはじめる)

The module-starter utility is distributed as part of the Module::Starter CPAN package. It creates a directory with stubs of all the necessary files to start a new module, according to recent "best practice" for module development, and is invoked from the command line, thus:

module-starter ユーティリティは Module::Starter CPAN パッケージの一部として配布されています。 最近のモジュール開発の「ベストプラクティス」に基づいた、新しいモジュールを 開始するために必要な全てのファイルの雛形を含むディレクトリを作ります; これはコマンドラインから起動されるので:

    module-starter --module=Foo::Bar \
       --author="Your Name" --email=yourname@cpan.org

If you do not wish to install the Module::Starter package from CPAN, h2xs is an older tool, originally intended for the development of XS modules, which comes packaged with the Perl distribution.

Module::Starter パッケージを CPAN から インストールしたくない場合は、h2xs はより古いツールで、本来は XS モジュールの開発のためのもので、Perl に同梱されています。

A typical invocation of h2xs for a pure Perl module is:

ピュア Perl のための h2xs の典型的な起動方法は:

    h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar 

The -A omits the Autoloader code, -X omits XS elements, --skip-exporter omits the Exporter code, --use-new-tests sets up a modern testing environment, and -n specifies the name of the module.

-A は Autoloader を省略し、-X は XS を省略し、 --skip-exporter は Exporter コードを省略し、--use-new-tests は 近代的なテスト環境を設定し、-n はモジュールの名前を指定します。

Use strict and warnings

(strict と warnings を使う)

A module's code has to be warning and strict-clean, since you can't guarantee the conditions that it'll be used under. Besides, you wouldn't want to distribute code that wasn't warning or strict-clean anyway, right?

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

Use Carp

(Carp を使う)

The Carp module allows you to present your error messages from the caller's perspective; this gives you a way to signal a problem with the caller and not your module. For instance, if you say this:

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

    warn "No hostname given";

the user will see something like this:

ユーザはこのようなメッセージを見ることになります:

 No hostname given at
 /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm line 123.

which looks like your module is doing something wrong. Instead, you want to put the blame on the user, and say this:

これでは、あなたのモジュールが何か間違ったことをしているように見えます。 代わりに、ユーザに責任をなすりつけられるのです; このように出力します:

    No hostname given at bad_code, line 10.

You do this by using Carp and replacing your warns with carps. If you need to die, say croak instead. However, keep warn and die in place for your sanity checks - where it really is your module at fault.

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

Use Exporter - wisely!

(Exporter を使う - 賢く!)

Exporter gives you a standard way of exporting symbols and subroutines from your module into the caller's namespace. For instance, saying use Net::Acme qw(&frob) would import the frob subroutine.

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

The package variable @EXPORT will determine which symbols will get exported when the caller simply says use Net::Acme - you will hardly ever want to put anything in there. @EXPORT_OK, on the other hand, specifies which symbols you're willing to export. If you do want to export a bunch of symbols, use the %EXPORT_TAGS and define a standard export set - look at Exporter for more details.

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

Use plain old documentation

(plain old documentation を使う)

The work isn't over until the paperwork is done, and you're going to need to put in some time writing some documentation for your module. module-starter or h2xs will provide a stub for you to fill in; if you're not sure about the format, look at perlpod for an introduction. Provide a good synopsis of how your module is used in code, a description, and then notes on the syntax and function of the individual subroutines or methods. Use Perl comments for developer notes and POD for end-user notes.

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

Write tests

(テストを書く)

You're encouraged to create self-tests for your module to ensure it's working as intended on the myriad platforms Perl supports; if you upload your module to CPAN, a host of testers will build your module and send you the results of the tests. Again, module-starter and h2xs provide a test framework which you can extend - you should do something more than just checking your module will compile. Test::Simple and Test::More are good places to start when writing a test suite.

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

Write the README

(README を書く)

If you're uploading to CPAN, the automated gremlins will extract the README file and place that in your CPAN directory. It'll also appear in the main by-module and by-category directories if you make it onto the modules list. It's a good idea to put here what the module actually does in detail.

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

Write Changes

(Changes を書く)

Add any user-visible changes since the last release to your Changes file.

一つ前のリリースからのユーザーに見える変更点を Changes ファイルに加えます。

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

Get a CPAN user ID

(CPAN ユーザ ID を取得する)

Every developer publishing modules on CPAN needs a CPAN ID. Visit http://pause.perl.org/, select "Request PAUSE Account", and wait for your request to be approved by the PAUSE administrators.

CPAN でモジュールを配布するには、CPAN ID が必要です。 http://pause.perl.org/ に訪れて、"Request PAUSE Account" を選択し、 リクエストが PAUSE 管理者に承認されるのを待ちましょう。

perl Makefile.PL; make test; make distcheck; make dist

Once again, module-starter or h2xs has done all the work for you. They produce the standard Makefile.PL you see when you download and install modules, and this produces a Makefile with a dist target.

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

Once you've ensured that your module passes its own tests - always a good thing to make sure - you can make distcheck to make sure everything looks OK, followed by make dist, and the Makefile will hopefully produce you a nice tarball of your module, ready for upload.

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

Upload the tarball

(tarball をアップロードする)

The email you got when you received your CPAN ID will tell you how to log in to PAUSE, the Perl Authors Upload SErver. From the menus there, you can upload your module to CPAN.

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

Alternatively you can use the cpan-upload script, part of the CPAN::Uploader distribution on CPAN.

あるいは CPAN の CPAN::Uploader 配布の一部である cpan-upload スクリプトも使えます。

Fix bugs!

(バグをなおす!)

Once you start accumulating users, they'll send you bug reports. If you're lucky, they'll even send you patches. Welcome to the joys of maintaining a software project...

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

作者¶

Simon Cozens, simon@cpan.org

Updated by Kirrily "Skud" Robert, skud@cpan.org

SEE ALSO¶

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 による自作のモジュールをビルドするためのチュートリアル。