Module::Setup でらくらくモジュール作成B!

こんにちわ!こんにちわ!acotie hackathon の懇談会来てるのに一人寂しくビール飲んでる Yappo です。

皆様お元気ですか?僕は寂しいです。

さて今日は今さっき shipit したての Module::Setup について紹介しましょう。

what is Module::Setup?

Module:Setup とは miyagawa さん作の pmsetup を CPANize した物です。

で、 pmsetup は何かというと Module::Starter などのモジュール開発を始める上の雛形を便利な感じで作ってくれる物です。

まぁ pmsetup でも良かったんですが、みんな好き勝手にオレオレ pmsetup を作り出してて無駄かなと思ったので CPANize したのでした。

how to use Module::Setup

さぁ Module::Setup を使ってみましょう。使うには Module::Setup をインストールしといてください。

最新版は 0.07 です。必要におうじて cpanf で入れてください。

インストールすると module-setup というコマンドが適当な bin の中にインストールされるので、これを使って操作を行います。

インストールしてすぐにつかえるというワケではなくて、最初に初期化を行わないとなりません。

初期化には module-setup コマンドに --init というオプションを与えます。

]$ module-setup --init
Creating directory /Users/username/.module-setup
(略)
Creating directory /Users/username/.module-setup/flavors/default/template
Do you use SVN? [yN] [n] 
Do you use SVK? [yN] [n] 
Do you use Git? [yN] [n] y
You chose version control system: Git
Your name:  [Default Name] 名前を入力
Your email:  [default {at} example.com] メールアドレスを入力
Dump config /Users/username/.module-setup/flavors/default/config.yaml

だいたいこんな感じです。

途中で "Do you use " と聞いてる部分では、あなたが使いたい VCS のところで y を入れてください。

Your name と Your email は、作成する Module やら README やらで使われるので正しく入れておきましょう。

作成ログを見れば分かりますが ~/.module-setup に Module::Setup 用のファイル構造が作成されます。

Module::Setup では flavor という単位で作成するモジュールの雛形を複数保存しておくことができます。

今回は Default flavor を使いましたが、例えば XS の為を flavor を作りたい場合には、 Flavor のモジュール名と flavor 名をコマンドラインに与えます。

]$ module-setup --init --flavor-class=XS xs
Creating /Users/username/.module-setup/flavors/xs/template/Makefile.PL
(略)
Your name:  [Default Name] 名前を入力
Your email:  [default {at} example.com] メールアドレスを入力
Dump config /Users/username/.module-setup/flavors/xs/config.yaml

--flavor-class というオプションで flavor class を指定して最後の引数で作成する flavor の名前を指定します。

作成する flavor の名前はあなたの好きな物を選べますが、 flavor class は Module::Setup::Flavor::* の中のものを指定します。

今のところ以下の flavor class が標準で入っています。

$ ls lib/Module/Setup/Flavor
CatalystStarter.pm      Default.pm              PBP.pm                  XS.pm
CodeRepos.pm            GitHub.pm               SelectVC.pm

もし、あなたの名前空間で flavor class を作っていたら --flavor-class=+YourModule::FlavorName とかいう感じで指定できます。

雛形を作る

初期化がすんだら雛形を作りだす事ができます。

$ module-setup モジュール名

という感じで module-setup コマンドを叩くと、モジュール名の雛形がカレントディレクトリに作成されます。

$ module-setup My::Module
[1]: default
[2]: xs
Select flavor: [1] 

ここまでのステップを踏むと default と xs という flavor が install されていますので、ここでどの flavor を使うかの選択肢がでます。

ここでは 1 の default を選びましょう。

Select flavor: [1] 1
You chose flavor: default
Creating directory My-Module
Creating My-Module/.shipit
Creating My-Module/Changes
Creating My-Module/Makefile.PL
Creating My-Module/MANIFEST.SKIP
Creating My-Module/README
Creating My-Module/lib/My/Module.pm
Creating My-Module/t/00_compile.t
Creating My-Module/xt/01_podspell.t
Creating My-Module/xt/02_perlcritic.t
Creating My-Module/xt/03_pod.t
Creating My-Module/xt/perlcriticrc
Creating My-Module/.gitignore
Check Makefile.PL? [Yn]  [y] 

こんどは、 Makefile.PL を使って make test をして正しく雛形が出来ているかを聞かれています。

まよわず y だ

Check Makefile.PL? [Yn]  [y] y
(略
Git init? [Yn]  [y] 

make test が無事実行できたら git init を実行して git repository を作るかを聞いています。

なぜ git かというと、最初の module-setup --init の例で git を選んでいたのです。

せっかく git をえらんだので y です

Git init? [Yn]  [y] y
Initialized empty Git repository in /Users/username/p5-Module-Setup/My-Module/.git/
The following paths are ignored by one of your .gitignore files:
MANIFEST
Use -f if you really want to add them.
fatal: no files added
Created initial commit 277e984: initial commit
 12 files changed, 137 insertions(+), 0 deletions(-)
 create mode 100644 .gitignore
 create mode 100644 .shipit
 create mode 100644 Changes
 create mode 100644 MANIFEST.SKIP
 create mode 100644 Makefile.PL
 create mode 100644 README
 create mode 100644 lib/My/Module.pm
 create mode 100644 t/00_compile.t
 create mode 100644 xt/01_podspell.t
 create mode 100644 xt/02_perlcritic.t
 create mode 100644 xt/03_pod.t
 create mode 100644 xt/perlcriticrc
$

無事プロジェクトが出来ました。

$ ls My-Module/
Changes         MANIFEST        MANIFEST.SKIP   Makefile.PL     README          lib             t               xt

Module::Setup では、基本的にモダンでかつ実用的な雛形を標準で用意しているので、 module-setup --init をしたあとは気軽にモジュール作成を行うことができます。

もし標準の雛形が気に入らなければ ~/.module-setup/flavors/default/template/ 以下がひな形のファイル構造が入っているので、これ以下のファイルを編集することによってお気に入りの雛形にすることができます。

もちろん改造した雛形は --pack オプションによっていつでも flavor class にすることができます。

$ module-setup --pack MyFlavor default

package MyFlavor;
use strict;
use warnings;
use base 'Module::Setup::Flavor';
1;

=head1

MyFlavor - pack from default

また、こうして flavor class を開発するための便利オプションなども充実しているのですが紙面が足りなさすぎるので perldoc Module::Setup とか、それ以下のモジュールのドキュメントを詳しくよんでね!

0.07 の新要素

ながらく 0.06_01 だったのですが、先程 0.07 を shipit しました。

一番大きい要素を紹介します。

add Helper support

いわゆる Catalyst::Helper を作るのに便利な Helper サポートを追加しました。

Module::Setup::Helper になってます。

これはさらに hacker 向けではあると思うので、ここでは説明しませんが Ark の setup script などに使うと良いでしょう。

XS flavor

XS なモジュールを書くための便利な flavor が追加されています。

おそらく id:gfx がいい感じにモダンな雛形にしてくれるとおもいます!

GitHub flavor

GitHub ユーザ向けの flavor が追加されています。

$ module-setup --init --flavor-class=GitHub
(略
use readme_pod_from? (depend Module::Install::ReadmePodFromPod, installed 0.01 [Yn]  [y] 
use githubmeta? (depend Module::Install::GithubMeta, installed 0.10 [Yn]  [y] 
use readme_markdown_from? (depend Module::Install::ReadmeMarkdownFromPod, not installed [Yn]  [y] n
use readme_from? (depend Module::Install::ReadmeFromPod, installed 0.06 [Yn]  [y] 
github repository name format:  [p5-%s] 
Dump config /Users/ko/.module-setup/flavors/github/config.yaml

という感じで setup します。

途中で聞いているのは perl ./Makefile.PL をした時に、メインのパッケージから README ファイルを作るかどうか聞いています。

3種類ありますが、普通の README か pod 形式化 markdown 形式かというのが選べます。

全部 CPAN から手に入ります。

もう一つ GithubMeta を使うかどうかも聞いています。

これは META.yml のデータの元を GitHub のメタデータから作れる物です。

最後の github repository name format は、雛形作成時に GitHub のリポジトリを作るときのリポジトリ名のフォーマットを決めます。

作ったモジュールの名前が %s に置換されます。

実際に使う時は以下のようになります。

$ module-setup My::GitHub
[1]: default
[2]: github
[3]: xs
Select flavor: [1] 2
You chose flavor: github
Creating directory My-GitHub
Creating My-GitHub/.shipit
(略
create GitHub repository? [Yn]  [y]
github repository name:  [p5-My-GitHub]
github repository description:  [Perl Module of My::GitHub]
github repository homepage:  []
create private repository? [yN]  [n]
include /Users/username/p5-Module-Setup/My-GitHub/inc/Module/Install.pm
(略
 create mode 100644 xt/03_pod.t
 create mode 100644 xt/perlcriticrc
try git push to GitHub? [Yn]  [y]
Enter passphrase for key '/Users/username/.ssh/id_dsa': 
Counting objects: 19, done.
Compressing objects: 100% (16/16), done.
Writing objects: 100% (19/19), 2.47 KiB, done.
Total 19 (delta 1), reused 0 (delta 0)
To git@github.com:yappo/p5-My-GitHub.git
 * [new branch]      master -> master

という感じで、実際に GitHub 上にリポジトリを作って、作りたてのリポジトリに雛形を push できます。

さすがに作りたての物を push するなんて誰得すぎるけどついでに作っといた反省しない。

その他

本当に Module::Setup はできることが多すぎて紹介しきれないんですが、例えば Helper suppoert を使わなくとも Module::Setup をあなたのモジュールに組み込むこともできる、組み込まれることを想定して作りこんであるので hack しがいがあると思います。

大抵のことはドキュメントに書いてあるつもりですし、もし不明点があれば僕を捕まえて聞いてみてください。

おわりに

ということで shipit したての Module::Setup のご紹介でした。

あしたは Module::Setup 0.07 の shipit 作業を物理的に行なってくれた xaicron さんです。

なんか、この文章書いてたら懇談会のおわりのじかんっぽいんですけど、この補填は kan さんのお寿司であてたいとおもいます。