=encoding utf8
=head1 NAME
Dist::Milla::Tutorial - Milla HOW TO
=begin original
See also L
explaining how to setup and create a new distribution with Milla.
=end original
L も参照してください。
Millaを使って新しいディストリビューションを、どのようにセットアップして、作成するかを説明しています。
=head2 Setup
=begin original
Install Milla and setup your profile.
=end original
Millaをインストールして、プロフィールをセットアップします。
> cpanm Dist::Milla
> milla setup
=begin original
Setup command will ask you a simple question to make a basic
profile. If you already have set up C before, this is common and
you can skip the process.
=end original
セットアップコマンドは、基本のプロフィールを作るために、簡単な質問をします。
Cを以前にセットアップしているなら、共通なので、このプロセスをスキップできます。
=head2 Making a new distribution
(新しいディストリビューションを作る)
=begin original
Now it's time to make a new distribution.
=end original
さぁ、新しいディストリビューションを作りましょう。
> milla new Dist-Name
> cd Dist-Name
=begin original
At this point, you will have a really simple C directory
that contains your module file with as minimum boilerplate as
possible.
=end original
この時点では、本当に単純な、可能な限り最小限のボイラーブレーとと
モジュールファイルを含んだCディレクトリができます。
=begin original
It is recommended to track your repository under git as soon as
possible, even before releasing to CPAN.
=end original
CPANにリリースをする前でも、可能な限りすぐにgitでリポジトリを
追跡することをおすすめします。
# git is already initialized and files are added for you
> git commit -m "initial commit"
=begin original
Now start writing your code, edit the docs, tests and manage CPAN
dependencies with L.
=end original
コードを書き、ドキュメントを編集し、テストをし、CPANの依存関係を
Lで管理します。
> $EDITOR lib/Dist/Name.pm t/dist-name.t cpanfile
=begin original
You can test your code with a simple C.
=end original
簡単なCでコードをテストできます。
=begin original
For the first time build only, you can make a test build to get some
boilerplate you want to keep in the git repository so that your github
repository looks great with README, as well as installable from git
using C or testable with C.
=end original
最初のビルドの時のみのために、Cを使ってgitからインストール可能にするか、
Cでテスト可能にするのと同様、READMEでgithubリポジトリをよく見せるために、
git リポジトリに保っておきたいいくつかのボイラープレートを得るために
テストビルドを作ることができます。
> milla build
> git add Build.PL META.json README.md && git commit -m "git stuff"
=head2 Making the first release
(最初のリリースをする)
=begin original
When you get confident and it's about time to ship to CPAN, use the
test and release command. Before doing so, make sure your git
directory is not dirty i.e. all changes are committed.
=end original
自信が持てたら、CPANにshipする時です。test と relaese コマンドを使います。
それをする前に、git ディレクトリが汚れていないことを確認してください。
すべての変更が commit されます。
> git commit -a -m "Done initial version"
=begin original
Milla assumes you have a git remote setup so that you can push all
your changes to. I recommend you to use either
L or L to create a new
github repository.
=end original
Milla は、すべての変更を push する git remote が設定されていることを
想定しています。新しいリポジトリを作るために、L か L
を使うことをおすすめします。
# Use hub rubygem
> hub create
# Use App::ph
> ph import
=begin original
Now, make sure you have C file ready and have a new entry
under C, which will be expanded to the next version of your
module.
=end original
Changes ファイルがあり、Cの下に新しいエントリがあることを確認します。
Cは、モジュールの次のバージョンに展開されます。
> $EDITOR Changes
> milla test
> milla release
=begin original
And your first release is done. The release is tagged on git and all
the changes atomatically made are committed to git as well.
=end original
最初のリリースが終わりました。リリースはgitにタグ付けされ、
すべての変更は自動的に git にコミットされます。
=begin original
If this is your first conversion to Milla and want to make sure you're
not going to mess CPAN with a bad archive when something goes wrong,
you can run the releas command with C environment
variable. This will run all the other release process, except the
UploadToCPAN step.
=end original
もし、これがMllaとの最初のやりとりで、何かが間違っていいて、
正しくないアーカイブでCPANを汚さないことを確認したければ、
C環境変数をつけて releaseコマンドを実行してください。
これは、UploadToCPANステップ以外、すべての他のリリースプロセスを実行します。
> FAKE_RELEASE=1 milla release
=begin original
Wait for PAUSE processing it and your module showing up on MetaCPAN in
a few minutes. Congratulations!
=end original
PAUSEの処理を待ち、モジュールが MetaCPAN に数分で現れます。おめでとう!
=head2 Making a maintainance release
(メンテナンスリリースを行う)
=begin original
You have new features, bugs, pull requests and get ready to make a next
version of your module. Great, making a new release is equally easy.
=end original
新しい機能や、バグ、プルリクエストなどがあり、モジュールの
次のバージョンを出す準備ができました。新しいリリースをするのも、同様に簡単です。
=begin original
First, make sure all your code has been committed to git and there's
no dirty files in the working directory.
=end original
まず、すべてのコードがgitにコミットされており、ダーティファイルが
ワーキングディレクトリにないことを確認します。
=begin original
Then make sure to edit C file and contain entries for the
next release under C. You don't need to commit the change
to the C file, yet.
=end original
それから、C ファイルを確実に編集し、Cの下に、
次のリリースのためのエントリを書きます。まだ、Iファイルへの変更を
コミットする必要はありません。
=begin original
Now, make a release!
=end original
さぁ、リリースしましょう!
> milla test
> milla release
=begin original
The release command will automatically bump the version for you - if
you have C<0.10>, the next version will be C<0.11> by default, but you
will be prompted to confirm that version in case you need a major
bump.
=end original
リリースコマンドは、自動的にバージョンを増加させます。 - 0.10であれば、
次のバージョンは デフォルトでは 0.11 です。ですが、メジャーバージョンアップを
するときために、確認が促されます。
=begin original
This will update C, C and bump C in your
mailn module. These changes made by Milla will be automatically
committed, tagged and pushed to the remote.
=end original
これにより、C、Cと メインモージュールの C が増加します。
Milla が行うこれらの変更は自動的にコミットされ、タグ付けされ、
リモートにプッシュされます。
=head1 MIGRATING
(移行)
=begin original
This section describes how to migrate your current authoring process
to Milla.
=end original
このセクションでは、現在のオーサリングプロセスをMillaに移行する方法について
書いています。
=head2 Manually migrating from other build tools
(他のビルドツールによる手動での移行)
=head3 Module Dependencies to cpanfile
(モジュールの依存性を cpanfile に)
=begin original
First, move the prereq declaration from C or C
to C.
=end original
最初に、C、Cの prereq 宣言を C に移動します。
=begin original
The easiest way to convert existing dependencies to cpanfile is to use
the command line tool C, which is installed with
L. Run the configuration with C for the
one last time, then run the C command:
=end original
既存の依存性を cpanfile に変換するもっとも簡単な方法は、 コマンドラインツールの
C をつかうことです。このコマンドはLで
インストールされます。最後に一度、Makefile.PLで設定を走らせた後、
mymeta-cpanfile コマンドを動かします:
> perl Makefile.PL
> mymeta-cpanfile --no-configure
requires 'DBI', '1.000';
on test => sub {
requires 'Test::More', '0.86';
}
...
=begin original
You can redirect the output to C if you like. It is
important to pass C option here, since otherwise
modules like ExtUtils::MakeMaker will be included. It is not required
with Milla setup, since Milla knows which configuration tool
(installer) to use and include them in META files upon the
releases. You can leave that out from the C.
=end original
望むなら、出力を C にリダイレクトできます。
C オプションをここで渡すのが重要です。
そうしないと、ExUtils::MakeMakerのようなモジュールが含まれてしまします。
これはMillaのセットアップでは必要ありません。Millaはどの設定ツール(インストーラ)
を使うか知っており、リリース時にMETAファイルにそれらを含めます。
ですので、C からそれらを無視することができます。
=begin original
If you decide to manually construct new cpanfile, the format is mostly
compatible to L's requirement DSL.
=end original
新しい cpanfile を手で作ると決めたなら、フォーマットは C
の要求のDSLとほとんど互換性があります。
# Makefile.PL
test_requires 'Test::More', 0.90;
requires 'Plack', '1.000';
=begin original
becomes:
=end original
次のようになります:
# cpanfile
test_requires 'Test::More', 0.90;
requires 'Plack', '1.000';
=begin original
which is exactly the same. If you use L or
L, that will be more manual process, but
basically the same thing. See L for the available syntax.
=end original
まったく同じです。LかLを使うなら、
より手で行うプロセスがありますが、基本的には同じです。
利用可能なシンタックスについてはLをみてください。
=head3 Remove boilerplate
(ボイラープレートの削除)
=begin original
Next, remove unnecessary boilerplate files.
=end original
次に、不要なボイラープレートファイルを削除します。
> git rm {Makefile,Build}.PL MANIFEST MANIFEST.SKIP README .shipit
=head3 Create a new ini and edit configurations
(新しく ini ファイルを作り、設定を編集する)
=begin original
Next, create a new C with the following two lines:
=end original
次に、以下の2行で、新しくCを作ります。
name = Dist-Name
[@Milla]
=begin original
the C line is optional.
=end original
C の行はオプショナルです。
=begin original
If your work directory is named C, Milla will be able to
figure out that is your distribution name, so you can omit that line.
=end original
ワーキングディレクトリの名前がCであれば、Milla はそれが、
ディストリビューションの名前であると見当を付けられます。そのため、
この行を省略できます。
=begin original
Next, Edit C and add the following lines:
=end original
次に、C を編集し、次の行を加えます:
/Dist-Name-*
/.build
!META.json
=begin original
You're almost done, and your directory will look like:
=end original
ほとんど終わりです。ディレクトリは次のようになります:
cpanfile
dist.ini
lib/Dist/Name.pm
t/...
=begin original
C the newly created files and commit it.
=end original
新しく作られたファイルを Cして、コミットします。
=head3 Make a new build
(新しいビルドを作成)
=begin original
Now you're ready to make the first build.
=end original
さぁ、最初のビルドをする準備ができました。
> milla build
=begin original
and if it was successful, you get a build in a directory called
C under your current directory. They can be later
removed with C command.
=end original
そして、成功したなら、カレントディレクトリの下に、C
のような名前のディレクトリができます。
後で、Cコマンドで削除できます。
=begin original
Also, new C, C and C are added in your
working directory for git-friendliness. C them and commit it.
=end original
また、ワーキングディレクトリに、git用の親切のために、新しくC、C、
Cが追加されます。Cして、コミットしてください。
> git add Build.PL META.json README.md && git commit -m "git stuff"
=begin original
Now you're ready to roll a new release with Milla. Before doing so,
convert your C file format a little bit, and make sure you
have a following header in the top:
=end original
Millaで新しくリリースをする準備ができました。その前に、Cファイルフォーマットを
少し変更し、トップに次のヘッダがあることを確認します。
{{$NEXT}}
- Change log entry for the next version
=begin original
The C is a template variable that gets replaced with the
version and date string, when you make a next release. This is almost
the I change you're required to make in your code base.
=end original
Cは、次のリリースを行うときに、バージョンとデータ文字列で
置き換えられるテンプレートの変数です。これは、元のコードベースから必要な
ほとんどIの変更です。
=begin original
Now, run the release command:
=end original
さぁ、リリースコマンドを実行しましょう:
> milla release
=begin original
to make a new release, in the same way described above for a new Milla
setup. You can set C environment variable if this is
your first conversion and want to double check what happens, before
uploading to CPAN.
=end original
新しいMillaのセットアップのために、上述と同じ方法で、新しいリリースを作ります。
最初の変換で、CPANにアップする前に、何が起きるかダブルチェックしたければ、
C環境変数をセットできます。
=begin original
When this is not your first release, the version number gets
automatically bumped by Milla, but you will be prompted if that is
exactly the version you want, and if you want a major version up, you
can specify to do so.
=end original
最初のリリースでなければ、バージョン番号は自動的にMillaによって、増加されます。
ですが、実際に望んでいるバージョンかどうか確認を促されます。
もし、メジャーバージョンアップをしたければ、そのように指定できます。
=head1 AUTHOR
Tatsuhiko Miyagawa
=head1 SEE ALSO
L
=cut