argra****@users*****
argra****@users*****
2008年 5月 29日 (木) 04:21:18 JST
Index: docs/perl/5.10.0/perlnewmod.pod diff -u /dev/null docs/perl/5.10.0/perlnewmod.pod:1.1 --- /dev/null Thu May 29 04:21:18 2008 +++ docs/perl/5.10.0/perlnewmod.pod Thu May 29 04:21:18 2008 @@ -0,0 +1,723 @@ + +=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> は標準ライブラリで、きれいに書かれていてとても +シンプルですので、これから始めると良いでしょう; それから +looking at something a little +more complex like L<File::Copy|File::Copy>. +オブジェクト指向のコードを書こうと思っているなら、 +C<WWW::Mechanize> や C<Mail::*> モジュールがよい例となります。 +(TBT) + +=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<modul****@perl*****>. 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<modul****@perl*****> のモジュールメーリングリストに +聞いてみましょう。 +このメーリングリストはクローズドで、待ち時間が長いことに +気を付けてください。 +レスポンスが返ってくるまでには、しばらく待つ必要があるかもしれません。 + +=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 + +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: +(TBT) + + module-starter --module=Foo::Bar \ + --author="Your Name" --email=yourn****@cpan***** + +=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 + +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. +(TBT) + +=begin original + +A typical invocation of L<h2xs|h2xs> for a pure Perl module is: + +=end original + +A typical invocation of L<h2xs|h2xs> for a pure Perl module is: +(TBT) + + 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> omits the Exporter code, C<--use-new-tests> sets up a +modern testing environment, and +C<-n> でモジュールの名前を指定します。 +(TBT) + +=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> and L<Test::More|Test::More> are good +places to start when writing a test suite. +(TBT) + +=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 が必要です。 +Visit +C<http://pause.perl.org/>, select "Request PAUSE Account", and wait for +your request to be approved by the PAUSE administrators. + +=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 モジュールと同じように載せたければ、 +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. +(TBT) + +=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*****> + +Updated by Kirrily "Skud" Robert, C<skud****@cpan*****> + +=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' 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/ , Ken Williams' tutorial on building your own +module at http://mathforum.org/~ken/perl_modules.html +(TBT) +
