perl/5.12.1/perlnewmod.pod


=encoding euc-jp

=head1 NAME

=begin original

perlnewmod - preparing a new module for distribution

=end original

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

=head1 DESCRIPTION

=begin original

This document gives you some suggestions about how to go about writing
Perl modules, preparing them for distribution, and making them available
via CPAN.

=end original

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

=begin original

One of the things that makes Perl really powerful is the fact that Perl
hackers tend to want to share the solutions to problems they've faced,
so you and I don't have to battle with the same problem again.

=end original

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

=begin original

The main way they do this is by abstracting the solution into a Perl
module. If you don't know what one of these is, the rest of this
document isn't going to be much use to you. You're also missing out on
an awful lot of useful code; consider having a look at L<perlmod>,
L<perlmodlib> and L<perlmodinstall> before coming back here.

=end original

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

=begin original

When you've found that there isn't a module available for what you're
trying to do, and you've had to write the code yourself, consider
packaging up the solution into a module and uploading it to CPAN so that
others can benefit.

=end original

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

=head2 Warning

(警告)

=begin original

We're going to primarily concentrate on Perl-only modules here, rather
than XS modules. XS modules serve a rather different purpose, and
you should consider different things before distributing them - the
popularity of the library you are gluing, the portability to other
operating systems, and so on. However, the notes on preparing the Perl
side of the module and packaging and distributing it will apply equally
well to an XS module as a pure-Perl one.

=end original

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

=head2 What should I make into a module?

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

=begin original

You should make a module out of any code that you think is going to be
useful to others. Anything that's likely to fill a hole in the communal
library and which someone else can slot directly into their program. Any
part of your code which you can isolate and extract and plug into
something else is a likely candidate.

=end original

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

=begin original

Let's take an example. Suppose you're reading in data from a local
format into a hash-of-hashes in Perl, turning that into a tree, walking
the tree and then piping each node to an Acme Transmogrifier Server.

=end original

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

=begin original

Now, quite a few people have the Acme Transmogrifier, and you've had to
write something to talk the protocol from scratch - you'd almost
certainly want to make that into a module. The level at which you pitch
it is up to you: you might want protocol-level modules analogous to
L<Net::SMTP|Net::SMTP> which then talk to higher level modules analogous
to L<Mail::Send|Mail::Send>. The choice is yours, but you do want to get
a module out for that server protocol.

=end original

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

=begin original

Nobody else on the planet is going to talk your local data format, so we
can ignore that. But what about the thing in the middle? Building tree
structures from Perl variables and then traversing them is a nice,
general problem, and if nobody's already written a module that does
that, you might want to modularise that code too.

=end original

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

=begin original

So hopefully you've now got a few ideas about what's good to modularise.
Let's now see how it's done.

=end original

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

=head2 Step-by-step: Preparing the ground

(Step-by-step: 地ならし)

=begin original

Before we even start scraping out the code, there are a few things we'll
want to do in advance.

=end original

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

=over 3

=item Look around

(見てまわる)

=begin original

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

=end original

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

=begin original

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

=end original

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

=item Check it's new

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

=begin original

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 the L<http://search.cpan.org> and make sure you're not the one
reinventing the wheel!

=end original

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

=item Discuss the need

(必要性を議論する)

=begin original

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 sending out feelers
on the C<comp.lang.perl.modules> newsgroup, or as a last resort, ask the
modules list at C<modules@perl.org>. Remember that this is a closed list
with a very long turn-around time - be prepared to wait a good while for
a response from them.

=end original

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

=item Choose a name

(名前を決める)

=begin original

Perl modules included on CPAN have a naming hierarchy you should try to
fit in with. See L<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.

=end original

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

=item Check again

(もう一度チェック)

=begin original

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

=end original

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

=begin original

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.

=end original

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

=back

=head2 Step-by-step: Making the module

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

=over 3

=item Start with F<module-starter> or F<h2xs>

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

=begin original

The F<module-starter> utility is distributed as part of the
L<Module::Starter|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:

=end original

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

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

=begin original

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

=end original

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

=begin original

A typical invocation of L<h2xs|h2xs> for a pure Perl module is:

=end original

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

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

=begin original

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

=end original

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

=item Use L<strict|strict> and L<warnings|warnings>

(L<strict|strict> と L<warnings|warnings> を使う)

=begin original

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?

=end original

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

=item Use L<Carp|Carp>

(L<Carp|Carp> を使う)

=begin original

The L<Carp|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:

=end original

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

    warn "No hostname given";

=begin original

the user will see something like this:

=end original

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

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

=begin original

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

=end original

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

    No hostname given at bad_code, line 10.

=begin original

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

=end original

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

=item Use L<Exporter|Exporter> - wisely!

(L<Exporter|Exporter> を使う - 賢く!)

=begin original

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

=end original

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

=begin original

The package variable C<@EXPORT> will determine which symbols will get
exported when the caller simply says C<use Net::Acme> - you will hardly
ever want to put anything in there. C<@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 C<%EXPORT_TAGS> and define a standard
export set - look at L<Exporter> for more details.

=end original

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

=item Use L<plain old documentation|perlpod>

(L<plain old documentation|perlpod> を使う)

=begin original

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.
C<module-starter> or C<h2xs> will provide a stub for you to fill in; if
you're not sure about the format, look at L<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.

=end original

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

=item Write tests

(テストを書く)

=begin original

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, C<module-starter> and C<h2xs>
provide a test framework which you can extend - you should do something
more than just checking your module will compile.
L<Test::Simple|Test::Simple> and L<Test::More|Test::More> are good
places to start when writing a test suite.

=end original

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

=item Write the README

(README を書く)

=begin original

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 F<by-module> and F<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, and the user-visible changes since the last release.

=end original

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

=back

=head2 Step-by-step: Distributing your module

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

=over 3

=item Get a CPAN user ID

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

=begin original

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

=end original

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

=item C<perl Makefile.PL; make test; make dist>

=begin original

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

=end original

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

=begin original

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

=end original

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

=item Upload the tarball

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

=begin original

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.

=end original

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

=item Announce to the modules list

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

=begin original

Once uploaded, it'll sit unnoticed in your author directory. If you want
it connected to the rest of the CPAN, you'll need to go to "Register
Namespace" on PAUSE.  Once registered, your module will appear in the
by-module and by-category listings on CPAN.

=end original

アップロードしたら、あなたのディレクトリにあるだけでは人目を引きません。
他のの CPAN モジュールと同じように載せたければ、PAUSE の
"Register Namespace" に行く必要があります。
登録されると、あなたのモジュールは CPAN のモジュール別およびカテゴリ別の
リストに表示されます。

=item Announce to clpa

(clpa にアナウンスする)

=begin original

If you have a burning desire to tell the world about your release, post
an announcement to the moderated C<comp.lang.perl.announce> newsgroup.

=end original

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

=item Fix bugs!

(バグをなおす!)

=begin original

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...

=end original

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

=back

=head1 AUTHOR

Simon Cozens, C<simon@cpan.org>

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

=head1 SEE ALSO

=begin original

L<perlmod>, L<perlmodlib>, L<perlmodinstall>, L<h2xs>, L<strict>,
L<Carp>, L<Exporter>, L<perlpod>, L<Test::Simple>, L<Test::More>
L<ExtUtils::MakeMaker>, L<Module::Build>, L<Module::Starter>
http://www.cpan.org/ , Ken Williams's tutorial on building your own
module at http://mathforum.org/~ken/perl_modules.html

=end original

L<perlmod>, L<perlmodlib>, L<perlmodinstall>, L<h2xs>, L<strict>,
L<Carp>, L<Exporter>, L<perlpod>, L<Test::Simple>, L<Test::More>
L<ExtUtils::MakeMaker>, L<Module::Build>, L<Module::Starter>
http://www.cpan.org/ , http://mathforum.org/~ken/perl_modules.html にある、
Ken Williams による自作のモジュールをビルドするためのチュートリアル。

=begin meta

Translate: miyagawa
Update: SHIRAKATA Kentaro <argrath@ub32.org> (5.10.0-)
Status: completed

=end meta
