Dist-Milla-v1.0.4 > Dist::Milla::Tutorial
Dist-Milla-v1.0.4

名前

Dist::Milla::Tutorial - Milla HOW TO

See also the screencast explaining how to setup and create a new distribution with Milla.

the screencast も参照してください。 Millaを使って新しいディストリビューションを、どのようにセットアップして、作成するかを説明しています。

Setup

Install Milla and setup your profile.

Millaをインストールして、プロフィールをセットアップします。

  > cpanm Dist::Milla
  > milla setup

Setup command will ask you a simple question to make a basic profile. If you already have set up dzil before, this is common and you can skip the process.

セットアップコマンドは、基本のプロフィールを作るために、簡単な質問をします。 dzilを以前にセットアップしているなら、共通なので、このプロセスをスキップできます。

新しいディストリビューションを作る

Now it's time to make a new distribution.

さぁ、新しいディストリビューションを作りましょう。

  > milla new Dist-Name
  > cd Dist-Name

At this point, you will have a really simple Dist-Name directory that contains your module file with as minimum boilerplate as possible.

この時点では、本当に単純な、可能な限り最小限のボイラーブレーとと モジュールファイルを含んだDist-Nameディレクトリができます。

It is recommended to track your repository under git as soon as possible, even before releasing to CPAN.

CPANにリリースをする前でも、可能な限りすぐにgitでリポジトリを 追跡することをおすすめします。

  # git is already initialized and files are added for you
  > git commit -m "initial commit"

Now start writing your code, edit the docs, tests and manage CPAN dependencies with cpanfile.

コードを書き、ドキュメントを編集し、テストをし、CPANの依存関係を cpanfileで管理します。

  > $EDITOR lib/Dist/Name.pm t/dist-name.t cpanfile

You can test your code with a simple prove -l t.

簡単なprove -l tでコードをテストできます。

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 cpanm or testable with Travis CI.

最初のビルドの時のみのために、cpanmを使ってgitからインストール可能にするか、 Travis CIでテスト可能にするのと同様、READMEでgithubリポジトリをよく見せるために、 git リポジトリに保っておきたいいくつかのボイラープレートを得るために テストビルドを作ることができます。

  > milla build
  > git add Build.PL META.json README.md && git commit -m "git stuff"

最初のリリースをする

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.

自信が持てたら、CPANにshipする時です。test と relaese コマンドを使います。 それをする前に、git ディレクトリが汚れていないことを確認してください。 すべての変更が commit されます。

  > git commit -a -m "Done initial version"

Milla assumes you have a git remote setup so that you can push all your changes to. I recommend you to use either hub gem or App::ph to create a new github repository.

Milla は、すべての変更を push する git remote が設定されていることを 想定しています。新しいリポジトリを作るために、hub gemoApp::ph を使うことをおすすめします。

  # Use hub rubygem
  > hub create

  # Use App::ph
  > ph import

Now, make sure you have Changes file ready and have a new entry under {{$NEXT}}, which will be expanded to the next version of your module.

Changes ファイルがあり、{{$NEXT}}の下に新しいエントリがあることを確認します。 {{$NEXT}}は、モジュールの次のバージョンに展開されます。

  > $EDITOR Changes
  > milla test
  > milla release

And your first release is done. The release is tagged on git and all the changes atomatically made are committed to git as well.

最初のリリースが終わりました。リリースはgitにタグ付けされ、 すべての変更は自動的に git にコミットされます。

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 FAKE_RELEASE environment variable. This will run all the other release process, except the UploadToCPAN step.

もし、これがMllaとの最初のやりとりで、何かが間違っていいて、 正しくないアーカイブでCPANを汚さないことを確認したければ、 FAKE_RELEASE環境変数をつけて releaseコマンドを実行してください。 これは、UploadToCPANステップ以外、すべての他のリリースプロセスを実行します。

  > FAKE_RELEASE=1 milla release

Wait for PAUSE processing it and your module showing up on MetaCPAN in a few minutes. Congratulations!

PAUSEの処理を待ち、モジュールが MetaCPAN に数分で現れます。おめでとう!

メンテナンスリリースを行う

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.

新しい機能や、バグ、プルリクエストなどがあり、モジュールの 次のバージョンを出す準備ができました。新しいリリースをするのも、同様に簡単です。

First, make sure all your code has been committed to git and there's no dirty files in the working directory.

まず、すべてのコードがgitにコミットされており、ダーティファイルが ワーキングディレクトリにないことを確認します。

Then make sure to edit Changes file and contain entries for the next release under {{$NEXT}}. You don't need to commit the change to the Changes file, yet.

それから、Changes ファイルを確実に編集し、{{$NEXT}}の下に、 次のリリースのためのエントリを書きます。まだ、Changesファイルへの変更を コミットする必要はありません。

Now, make a release!

さぁ、リリースしましょう!

  > milla test
  > milla release

The release command will automatically bump the version for you - if you have 0.10, the next version will be 0.11 by default, but you will be prompted to confirm that version in case you need a major bump.

リリースコマンドは、自動的にバージョンを増加させます。 - 0.10であれば、 次のバージョンは デフォルトでは 0.11 です。ですが、メジャーバージョンアップを するときために、確認が促されます。

This will update Changes, META.json and bump $VERSION in your mailn module. These changes made by Milla will be automatically committed, tagged and pushed to the remote.

これにより、ChangesMETA.jsonと メインモージュールの $VERSION が増加します。 Milla が行うこれらの変更は自動的にコミットされ、タグ付けされ、 リモートにプッシュされます。

移行

This section describes how to migrate your current authoring process to Milla.

このセクションでは、現在のオーサリングプロセスをMillaに移行する方法について 書いています。

他のビルドツールによる手動での移行

モジュールの依存性を cpanfile に

First, move the prereq declaration from Makefile.PL or Build.PL to cpanfile.

最初に、Makefile.PLBuild.PLの prereq 宣言を cpanfile に移動します。

The easiest way to convert existing dependencies to cpanfile is to use the command line tool mymeta-cpanfile, which is installed with Module::CPANfile. Run the configuration with Makefile.PL for the one last time, then run the mymeta-cpanfile command:

既存の依存性を cpanfile に変換するもっとも簡単な方法は、 コマンドラインツールの mymeta-cpanfile をつかうことです。このコマンドはModule::CPANfileで インストールされます。最後に一度、Makefile.PLで設定を走らせた後、 mymeta-cpanfile コマンドを動かします:

  > perl Makefile.PL
  > mymeta-cpanfile --no-configure
  requires 'DBI', '1.000';
  
  on test => sub {
      requires 'Test::More', '0.86';
  }
  
  ...

You can redirect the output to cpanfile if you like. It is important to pass --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 cpanfile.

望むなら、出力を cpanfile にリダイレクトできます。 --no-configure オプションをここで渡すのが重要です。 そうしないと、ExUtils::MakeMakerのようなモジュールが含まれてしまします。 これはMillaのセットアップでは必要ありません。Millaはどの設定ツール(インストーラ) を使うか知っており、リリース時にMETAファイルにそれらを含めます。 ですので、cpanfile からそれらを無視することができます。

If you decide to manually construct new cpanfile, the format is mostly compatible to Module::Install's requirement DSL.

新しい cpanfile を手で作ると決めたなら、フォーマットは Module::Install の要求のDSLとほとんど互換性があります。

  # Makefile.PL
  test_requires 'Test::More', 0.90;
  requires 'Plack', '1.000';

becomes:

次のようになります:

  # cpanfile
  test_requires 'Test::More', 0.90;
  requires 'Plack', '1.000';

which is exactly the same. If you use Module::Build or ExtUtils::MakeMaker, that will be more manual process, but basically the same thing. See cpanfile for the available syntax.

まったく同じです。Module::BuildExtUtils::MakeMakerを使うなら、 より手で行うプロセスがありますが、基本的には同じです。 利用可能なシンタックスについてはcpanfileをみてください。

ボイラープレートの削除

Next, remove unnecessary boilerplate files.

次に、不要なボイラープレートファイルを削除します。

  > git rm {Makefile,Build}.PL MANIFEST MANIFEST.SKIP README .shipit

新しく ini ファイルを作り、設定を編集する

Next, create a new dist.ini with the following two lines:

次に、以下の2行で、新しくdist.iniを作ります。

  name = Dist-Name
  [@Milla]

the name = line is optional.

name = の行はオプショナルです。

If your work directory is named Dist-Name, Milla will be able to figure out that is your distribution name, so you can omit that line.

ワーキングディレクトリの名前がDist-Nameであれば、Milla はそれが、 ディストリビューションの名前であると見当を付けられます。そのため、 この行を省略できます。

Next, Edit .gitignore and add the following lines:

次に、.gitignore を編集し、次の行を加えます:

  /Dist-Name-*
  /.build
  !META.json

You're almost done, and your directory will look like:

ほとんど終わりです。ディレクトリは次のようになります:

  cpanfile
  dist.ini
  lib/Dist/Name.pm
  t/...

git add the newly created files and commit it.

新しく作られたファイルを git addして、コミットします。

新しいビルドを作成

Now you're ready to make the first build.

さぁ、最初のビルドをする準備ができました。

  > milla build

and if it was successful, you get a build in a directory called Dist-Name-v0.1.0 under your current directory. They can be later removed with milla clean command.

そして、成功したなら、カレントディレクトリの下に、Dist-Name-v0.1.0 のような名前のディレクトリができます。 後で、milla cleanコマンドで削除できます。

Also, new Build.PL, META.json and README.md are added in your working directory for git-friendliness. git add them and commit it.

また、ワーキングディレクトリに、git用の親切のために、新しくBuild.PLMETA.jsonREADME.mdが追加されます。git addして、コミットしてください。

  > git add Build.PL META.json README.md && git commit -m "git stuff"

Now you're ready to roll a new release with Milla. Before doing so, convert your Changes file format a little bit, and make sure you have a following header in the top:

Millaで新しくリリースをする準備ができました。その前に、Changesファイルフォーマットを 少し変更し、トップに次のヘッダがあることを確認します。

  {{$NEXT}}
          - Change log entry for the next version

The {{$NEXT}} is a template variable that gets replaced with the version and date string, when you make a next release. This is almost the only change you're required to make in your code base.

{{$NEXT}}は、次のリリースを行うときに、バージョンとデータ文字列で 置き換えられるテンプレートの変数です。これは、元のコードベースから必要な ほとんど唯一の変更です。

Now, run the release command:

さぁ、リリースコマンドを実行しましょう:

  > milla release

to make a new release, in the same way described above for a new Milla setup. You can set FAKE_RELEASE environment variable if this is your first conversion and want to double check what happens, before uploading to CPAN.

新しいMillaのセットアップのために、上述と同じ方法で、新しいリリースを作ります。 最初の変換で、CPANにアップする前に、何が起きるかダブルチェックしたければ、 FAKE_RELEASE環境変数をセットできます。

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.

最初のリリースでなければ、バージョン番号は自動的にMillaによって、増加されます。 ですが、実際に望んでいるバージョンかどうか確認を促されます。 もし、メジャーバージョンアップをしたければ、そのように指定できます。

作者

Tatsuhiko Miyagawa

SEE ALSO

Dist::Milla