憂鬱なムックを助ける友の会: CPAN

前編でPAUSEのアカウント登録まで終わりました。

後編はモジュールを書いてCPANにアップするまでの流れを私が嵌ったポイントを中心に書きます。

1. モジュールのスケルトンの作成の準備（必要なモジュールのインストール）

　スケルトンの作成はModule::Starter::PBPを使用します。その為に、次の３モジュールをCPANからインストールします。

　通常はスケルトンにファイルの追加ができないので、これを可能にするためにModule::Starter::Smartもインストールしています。

　ターミナル上で下記の手順を実行し、ホームディレクトリにスケルトンの雛形~/.module-starter/を生成します。

　Module::Starter::Smartを有効にするために、~/module-starter/configに下記を追記します。

2. スケルトンの作成

　下記のコマンドでスケルトンを作成します。例は先日CPANにアップしたDataStructure::LinkedListを使っています。

　実行するとカレントディレクトリにDataStructure-LinkedListディレクトリが作成され、DataStructure-LinkedListディレクトリ内にスケルトンが作成されます。

3. モジュールの実装

　スケルトンで生成されたモジュールに対して実装を加えていきます。ファイルはDataStructure::LinkedListモジュールなら ./DataStructure-LinkedList/lib/DataStructure/LinkedList.pmになります。つまり、一般にFoo::Barモジュールを作るなら、./Foo-Bar/lib/Foo/Bar.pmが実装対象のモジュールになります。

　スケルトンで生成されたモジュールには、初期状態でpodが書かれています。全体の構成と、BUGS、SUPPORT、ACKNOWLEDGEMENTS、LICENSE AND COPYRIGHTはそのまま使えますので、便利に利用して実装を進めていきます。ちなみに、名前の表記やメールアドレスなど、微調整したい場合は、これらの値も書き換えます。

　また、既にあるモジュール（例だと./DataStructure-LinkedList/）に新しくモジュールを追加したい場合はコマンドラインで下記のようにします。

　私の場合は、DataStructure::LinkedList::Cellなどの追加モジュールは自分で直接ファイル作って置きました（汗
　この場合、追加したモジュールにはpodが全く記述されていないので（当たり前か）、最初に作ったモジュールをコピペするなりして実装します。podを書いていないモジュールをアップすると、エラーレポートが送りつけられるので、気をつけましょう。面倒ですが、ユーザが直接使わないモジュール（クラス）にもpodを書いてください。

　さて、この段階で、次のようにmake & installしてみます。

　このコマンドで、作業ディレクトリ（例の場合は~/DataStructure-LinkedList/）のlib/配下のファイルがblib/配下にコピーされ、また、自環境のPerlライブラリに追加されます。注意が必要なのは、この時点でテストプログラム等を書いた場合に、そのプログラムが参照するのは自環境のPerlライブラリ、blib/配下、lib/配下の順に参照されるという事です。モジュールの実装を進めるにあたって、度々実行テストをすると思いますが、lib/配下のモジュールをアップデートしてもPerlライブラリ、blib/配下にはコピーされず、変更が反映されないので、テストプログラムの挙動に変化がないということになります。これを避けるにはlib/配下のモジュールをアップデート後、下記のようにmake cleanしてinstallし直します。（実はmake installを実行していなければ、テストプログラムはblib/配下を見に行きますので、毎回のmake installは省略可能です）。

　実装の最後に、Build.PLにモジュールが利用（依存）している他のモジュールの情報を書き足します。DataStructure::LinkedListの場合、Class::Accessor、Scalar::Util、Carpを使っていますので、下記のようにMakefile.PLのPREREQ_PM、Build.PLのrequiresに記述します。Module::Starterを使ってモジュールを作成する場合、Makefile.PLとBuild.PLを使った2通りのインストール方法がREADMEに記述されますので、どちらの方法でインストールされても良いように二つのPLファイルに依存関係を記述します。

Makefile.PLでのモジュールの依存関係の定義 Build.PLでのモジュールの依存関係の定義　依存関係のある各モジュールの自環境（＝開発環境）でのバージョンはコマンドラインにて下記のようにして調べられます。

依存関係にあるモジュールのバージョンを自環境でのバージョンを正として書いてよいのか、どのバージョンでも良い様に0とするか悩みました。しかし、結局テストして動作確認できているのは自環境だけだから、そのバージョンを明記した方が良心的だろうと判断しました。

4. デブロイ（リリース）

　モジュールの実装が終わったらCPANにアップするtar ball（tar.gzファイル）を作ってPAUSEからアップロードします。

　まず、下記のようにMANIFESTを作ります。

　これで、MANIFESTファイルが作成されます。MANIFESTにはtar ballに含める全ファイルのリストが書かれています。基本的にはカレントディレクトリ配下の全ファイルが記述されます（ただし、.svnなどの隠しファイルは記述されない）。MANIFESTをエディタで開き、余計なファイルが含まれているか、足りないファイルがないか、よく確認してください。特に、既にあるモジュールに新しくモジュールを追加する際に、module-starterを使わずに私のように直接ファイルを置いて作った場合は、そのモジュールがMANIFESTから漏れているかもしれないので要注意です。おそらく、モジュールを追加した後に一度でもmake manifestしていれば大丈夫だと思います。

　それでは、いよいよtar ballを作ります。まず、tar ballに固める内容をテストします。

　これが問題なく通れば、MANIFESTの記載内容や開発環境（カレントディレクトリ配下）以外の環境でもテストが通ることを確認できます。make disttestはアーカイブ用のディレクトリの中にMANIFESTに記載されている全ファイルをコピーしmake testしてくれるからです。
　make disttestでの結果が問題なければ、次のようにmake distしてtar ballを作ります。

　例の場合だとDataStructure-LinkedList-0.01.tar.gzが作成されます。一般にversionがxのFoo::Barモジュールをmake distするとFoo-Bar-x.tar.gzが作成されます。

　最後に、PAUSEにアクセス、ログインして、メニュー[Upload a file to CPAN]を選び、表示されるフォームから作成したtar ballを指定してアップロードします。

　これで、しばらく待つと（承認されれば）CPANに登録されて検索可能になります。アップロードから24時間ぐらいのタイミングでエラーレポートのメールがCPANから届きます（エラーがなければ届かないのかどうかは私には不明。）。

　以上です、お疲れさまでした。

X. 参考

　Module::Starterを使ってみる - 色々メモにっき
　Perlのmakeフェーズの挙動 : D-7 <altijd in beweging>

Y. 推奨

　本当はアップロードする前にGitHubかブログにリンクを貼った状態でtar ballをPrePANに公開し、PrePANの有志のテスターにモジュールのレビュー/テスト（特に名前の付け方）をしてもらうことが推奨されています。私は今回、PrePANを知ったのがtar ballをアップロードした後だったので（汗、使いませんでしたが。次のモジュールからは使います。大体３日ぐらいフィードバックを待って、特に指摘がなければそのままPAUSEからアップすればよいようです。

憂鬱なムックを助ける友の会

2014年12月12日金曜日

[Perl] [CPAN] CPAN Autherの登録手順（後編）

2014年12月6日土曜日

[Perl] [CPAN] CPAN Autherの登録手順（前編）