=encoding utf8

=head1 NAME

cpanfile-faq - cpanfile FAQ

=head1 QUESTIONS

(質問)

=begin original

=head2 Does cpanfile replace Makefile.PL/Build.PL or META.yml/json?

=end original

=head2 cpanfile は Makefile.PL/Build.PL や META.yml/json を置き換えますか?

=begin original

No, it doesn't. C<cpanfile> is a simpler way to declare CPAN
dependencies, mainly for I<your application> rather than CPAN
distributions.

=end original

いいえ、C<cpanfile>は、単純にCPANの依存を宣言する方法です。
CPANディストリビューションよりもむしろ、主にI<あなたのアプリケーション>
のためのものです。

=begin original

However, while CPAN distributions do not need to B<switch> to
C<cpanfile>, you can certainly I<manage> the dependencies in
C<cpanfile>, then export them into C<META.json> files when shipping to
CPAN, using tools such as L<Dist::Milla> or L<Module::Install::CPANfile>

=end original

しかしながら、CPANディストリビューションC<cpanfile>にB<切り替える>必要が
ないとはいえ、確かに、C<cpanfile>で依存をI<管理>できます。それから、CPANに
シッピングするときに、L<Dist::Milla>やL<Module::Install::CPANfile>のような
ツールを使って、その依存をC<META.json>ファイルにエクスポートできます。

=begin original

=head2 Why do we need yet another format?

=end original

=head2 なぜ、別のフォーマットが必要なのでしょう？

=begin original

Here are some of the reasons that motivates the new L<cpanfile>
format.

=end original

新しくL<cpanfile>フォーマットを作る動機となる理由がいくつかあります。

=over 4

=item Not everything is a CPAN distribution

(すべてがCPANディストリビューションではない)

=begin original

First of all, it is annoying to write (a dummy) C<Makefile.PL> when
what you develop is not a CPAN distribution, just so that installation
like C<cpanm --installdeps .> would work.

=end original

まず最初に、CPANディストリビューションでないものを開発をするときに、
単に、C<cpanm --installdeps .> のようにが動かしたいがために、
(ダミーの)C<Makefile.PL>を書くのは面倒です。

=begin original

It gets more painful when you develop a web application that you want
to deploy on a different environment using version control system
(such as PaaS/cloud infrastructure), because it requires you to often
commit the META file or C<inc/> directory (or even worse, both) to a
repository.

=end original

(PaaS/クラウドのようなインフラで)、バージョンコントロールシステムを使って
違った環境でデプロイしたいWebアプリケーションを開発するときに、
より苦痛です。なぜなら、METAファイルかC<inc/>ディレクトリ(悪い時には、両方)を
リポジトリに頻繁にコミットしなければならないからです。

=begin original

Many web application frameworks generate a boiler-plate C<Makefile.PL>
for dependency declaration and to let you install dependencies with
C<< cpanm --installdeps . >>, but that doesn't always mean they are
meant to be installed. Things can be often much simpler if you run the
application from the checkout directory.

=end original

多くのWebアプリケーションフレームワークは、依存性の宣言のために、
サンプルのC<Makefile.PL>を生成し、C<< cpanm --installdeps . >>で、
依存をインストールさせます。ですが、常にインストールするつもりであるとは
限りません。チェックアウトしたディレクトリからアプリケーションを
走らせるなら、多くの場合、より簡単にできます。

=begin original

With L<cpanfile>, dependencies can be installed either globally or
locally using supported tools such as L<cpanm> or L<Carton>. Because
C<cpanfile> lists all the dependencies of your entire application and
will be updated over time, it makes perfect sense to commit the file
to a version control system, and push the file for a deployment.

=end original

L<cpanfile>を使えば、L<cpanm>やL<Carton>のようなL<cpanfile>をサポートしたツール
を使って、依存をグローバルにもローカルにもインストールできます。
C<cpanfile>はアプリケーション全体のすべての依存をリストしており、
時間が経てば更新されるでしょう。バージョンコントロールシステムにこのファイルをコミットする
完全な意義があります。そして、デプロイメントのためにファイルを置きます。

=item Familiar DSL syntax

(なじみやすいDSLシンタックス)

=begin original

This is a new file type, but the format and syntax isn't entirely
new. The metadata it can declare is exactly a subset of "Prereqs" in
L<CPAN Meta Spec|CPAN::Meta::Spec>.

=end original

これは新しいファイルタイプですが、フォーマットとシンタックスは完全に
新しいものではありません。宣言できるメタデータは、L<CPAN Meta Spec|CPAN::Meta::Spec>の
"Prereqs"のサブセットです。

=begin original

The syntax borrows a lot from L<Module::Install>. Module::Install is a
great way to easily declare module metadata such as name, author and
dependencies. L<cpanfile> format is simply to extract the dependencies
into a separate file, which means most of the developers are familiar
with the syntax.

=end original

シンタックスの多くはL<Module::Install>から借りています。Module::Installは
名前や著者や依存といったモジュールのメタデータを簡単に宣言する素晴らしい方法
です。L<cpanfile>フォーマットは単純に依存性を別のファイルに取り出したもの
なので、開発者の多くはそのシンタックスに馴染みがあるということになります。

=item Complete CPAN Meta Spec v2 support

(CPAN メタスペック v2 の完全なサポート)

=begin original

C<cpanfile> basically allows you to declare L<CPAN::Meta::Spec>
prerequisite specification using an easy Perl DSL syntax. This makes
it easy to declare per-phase dependencies and newer version 2 features
such as conflicts and version ranges.

=end original

C<cpanfile>は、基本的に、簡単なPerlのDSLシンタックスを使って、
L<CPAN::Meta::Spec>の必要条件を宣言できます。これにより、
フェーズごとの依存、コンフリクト、バージョンの範囲のような、
新しいバージョン2の機能を簡単に宣言できます。

=back

=begin original

=head2 How can I start using C<cpanfile>?

=end original

=head2 どのようにC<cpanfile>を使い始めますか?

=begin original

First of all, most distributions on CPAN are not required to update to
this format.

=end original

まず最初に、CPANにある多くのディストリビューションはこのフォーマットに
アップデートする必要はありません。

=begin original

If your application currently uses C<Makefile.PL> etc. for dependency
declaration because of the current toolchain implementation (e.g. C<<
cpanm --installdeps . >>), you can upgrade to C<cpanfile> while
keeping the build file based installation working for the backward
compatibility.

=end original

現在、あなたのアプリケーションが、現在のツールチェインの実装
(e.g. C<<cpanm --installdeps . >>)のために、C<Makefile.PL>などを、
依存の宣言に使っているなら、後方互換性のために動くインストレーションに基づいた
ビルドファイルを持ち続けることで、C<cpanfile>にアップグレードできます。

=begin original

If you are an author of CPAN module and want to manage CPAN module
prerequisites using C<cpanfile> you can use one of the following
tools:

=end original

CPANモジュールの作者で、CPANモジュールの必要条件をC<cpanfile>を使って
管理したければ、以下のツールの一つを使うことができます。

=over 4

=item Dist::Milla

=begin original

L<Dist::Milla> is a profile for L<Dist::Zilla> that has a C<cpanfile>
support to declare dependencies for your module.

=end original

L<Dist::Milla> は、L<Dist::Zilla> のプロファイルです。
モジュールの依存の宣言のために、C<cpanfile>をサポートしています。

=item Dist::Zilla

=begin original

L<Dist::Zilla::Plugin::Prereqs::FromCPANfile> provides a way to merge
dependencies declared in C<cpanfile> into META files as well as build
files. You can combine them using other prerequisite scanners like
C<AutoPrereqs>.

=end original

L<Dist::Zilla::Plugin::Prereqs::FromCPANfile>は、C<cpanfile>に宣言された
依存をMETAファイルに加えけてビルドファイルにも、マージする方法を提供します。
C<AutoPrereqs>のような他の必要条件スキャナーを使って、それらを一体化できます。

=item Minilla

=begin original

L<Minilla> is a yet another authoring tool that supports C<cpanfile>
as a way to describe dependencies for your CPAN module.

=end original

L<Minilla>は、また別のオーサリングツールであり、
CPANモジュールの依存を宣言するための方法としてC<cpanfile>をサポートします。

=item Module::Install

=begin original

L<Module::Install::CPANfile> provides a C<cpanfile> DSL that reads
C<cpanfile> to merge prerequisites when dumping C<MYMETA> files upon
installation.

=end original

L<Module::Install::CPANfile>は、C<cpanfile>DSLを読み、
インストール時にC<MYMETA>ファイルをダンプするときに、
C<cpanfile> を必要条件にマージします。

=item Module::Build

=begin original

L<Module::Build::Pluggable::CPANfile> merges C<cpanfile> dependencies
from C<Build.PL> when dumping out MYMETA information.

=end original

L<Module::Build::Pluggable::CPANfile> は C<Build.PL>から、MYMETAの情報を
ダンプするときに、C<cpanfile> の依存をマージします。

=item ExtUtils::MakeMaker

=begin original

L<ExtUtils::MakeMaker> has no direct support for cpanfile yet, but you
could use L<Module::CPANfile>'s C<merge_meta> method to update
C<MYMETA.json> files with the contents in C<cpanfile>, or convert the
structure to appropriate options with L<PREREQ_PM> and C<META_MERGE>
for C<WriteMakefile>.

=end original

L<ExtUtils::MakeMaker> は、cpanfileを直接にはサポートしません。ですが、
L<Module::CPANfile> の C<merge_meta> を使って、
C<MYMETA.json> ファイルを、C<cpanfile>の内容で更新するか、
C<WriteMakefile>にL<PREREQ_PM>とC<META_MERGE>のオプションを使って、
構造を変換できます。

=back