=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<{{$NEXT}}>, which will be expanded to the next version of your module. =end original Changes ファイルがあり、C<{{$NEXT}}>の下に新しいエントリがあることを確認します。 C<{{$NEXT}}>は、モジュールの次のバージョンに展開されます。 > $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<{{$NEXT}}>. You don't need to commit the change to the C file, yet. =end original それから、C ファイルを確実に編集し、C<{{$NEXT}}>の下に、 次のリリースのためのエントリを書きます。まだ、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<$VERSION> in your mailn module. These changes made by Milla will be automatically committed, tagged and pushed to the remote. =end original これにより、C、Cと メインモージュールの C<$VERSION> が増加します。 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<--no-configure> 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<--no-configure> オプションをここで渡すのが重要です。 そうしないと、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<.gitignore> and add the following lines: =end original 次に、C<.gitignore> を編集し、次の行を加えます: /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<{{$NEXT}}> 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<{{$NEXT}}>は、次のリリースを行うときに、バージョンとデータ文字列で 置き換えられるテンプレートの変数です。これは、元のコードベースから必要な ほとんど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