=encoding utf8
=for comment
Consistent formatting of this file is achieved with:
perl ./Porting/podtidy pod/perlhack.pod
=head1 NAME
=begin original
perlhack - How to hack on Perl
=end original
perlhack - Perl をハックする方法
=head1 DESCRIPTION
=begin original
This document explains how Perl development works. It includes details
about the Perl 5 Porters email list, the Perl repository, the Perlbug
bug tracker, patch guidelines, and commentary on Perl development
philosophy.
=end original
This document explains how Perl development works. It includes details
about the Perl 5 Porters email list, the Perl repository, the Perlbug
bug tracker, patch guidelines, and commentary on Perl development
philosophy.
(TBT)
=head1 SUPER QUICK PATCH GUIDE
=begin original
If you just want to submit a single small patch like a pod fix, a test
for a bug, comment fixes, etc., it's easy! Here's how:
=end original
If you just want to submit a single small patch like a pod fix, a test
for a bug, comment fixes, etc., it's easy! Here's how:
(TBT)
=over 4
=item * Check out the source repository
=begin original
The perl source is in a git repository. You can clone the repository
with the following command:
=end original
The perl source is in a git repository. You can clone the repository
with the following command:
(TBT)
% git clone git://perl5.git.perl.org/perl.git perl
=item * Make your change
=begin original
Hack, hack, hack.
=end original
Hack, hack, hack.
(TBT)
=item * Test your change
=begin original
You can run all the tests with the following commands:
=end original
You can run all the tests with the following commands:
(TBT)
% ./Configure -des -Dusedevel
% make test
=begin original
Keep hacking until the tests pass.
=end original
Keep hacking until the tests pass.
(TBT)
=item * Commit your change
=begin original
Committing your work will save the change I<on your local system>:
=end original
Committing your work will save the change I<on your local system>:
(TBT)
% git commit -a -m 'Commit message goes here'
=begin original
Make sure the commit message describes your change in a single
sentence. For example, "Fixed spelling errors in perlhack.pod".
=end original
Make sure the commit message describes your change in a single
sentence. For example, "Fixed spelling errors in perlhack.pod".
(TBT)
=item * Send your change to perlbug
=begin original
The next step is to submit your patch to the Perl core ticket system
via email.
=end original
The next step is to submit your patch to the Perl core ticket system
via email.
(TBT)
=begin original
Assuming your patch consists of a single git commit, you can send it to
perlbug with this command line:
=end original
Assuming your patch consists of a single git commit, you can send it to
perlbug with this command line:
(TBT)
% git format-patch HEAD^1..HEAD
% perlbug -s '[PATCH] `git log --pretty=format:%s HEAD^1..HEAD`' -f 0001-*.patch
=begin original
The perlbug program will ask you a few questions about your email
address and the patch you're submitting. Once you've answered them you
can submit your patch.
=end original
The perlbug program will ask you a few questions about your email
address and the patch you're submitting. Once you've answered them you
can submit your patch.
(TBT)
=item * Thank you
=begin original
The porters appreciate the time you spent helping to make Perl better.
Thank you!
=end original
The porters appreciate the time you spent helping to make Perl better.
Thank you!
(TBT)
=back
=head1 BUG REPORTING
=begin original
If you want to report a bug in Perl, you must use the F<perlbug> command
line tool. This tool will ensure that your bug report includes all the
relevant system and configuration information.
=end original
If you want to report a bug in Perl, you must use the F<perlbug> command
line tool. This tool will ensure that your bug report includes all the
relevant system and configuration information.
(TBT)
=begin original
To browse existing Perl bugs and patches, you can use the web interface
at L<http://rt.perl.org/>.
=end original
To browse existing Perl bugs and patches, you can use the web interface
at L<http://rt.perl.org/>.
(TBT)
=begin original
Please check the archive of the perl5-porters list (see below) and/or
the bug tracking system before submitting a bug report. Often, you'll
find that the bug has been reported already.
=end original
Please check the archive of the perl5-porters list (see below) and/or
the bug tracking system before submitting a bug report. Often, you'll
find that the bug has been reported already.
(TBT)
=begin original
You can log in to the bug tracking system and comment on existing bug
reports. If you have additional information regarding an existing bug,
please add it. This will help the porters fix the bug.
=end original
You can log in to the bug tracking system and comment on existing bug
reports. If you have additional information regarding an existing bug,
please add it. This will help the porters fix the bug.
(TBT)
=head1 PERL 5 PORTERS
=begin original
The perl5-porters (p5p) mailing list is where the Perl standard
distribution is maintained and developed. The people who maintain Perl
are also referred to as the "Perl 5 Porters", or just the "porters".
=end original
The perl5-porters (p5p) mailing list is where the Perl standard
distribution is maintained and developed. The people who maintain Perl
are also referred to as the "Perl 5 Porters", or just the "porters".
(TBT)
=begin original
A searchable archive of the list is available at
L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>. There is
also another archive at
L<http://archive.develooper.com/perl5-porters@perl.org/>.
=end original
A searchable archive of the list is available at
L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>. There is
also another archive at
L<http://archive.develooper.com/perl5-porters@perl.org/>.
(TBT)
=head2 perl-changes mailing list
=begin original
The perl5-changes mailing list receives a copy of each patch that gets
submitted to the maintenance and development branches of the perl
repository. See L<http://lists.perl.org/list/perl5-changes.html> for
subscription and archive information.
=end original
The perl5-changes mailing list receives a copy of each patch that gets
submitted to the maintenance and development branches of the perl
repository. See L<http://lists.perl.org/list/perl5-changes.html> for
subscription and archive information.
(TBT)
=head1 GETTING THE PERL SOURCE
=begin original
All of Perl's source code is kept centrally in a Git repository at
I<perl5.git.perl.org>. The repository contains many Perl revisions from
Perl 1 onwards and all the revisions from Perforce, the previous
version control system.
=end original
Perlのソースコードはすべて、I<perl5.git.perl.org> の Git リポジトリに
集中管理されています。
このリポジトリには、Perl 1 以降の多くの Perl リビジョンと、
以前使用していたバージョン管理システムである Perforce のすべての
リビジョンが含まれています。
=begin original
For much more detail on using git with the Perl repository, please see
L<perlgit>.
=end original
For much more detail on using git with the Perl repository, please see
L<perlgit>.
(TBT)
=head2 Read access via Git
(Git 経由の読み込みアクセス)
=begin original
You will need a copy of Git for your computer. You can fetch a copy of
the repository using the git protocol:
=end original
あなたのコンピュータ用の Git が必要です。
git プロトコルを使用して、リポジトリのコピーを
フェッチできます。
% git clone git://perl5.git.perl.org/perl.git perl
=begin original
This clones the repository and makes a local copy in the F<perl>
directory.
=end original
これにより、リポジトリが複製され、F<perl> ディレクトリに
ローカルコピーが作成されます。
=begin original
If you cannot use the git protocol for firewall reasons, you can also
clone via http, though this is much slower:
=end original
ファイアウォールの関係で git プロトコルが使えない場合、
http 経由でもクローンできますが、はるかに遅いです:
% git clone http://perl5.git.perl.org/perl.git perl
=head2 Read access via the web
(Web 経由の読み込みアクセス)
=begin original
You may access the repository over the web. This allows you to browse
the tree, see recent commits, subscribe to RSS feeds for the changes,
search for particular commits and more. You may access it at
L<http://perl5.git.perl.org/perl.git>. A mirror of the repository is
found at L<http://github.com/mirrors/perl>.
=end original
Web 経由でリポジトリにアクセスできます。
これにより、ツリーの参照、最近のコミットの表示、変更の RSS フィードの購読、
特定のコミットの検索などが可能になります。
次の場所からアクセスできます:
L<http://perl5.git.perl.org/perl.git>.
リポジトリのミラーは以下にあります
found at L<http://github.com/mirrors/perl>.
=head2 Read access via rsync
=begin original
You can also choose to use rsync to get a copy of the current source
tree for the bleadperl branch and all maintenance branches:
=end original
You can also choose to use rsync to get a copy of the current source
tree for the bleadperl branch and all maintenance branches:
(TBT)
% rsync -avz rsync://perl5.git.perl.org/perl-current .
% rsync -avz rsync://perl5.git.perl.org/perl-5.12.x .
% rsync -avz rsync://perl5.git.perl.org/perl-5.10.x .
% rsync -avz rsync://perl5.git.perl.org/perl-5.8.x .
% rsync -avz rsync://perl5.git.perl.org/perl-5.6.x .
% rsync -avz rsync://perl5.git.perl.org/perl-5.005xx .
=begin original
(Add the C<--delete> option to remove leftover files.)
=end original
(Add the C<--delete> option to remove leftover files.)
(TBT)
=begin original
To get a full list of the available sync points:
=end original
To get a full list of the available sync points:
(TBT)
% rsync perl5.git.perl.org::
=head2 Write access via git
=begin original
If you have a commit bit, please see L<perlgit> for more details on
using git.
=end original
If you have a commit bit, please see L<perlgit> for more details on
using git.
(TBT)
=head1 PATCHING PERL
=begin original
If you're planning to do more extensive work than a single small fix,
we encourage you to read the documentation below. This will help you
focus your work and make your patches easier to incorporate into the
Perl source.
=end original
If you're planning to do more extensive work than a single small fix,
we encourage you to read the documentation below. This will help you
focus your work and make your patches easier to incorporate into the
Perl source.
(TBT)
=head2 Submitting patches
=begin original
If you have a small patch to submit, please submit it via perlbug. You
can also send email directly to perlbug@perl.org. Please note that
messages sent to perlbug may be held in a moderation queue, so you
won't receive a response immediately.
=end original
If you have a small patch to submit, please submit it via perlbug. You
can also send email directly to perlbug@perl.org. Please note that
messages sent to perlbug may be held in a moderation queue, so you
won't receive a response immediately.
(TBT)
=begin original
You'll know your submission has been processed when you receive an
email from our ticket tracking system. This email will give you a
ticket number. Once your patch has made it to the ticket tracking
system, it will also be sent to the perl5-porters@perl.org list.
=end original
You'll know your submission has been processed when you receive an
email from our ticket tracking system. This email will give you a
ticket number. Once your patch has made it to the ticket tracking
system, it will also be sent to the perl5-porters@perl.org list.
(TBT)
=begin original
Patches are reviewed and discussed on the p5p list. Simple,
uncontroversial patches will usually be applied without any discussion.
When the patch is applied, the ticket will be updated and you will
receive email. In addition, an email will be sent to the p5p list.
=end original
Patches are reviewed and discussed on the p5p list. Simple,
uncontroversial patches will usually be applied without any discussion.
When the patch is applied, the ticket will be updated and you will
receive email. In addition, an email will be sent to the p5p list.
(TBT)
=begin original
In other cases, the patch will need more work or discussion. That will
happen on the p5p list.
=end original
In other cases, the patch will need more work or discussion. That will
happen on the p5p list.
(TBT)
=begin original
You are encouraged to participate in the discussion and advocate for
your patch. Sometimes your patch may get lost in the shuffle. It's
appropriate to send a reminder email to p5p if no action has been taken
in a month. Please remember that the Perl 5 developers are all
volunteers, and be polite.
=end original
You are encouraged to participate in the discussion and advocate for
your patch. Sometimes your patch may get lost in the shuffle. It's
appropriate to send a reminder email to p5p if no action has been taken
in a month. Please remember that the Perl 5 developers are all
volunteers, and be polite.
(TBT)
=begin original
Changes are always applied directly to the main development branch,
called "blead". Some patches may be backported to a maintenance branch.
If you think your patch is appropriate for the maintenance branch,
please explain why when you submit it.
=end original
Changes are always applied directly to the main development branch,
called "blead". Some patches may be backported to a maintenance branch.
If you think your patch is appropriate for the maintenance branch,
please explain why when you submit it.
(TBT)
=head2 Getting your patch accepted
(あなたのパッチを受け入れてもらうために)
=begin original
If you are submitting a code patch there are several things that you
can do to help the Perl 5 Porters accept your patch.
=end original
コードパッチを送信する場合は、Perl 5 Porters があなたのパッチを
受け入れるのを助けるためにできることがいくつかあります。
=head3 Patch style
=begin original
If you used git to check out the Perl source, then using C<git
format-patch> will produce a patch in a style suitable for Perl. The
C<format-patch> command produces one patch file for each commit you
made. If you prefer to send a single patch for all commits, you can use
C<git diff>.
=end original
If you used git to check out the Perl source, then using C<git
format-patch> will produce a patch in a style suitable for Perl. The
C<format-patch> command produces one patch file for each commit you
made. If you prefer to send a single patch for all commits, you can use
C<git diff>.
(TBT)
% git co blead
% git pull
% git diff blead my-branch-name
=begin original
This produces a patch based on the difference between blead and your
current branch. It's important to make sure that blead is up to date
before producing the diff, that's why we call C<git pull> first.
=end original
This produces a patch based on the difference between blead and your
current branch. It's important to make sure that blead is up to date
before producing the diff, that's why we call C<git pull> first.
(TBT)
=begin original
We strongly recommend that you use git if possible. It will make your
life easier, and ours as well.
=end original
We strongly recommend that you use git if possible. It will make your
life easier, and ours as well.
(TBT)
=begin original
However, if you're not using git, you can still produce a suitable
patch. You'll need a pristine copy of the Perl source to diff against.
The porters prefer unified diffs. Using GNU C<diff>, you can produce a
diff like this:
=end original
However, if you're not using git, you can still produce a suitable
patch. You'll need a pristine copy of the Perl source to diff against.
The porters prefer unified diffs. Using GNU C<diff>, you can produce a
diff like this:
(TBT)
% diff -Npurd perl.pristine perl.mine
=begin original
Make sure that you C<make realclean> in your copy of Perl to remove any
build artifacts, or you may get a confusing result.
=end original
Make sure that you C<make realclean> in your copy of Perl to remove any
build artifacts, or you may get a confusing result.
(TBT)
=head3 Commit message
=begin original
As you craft each patch you intend to submit to the Perl core, it's
important to write a good commit message. This is especially important
if your submission will consist of a series of commits.
=end original
Perl コアに投稿しようとするパッチを作成する際には、
適切なコミットメッセージを作成することが重要です。
This is especially important
if your submission will consist of a series of commits.
(TBT)
=begin original
The first line of the commit message should be a short description
without a period. It should be no longer than the subject line of an
email, 50 characters being a good rule of thumb.
=end original
The first line of the commit message should be a short description
without a period. It should be no longer than the subject line of an
email, 50 characters being a good rule of thumb.
(TBT)
=begin original
A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ...) will
only display the first line (cut off at 50 characters) when presenting
commit summaries.
=end original
A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ...) will
only display the first line (cut off at 50 characters) when presenting
commit summaries.
(TBT)
=begin original
The commit message should include a description of the problem that the
patch corrects or new functionality that the patch adds.
=end original
コミットメッセージは、パッチによって修正される問題の説明、または
パッチによって追加される新機能の説明を含む必要があります。
=begin original
As a general rule of thumb, your commit message should help a
programmer who knows the Perl core quickly understand what you were
trying to do, how you were trying to do it, and why the change matters
to Perl.
=end original
一般的な経験則として、コミットメッセージによって、Perl コアを
知っているプログラマーは、何をしようとしているのか、
どのようにしようとしているのか、そしてなぜ変更が Perl にとって
重要なのかをすぐに理解する助けになるはずです。
=over 4
=item * Why
=begin original
Your commit message should describe why the change you are making is
important. When someone looks at your change in six months or six
years, your intent should be clear.
=end original
コミットメッセージに、
自分が行っている変更がなぜ重要なのかを記述すべきだということです。
6 ヶ月や6 年後に誰かがあなたの変更を見たとき、
あなたの意図は明確であるべきです。
=begin original
If you're deprecating a feature with the intent of later simplifying
another bit of code, say so. If you're fixing a performance problem or
adding a new feature to support some other bit of the core, mention
that.
=end original
後で別のコードを単純化するために機能を非推奨にしているのであれば、
そう書いてください。
パフォーマンスの問題を修正したり、コアの他の部分をサポートするための
新機能を追加しているのであれば、そのことに言及してください。
=item * What
=begin original
Your commit message should describe what part of the Perl core you're
changing and what you expect your patch to do.
=end original
コミットメッセージには、Perlコアのどの部分を変更しようとしているのか、
パッチに何を期待しているのかを記述する必要があります。
=item * How
=begin original
While it's not necessary for documentation changes, new tests or
trivial patches, it's often worth explaining how your change works.
Even if it's clear to you today, it may not be clear to a porter next
month or next year.
=end original
文書の変更、新しいテスト、簡単なパッチなどでは必要ありませんが、
変更がどのように機能するかを説明する価値があることがよくあります。
今日ははっきりしていても、来月や来年にははっきりしないかもしれません。
=back
=begin original
A commit message isn't intended to take the place of comments in your
code. Commit messages should describe the change you made, while code
comments should describe the current state of the code.
=end original
コミットメッセージは、コード内のコメントに代わるものではありません。
コミットメッセージには変更内容が記述され、コードコメントにはコードの
現在の状態が記述されます。
=begin original
If you've just implemented a new feature, complete with doc, tests and
well-commented code, a brief commit message will often suffice. If,
however, you've just changed a single character deep in the parser or
lexer, you might need to write a small novel to ensure that future
readers understand what you did and why you did it.
=end original
新機能を実装したばかりで、文書、テスト、コメント付きのコードが
揃っている場合は、簡単なコミットメッセージで十分なことがよくあります。
ただし、パーサや字句解析器の奥深くにある 1 文字を変更しただけの場合は、
将来の読者が自分のしたこととその理由を確実に理解できるように、
短い小説を書く必要があるかもしれません。
=head3 Comments, Comments, Comments
(コメント、コメント、コメント)
=begin original
Be sure to adequately comment your code. While commenting every line is
unnecessary, anything that takes advantage of side effects of
operators, that creates changes that will be felt outside of the
function being patched, or that others may find confusing should be
documented. If you are going to err, it is better to err on the side of
adding too many comments than too few.
=end original
コードに適切なコメントを付けるようにしてください。
すべての行にコメントを付ける必要はありませんが、演算子の副作用を利用するもの、
パッチされている関数の外部で感じられる変更を生成するもの、
または他の人が混乱を感じる可能性のあるものはすべて
文書化する必要があります。
過ちを起こす場合は、コメントの数が少なすぎる過ちよりも、
コメントの数が多すぎる過ちの方がましです。
=begin original
The best comments explain I<why> the code does what it does, not I<what
it does>.
=end original
The best comments explain I<why> the code does what it does, not I<what
it does>.
(TBT)
=head3 Style
(スタイル)
=begin original
In general, please follow the particular style of the code you are
patching.
=end original
一般に、パッチを適用するコードは特定のスタイルに従ってください。
=begin original
In particular, follow these general guidelines for patching Perl
sources:
=end original
特に、Perl ソースにパッチを適用する場合は、次の一般的なガイドラインに
従ってください:
=over 4
=item *
=begin original
8-wide tabs (no exceptions!)
=end original
8-wide tabs (no exceptions!)
(TBT)
=item *
=begin original
4-wide indents for code, 2-wide indents for nested CPP #defines
=end original
4-wide indents for code, 2-wide indents for nested CPP #defines
(TBT)
=item *
=begin original
Try hard not to exceed 79-columns
=end original
Try hard not to exceed 79-columns
(TBT)
=item *
=begin original
ANSI C prototypes
=end original
ANSI C prototypes
(TBT)
=item *
=begin original
Uncuddled elses and "K&R" style for indenting control constructs
=end original
Uncuddled elses and "K&R" style for indenting control constructs
(TBT)
=item *
=begin original
No C++ style (//) comments
=end original
No C++ style (//) comments
(TBT)
=item *
=begin original
Mark places that need to be revisited with XXX (and revisit often!)
=end original
Mark places that need to be revisited with XXX (and revisit often!)
(TBT)
=item *
=begin original
Opening brace lines up with "if" when conditional spans multiple lines;
should be at end-of-line otherwise
=end original
Opening brace lines up with "if" when conditional spans multiple lines;
should be at end-of-line otherwise
(TBT)
=item *
=begin original
In function definitions, name starts in column 0 (return value is on
previous line)
=end original
In function definitions, name starts in column 0 (return value is on
previous line)
(TBT)
=item *
=begin original
Single space after keywords that are followed by parens, no space
between function name and following paren
=end original
Single space after keywords that are followed by parens, no space
between function name and following paren
(TBT)
=item *
=begin original
Avoid assignments in conditionals, but if they're unavoidable, use
extra paren, e.g. "if (a && (b = c)) ..."
=end original
Avoid assignments in conditionals, but if they're unavoidable, use
extra paren, e.g. "if (a && (b = c)) ..."
(TBT)
=item *
=begin original
"return foo;" rather than "return(foo);"
=end original
"return foo;" rather than "return(foo);"
(TBT)
=item *
=begin original
"if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
=end original
"if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
(TBT)
=back
=head3 Test suite
(テストスイート)
=begin original
If your patch changes code (rather than just changing documentation),
you should also include one or more test cases which illustrate the bug
you're fixing or validate the new functionality you're adding. In
general, you should update an existing test file rather than create a
new one.
=end original
パッチによってコードが変更された場合(単なる文書の変更ではなく)、
修正しようとしているバグを説明するか、
追加しようとしている新機能を検証するテストケースを一つ以上含める
必要があります。
一般的には、新しいテストファイルを作成するのではなく、
既存のテストファイルを更新するべきです。
=begin original
Your test suite additions should generally follow these guidelines
(courtesy of Gurusamy Sarathy <gsar@activestate.com>):
=end original
テストスイートの追加は、一般的に次のガイドラインに従う必要があります
(Gurusamy Sarthy <gsar@activestate.com> による):
=over 4
=item *
=begin original
Know what you're testing. Read the docs, and the source.
=end original
Know what you're testing. Read the docs, and the source.
(TBT)
=item *
=begin original
Tend to fail, not succeed.
=end original
Tend to fail, not succeed.
(TBT)
=item *
=begin original
Interpret results strictly.
=end original
Interpret results strictly.
(TBT)
=item *
=begin original
Use unrelated features (this will flush out bizarre interactions).
=end original
Use unrelated features (this will flush out bizarre interactions).
(TBT)
=item *
=begin original
Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
=end original
Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
(TBT)
=item *
=begin original
Avoid using hardcoded test numbers whenever possible (the EXPECTED/GOT
found in t/op/tie.t is much more maintainable, and gives better failure
reports).
=end original
Avoid using hardcoded test numbers whenever possible (the EXPECTED/GOT
found in t/op/tie.t is much more maintainable, and gives better failure
reports).
(TBT)
=item *
=begin original
Give meaningful error messages when a test fails.
=end original
Give meaningful error messages when a test fails.
(TBT)
=item *
=begin original
Avoid using qx// and system() unless you are testing for them. If you
do use them, make sure that you cover _all_ perl platforms.
=end original
Avoid using qx// and system() unless you are testing for them. If you
do use them, make sure that you cover _all_ perl platforms.
(TBT)
=item *
=begin original
Unlink any temporary files you create.
=end original
Unlink any temporary files you create.
(TBT)
=item *
=begin original
Promote unforeseen warnings to errors with $SIG{__WARN__}.
=end original
Promote unforeseen warnings to errors with $SIG{__WARN__}.
(TBT)
=item *
=begin original
Be sure to use the libraries and modules shipped with the version being
tested, not those that were already installed.
=end original
Be sure to use the libraries and modules shipped with the version being
tested, not those that were already installed.
(TBT)
=item *
=begin original
Add comments to the code explaining what you are testing for.
=end original
Add comments to the code explaining what you are testing for.
(TBT)
=item *
=begin original
Make updating the '1..42' string unnecessary. Or make sure that you
update it.
=end original
Make updating the '1..42' string unnecessary. Or make sure that you
update it.
(TBT)
=item *
=begin original
Test _all_ behaviors of a given operator, library, or function.
=end original
Test _all_ behaviors of a given operator, library, or function.
(TBT)
=begin original
Test all optional arguments.
=end original
Test all optional arguments.
(TBT)
=begin original
Test return values in various contexts (boolean, scalar, list, lvalue).
=end original
Test return values in various contexts (boolean, scalar, list, lvalue).
(TBT)
=begin original
Use both global and lexical variables.
=end original
Use both global and lexical variables.
(TBT)
=begin original
Don't forget the exceptional, pathological cases.
=end original
Don't forget the exceptional, pathological cases.
(TBT)
=back
=head2 Patching a core module
(コアモジュールにパッチを当てる)
=begin original
This works just like patching anything else, with one extra
consideration.
=end original
これは他のパッチと同じように動作しますが、一つ特別な注意が必要です。
=begin original
Some core modules also live on CPAN and are maintained outside of the
Perl core. When the author updates the module, the updates are simply
copied into the core.
=end original
Some core modules also live on CPAN and are maintained outside of the
Perl core. When the author updates the module, the updates are simply
copied into the core.
(TBT)
=begin original
Modules in the F<cpan/> directory of the source tree are maintained
outside of the Perl core. See that module's listing on documentation or
its listing on L<http://search.cpan.org/> for more information on
reporting bugs and submitting patches.
=end original
Modules in the F<cpan/> directory of the source tree are maintained
outside of the Perl core. See that module's listing on documentation or
its listing on L<http://search.cpan.org/> for more information on
reporting bugs and submitting patches.
(TBT)
=begin original
In contrast, modules in the F<dist/> directory are maintained in the
core.
=end original
In contrast, modules in the F<dist/> directory are maintained in the
core.
(TBT)
=head2 Updating perldelta
=begin original
For changes significant enough to warrant a F<pod/perldelta.pod> entry,
the porters will greatly appreciate it if you submit a delta entry
along with your actual change. Significant changes include, but are not
limited to:
=end original
For changes significant enough to warrant a F<pod/perldelta.pod> entry,
the porters will greatly appreciate it if you submit a delta entry
along with your actual change. Significant changes include, but are not
limited to:
(TBT)
=over 4
=item *
=begin original
Adding, deprecating, or removing core features
=end original
Adding, deprecating, or removing core features
(TBT)
=item *
=begin original
Adding, deprecating, removing, or upgrading core or dual-life modules
=end original
Adding, deprecating, removing, or upgrading core or dual-life modules
(TBT)
=item *
=begin original
Adding new core tests
=end original
Adding new core tests
(TBT)
=item *
=begin original
Fixing security issues and user-visible bugs in the core
=end original
Fixing security issues and user-visible bugs in the core
(TBT)
=item *
=begin original
Changes that might break existing code, either on the perl or C level
=end original
Changes that might break existing code, either on the perl or C level
(TBT)
=item *
=begin original
Significant performance improvements
=end original
Significant performance improvements
(TBT)
=item *
=begin original
Adding, removing, or significantly changing documentation in the
F<pod/> directory
=end original
Adding, removing, or significantly changing documentation in the
F<pod/> directory
(TBT)
=item *
=begin original
Important platform-specific changes
=end original
Important platform-specific changes
(TBT)
=back
=begin original
Please make sure you add the perldelta entry to the right section
within F<pod/perldelta.pod>. More information on how to write good
perldelta entries is available in the C<Style> section of
F<Porting/how_to_write_a_perldelta.pod>.
=end original
Please make sure you add the perldelta entry to the right section
within F<pod/perldelta.pod>. More information on how to write good
perldelta entries is available in the C<Style> section of
F<Porting/how_to_write_a_perldelta.pod>.
(TBT)
=head2 What makes for a good patch?
=begin original
New features and extensions to the language can be contentious. There
is no specific set of criteria which determine what features get added,
but here are some questions to consider when developing a patch:
=end original
New features and extensions to the language can be contentious. There
is no specific set of criteria which determine what features get added,
but here are some questions to consider when developing a patch:
(TBT)
=head3 Does the concept match the general goals of Perl?
=begin original
Our goals include, but are not limited to:
=end original
目標には次のようなものがありますが、これには限りません:
=over 4
=item 1.
=begin original
Keep it fast, simple, and useful.
=end original
Keep it fast, simple, and useful.
(TBT)
=item 2.
=begin original
Keep features/concepts as orthogonal as possible.
=end original
Keep features/concepts as orthogonal as possible.
(TBT)
=item 3.
=begin original
No arbitrary limits (platforms, data sizes, cultures).
=end original
No arbitrary limits (platforms, data sizes, cultures).
(TBT)
=item 4.
=begin original
Keep it open and exciting to use/patch/advocate Perl everywhere.
=end original
Keep it open and exciting to use/patch/advocate Perl everywhere.
(TBT)
=item 5.
=begin original
Either assimilate new technologies, or build bridges to them.
=end original
Either assimilate new technologies, or build bridges to them.
(TBT)
=back
=head3 Where is the implementation?
=begin original
All the talk in the world is useless without an implementation. In
almost every case, the person or people who argue for a new feature
will be expected to be the ones who implement it. Porters capable of
coding new features have their own agendas, and are not available to
implement your (possibly good) idea.
=end original
実装なしでは、世界のすべての話は役に立ちません。
ほとんどすべての場合、新機能を主張する人は、それを実装する人であることが
期待されます。
新機能をコーディングできる porters は独自のアジェンダを持っており、
あなたの(おそらく良い)アイデアを実装するためには利用できません。
=head3 Backwards compatibility
=begin original
It's a cardinal sin to break existing Perl programs. New warnings can
be contentious--some say that a program that emits warnings is not
broken, while others say it is. Adding keywords has the potential to
break programs, changing the meaning of existing token sequences or
functions might break programs.
=end original
既存の Perl プログラムを破壊することは重大な罪です。
新しい警告については議論の余地があります --
警告を発するプログラムは破壊されないとする人もいれば、
破壊されるとする人もいます。
キーワードを追加するとプログラムが破壊される可能性があり、
既存のトークンシーケンスや関数の意味を変更すると
プログラムが破壊される可能性があります。
=begin original
The Perl 5 core includes mechanisms to help porters make backwards
incompatible changes more compatible such as the L<feature> and
L<deprecate> modules. Please use them when appropriate.
=end original
The Perl 5 core includes mechanisms to help porters make backwards
incompatible changes more compatible such as the L<feature> and
L<deprecate> modules. Please use them when appropriate.
(TBT)
=head3 Could it be a module instead?
=begin original
Perl 5 has extension mechanisms, modules and XS, specifically to avoid
the need to keep changing the Perl interpreter. You can write modules
that export functions, you can give those functions prototypes so they
can be called like built-in functions, you can even write XS code to
mess with the runtime data structures of the Perl interpreter if you
want to implement really complicated things.
=end original
Perl 5 には、
特に Perl インタプリタを変更し続ける必要がないようにするための、
拡張メカニズム、モジュール、XS があります。
関数をエクスポートするモジュールを書くこともできますし、
組み込み関数のように呼び出すことができるように
関数にプロトタイプを与えることもできますし、
非常に複雑なことを実装したい場合には、
Perl インタプリタの実行時データ構造をいじる XS コードを書くこともできます。
=begin original
Whenever possible, new features should be prototyped in a CPAN module
before they will be considered for the core.
=end original
Whenever possible, new features should be prototyped in a CPAN module
before they will be considered for the core.
(TBT)
=head3 Is the feature generic enough?
=begin original
Is this something that only the submitter wants added to the language,
or is it broadly useful? Sometimes, instead of adding a feature with a
tight focus, the porters might decide to wait until someone implements
the more generalized feature.
=end original
これは投稿者だけが言語に追加したいと思っているものなのでしょうか、
それとも広く有用なものなのでしょうか?
時には、焦点を絞った機能を追加する代わりに、porters は誰かが
より一般的な機能を実装するまで待つことに決めるかもしれません。
=head3 Does it potentially introduce new bugs?
=begin original
Radical rewrites of large chunks of the Perl interpreter have the
potential to introduce new bugs.
=end original
Perl インタプリタの大きな部分を大幅に書き換えてしまうと、
新しいバグが発生する可能性があります。
=head3 How big is it?
=begin original
The smaller and more localized the change, the better. Similarly, a
series of small patches is greatly preferred over a single large patch.
=end original
変化が小さく、局所的であればあるほど良いです。
同様に、一つの大きなパッチより、小さなパッチの連続の方がはるかに
好ましいです。
=head3 Does it preclude other desirable features?
=begin original
A patch is likely to be rejected if it closes off future avenues of
development. For instance, a patch that placed a true and final
interpretation on prototypes is likely to be rejected because there are
still options for the future of prototypes that haven't been addressed.
=end original
パッチが将来の開発の道を閉ざす場合、
パッチは却下される可能性が高いです。
例えば、プロトタイプに真の最終解釈を置いたパッチは、
まだ対処されていないプロトタイプの将来の選択肢がまだあるため、
却下される可能性が高いです。
=head3 Is the implementation robust?
=begin original
Good patches (tight code, complete, correct) stand more chance of going
in. Sloppy or incorrect patches might be placed on the back burner
until the pumpking has time to fix, or might be discarded altogether
without further notice.
=end original
優れたパッチ(厳密なコード、完全なパッチ、正しいパッチ)は、
入り込む可能性が高くなります。
ずさんなパッチや正しくないパッチは、pumpking が修正する時間があるまで
後回しにされたり、通知なしに完全に廃棄されたりします。
=head3 Is the implementation generic enough to be portable?
=begin original
The worst patches make use of system-specific features. It's highly
unlikely that non-portable additions to the Perl language will be
accepted.
=end original
最悪のパッチは、システム固有の機能を利用しています。
移植性のない Perl 言語への追加が受け入れられる可能性はほとんどありません。
=head3 Is the implementation tested?
=begin original
Patches which change behaviour (fixing bugs or introducing new
features) must include regression tests to verify that everything works
as expected.
=end original
動作を変更するパッチ(バグの修正や新機能の導入)には、
すべてが期待通りに動作することを検証するための
回帰テストを含める必要があります。
=begin original
Without tests provided by the original author, how can anyone else
changing perl in the future be sure that they haven't unwittingly
broken the behaviour the patch implements? And without tests, how can
the patch's author be confident that his/her hard work put into the
patch won't be accidentally thrown away by someone in the future?
=end original
元の著者が提供したテストがなければ、将来 Perl を変更する他の人が、
パッチが実装している動作を無意識のうちに破壊していないことを
確認するにはどうすればよいでしょうか?
また、テストがなければ、パッチの作成者は、
パッチに加えた自分の苦労が将来誰かによって誤って捨てられないと
確信するにはどうすればよいでしょうか?
=head3 Is there enough documentation?
=begin original
Patches without documentation are probably ill-thought out or
incomplete. No features can be added or changed without documentation,
so submitting a patch for the appropriate pod docs as well as the
source code is important.
=end original
文書のないパッチは、おそらく間違っているか不完全です。
文書なしではどんな機能も追加または変更できないので、
ソースコードとともに適切な pod 文書のパッチを提出することは重要です。
=head3 Is there another way to do it?
=begin original
Larry said "Although the Perl Slogan is I<There's More Than One Way to
Do It>, I hesitate to make 10 ways to do something". This is a tricky
heuristic to navigate, though--one man's essential addition is another
man's pointless cruft.
=end original
Larry は、「Perl のスローガンはI<There's More Than one way to Do It> ですが、
何かを行うための 10 の方法を作ることにはためらいがあります」と述べています。
しかし、これは運営のための巧妙なヒューリスティックです -- ある人の
本質的な追加は、別の人の無意味なたわごとです。
=head3 Does it create too much work?
=begin original
Work for the pumpking, work for Perl programmers, work for module
authors, ... Perl is supposed to be easy.
=end original
pumpking の仕事、Perl プログラマーの仕事、モジュール作成者の仕事…。
Perl は簡単なはずです。
=head3 Patches speak louder than words
=begin original
Working code is always preferred to pie-in-the-sky ideas. A patch to
add a feature stands a much higher chance of making it to the language
than does a random feature request, no matter how fervently argued the
request might be. This ties into "Will it be useful?", as the fact that
someone took the time to make the patch demonstrates a strong desire
for the feature.
=end original
動作するコードは、絵に描いた餅のアイデアよりも常に好まれます。
機能を追加するパッチは、ランダムな機能リクエストよりも、
そのリクエストがどんなに熱心に議論されたとしても、
言語に取り入れられる可能性がはるかに高くなります。
誰かが時間をかけてパッチを作成したという事実は、
その機能に対する強い欲求を示しているため、
これは "Will it be useful?" と結びついています。
=head1 TESTING
(テスト)
=begin original
The core uses the same testing style as the rest of Perl, a simple
"ok/not ok" run through Test::Harness, but there are a few special
considerations.
=end original
コアは Perl の他の部分と同じテストスタイルを使っており、
Test::Harness を通して単純な「ok/not ok」を実行しますが、
いくつか特別な考慮事項があります。
=begin original
There are three ways to write a test in the core. L<Test::More>,
F<t/test.pl> and ad hoc C<print $test ? "ok 42\n" : "not ok 42\n">. The
decision of which to use depends on what part of the test suite you're
working on. This is a measure to prevent a high-level failure (such as
Config.pm breaking) from causing basic functionality tests to fail.
=end original
コアにテストを記述する方法は三つあります。
L<Test::More>, F<t/test.pl>, アドホックな
C<print $test ? "ok 42\n" : "not ok 42\n"> です。
どれを使うかは、テストスイートのどの部分で
作業しているかによって決まります。
これは、高レベルの障害(Config.pm の破損など)によって基本的な機能テストが
失敗しないようにするための手段です。
=begin original
The F<t/test.pl> library provides some of the features of
L<Test::More>, but avoids loading most modules and uses as few core
features as possible.
=end original
The F<t/test.pl> library provides some of the features of
L<Test::More>, but avoids loading most modules and uses as few core
features as possible.
(TBT)
=begin original
If you write your own test, use the L<Test Anything Protocol|TAP>.
=end original
If you write your own test, use the L<Test Anything Protocol|TAP>.
(TBT)
=over 4
=item * F<t/base> and F<t/comp>
=begin original
Since we don't know if require works, or even subroutines, use ad hoc
tests for these two. Step carefully to avoid using the feature being
tested.
=end original
require が動作するのか、あるいはサブルーチンでさえも分からないので、
この二つに対してはアドホックテストを使ってください。
テスト中の機能を使わないように注意してください。
=item * F<t/cmd>, F<t/run>, F<t/io> and F<t/op>
=begin original
Now that basic require() and subroutines are tested, you can use the
F<t/test.pl> library.
=end original
これで基本的な require() とサブルーチンがテストされたので、
F<t/test.pl> ライブラリを使うことができます。
=begin original
You can also use certain libraries like Config conditionally, but be
sure to skip the test gracefully if it's not there.
=end original
Config のような特定のライブラリを条件付きで使うこともできますが、
テストがない場合にはテストを省略するようにしてください。
=item * Everything else
=begin original
Now that the core of Perl is tested, L<Test::More> can and should be
used. You can also use the full suite of core modules in the tests.
=end original
Perl のコアがテストされたので、L<Test::More> が使えますし
使うべきです。
また、コアモジュールの完全なスイートをテストで使うこともできます。
=back
=begin original
When you say "make test", Perl uses the F<t/TEST> program to run the
test suite (except under Win32 where it uses F<t/harness> instead). All
tests are run from the F<t/> directory, B<not> the directory which
contains the test. This causes some problems with the tests in F<lib/>,
so here's some opportunity for some patching.
=end original
"make test" とすれば、Perl は F<t/TEST> プログラムを使って
テストスイートを実行します(Win32 では、代わりに F<t/harness> を使います)。
すべてのテストは F<t/> ディレクトリから実行され、テストを含む
ディレクトリでは B<ありません>。
このため、F<lib/> 内のテストで問題が発生するので、パッチを適用する
機会があります。
=begin original
You must be triply conscious of cross-platform concerns. This usually
boils down to using L<File::Spec> and avoiding things like C<fork()>
and C<system()> unless absolutely necessary.
=end original
クロスプラットフォームに関する懸念を 3 倍意識する必要があります。
これは通常、L<File::Spec> を使い、絶対に必要でない限り C<fork()> や
C<system()> のようなものを避けることに要約されます。
=head2 Special C<make test> targets
(特殊 C<make test> ターゲット)
=begin original
There are various special make targets that can be used to test Perl
slightly differently than the standard "test" target. Not all them are
expected to give a 100% success rate. Many of them have several
aliases, and many of them are not available on certain operating
systems.
=end original
標準の "test" ターゲットとは若干異なる方法で Perl をテストするために
使える特殊な make ターゲットがいくつかあります。
すべての make ターゲットが 100% の成功率を示すとは限りません。
これらの多くには複数の別名があり、その多くは特定の
オペレーティングシステムでは使えません。
=over 4
=item * test_porting
=begin original
This runs some basic sanity tests on the source tree and helps catch
basic errors before you submit a patch.
=end original
This runs some basic sanity tests on the source tree and helps catch
basic errors before you submit a patch.
(TBT)
=item * coretest
=begin original
Run F<perl> on all core tests (F<t/*> and F<lib/[a-z]*> pragma tests).
=end original
全てのコアテスト (F<t/*> と F<lib/[a-z]*> プラグマテスト) で F<perl> を
実行します。
=begin original
(Not available on Win32)
=end original
(Win32 では利用できません)
=item * test.deparse
=begin original
Run all the tests through L<B::Deparse>. Not all tests will succeed.
=end original
全てのテストを L<B::Deparse> を通して実行します。
全てのテストが成功するわけではありません。
=begin original
(Not available on Win32)
=end original
(Win32 では利用できません)
=item * test.taintwarn
=begin original
Run all tests with the B<-t> command-line switch. Not all tests are
expected to succeed (until they're specifically fixed, of course).
=end original
全てのテストを B<-t> コマンドラインスイッチ付きで実行します。
全てのテストが成功するとは想定されません(もちろん具体的に修正するまでです)。
=begin original
(Not available on Win32)
=end original
(Win32 では利用できません)
=item * minitest
=begin original
Run F<miniperl> on F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>,
F<t/op>, F<t/uni> and F<t/mro> tests.
=end original
F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>, F<t/op>, F<t/uni>,
F<t/mro> テストで F<miniperl> を実行します。
=item * test.valgrind check.valgrind utest.valgrind ucheck.valgrind
=begin original
(Only in Linux) Run all the tests using the memory leak + naughty
memory access tool "valgrind". The log files will be named
F<testname.valgrind>.
=end original
(Linux のみ) 全てのテストをメモリリーク+メモリアクセスツール
"valgrind" を使って実行します。
ログファイルの名前は F<testname.valgrind> です。
=item * test.torture torturetest
=begin original
Run all the usual tests and some extra tests. As of Perl 5.8.0, the only
extra tests are Abigail's JAPHs, F<t/japh/abigail.t>.
=end original
全ての通常のテストといくつかの追加のテストを実行します。
Perl 5.8.0 から、追加のテストは Abigail の JAPHs, F<t/japh/abigail.t>
だけです。
=begin original
You can also run the torture test with F<t/harness> by giving
C<-torture> argument to F<t/harness>.
=end original
F<t/harness> に C<-torture> 引数を与えることでも F<t/harness> で耐久テストを
実行できます。
=item * utest ucheck test.utf8 check.utf8
=begin original
Run all the tests with -Mutf8. Not all tests will succeed.
=end original
全てのテストを -Mutf8 で実行します。
全てのテストが成功するわけではありません。
=begin original
(Not available on Win32)
=end original
(Win32 では利用できません)
=item * minitest.utf16 test.utf16
=begin original
Runs the tests with UTF-16 encoded scripts, encoded with different
versions of this encoding.
=end original
UTF-16 の様々なバージョンでエンコードされたスクリプトでテストを
実行します。
=begin original
C<make utest.utf16> runs the test suite with a combination of C<-utf8>
and C<-utf16> arguments to F<t/TEST>.
=end original
C<make utest.utf16> は F<t/TEST> へ C<-utf8> と C<-utf16> 引数を組み合わせて
テストスイートを実行します。
=begin original
(Not available on Win32)
=end original
(Win32 では利用できません)
=item * test_harness
=begin original
Run the test suite with the F<t/harness> controlling program, instead
of F<t/TEST>. F<t/harness> is more sophisticated, and uses the
L<Test::Harness> module, thus using this test target supposes that perl
mostly works. The main advantage for our purposes is that it prints a
detailed summary of failed tests at the end. Also, unlike F<t/TEST>, it
doesn't redirect stderr to stdout.
=end original
F<t/TEST> ではなく、F<t/harness> 制御プログラムでテストスイートを実行します。
F<t/harness> はより洗練されており、L<Test::Harness> モジュールを使います;
したがって、このテストターゲットを使うと、perl はほとんど動作すると
想定されます。
私たちの目的にとっての主な利点は、失敗したテストの詳細な要約が最後に
出力されることです。
また、F<t/TEST> とは異なり、stderr を stdout にリダイレクトしません。
=begin original
Note that under Win32 F<t/harness> is always used instead of F<t/TEST>,
so there is no special "test_harness" target.
=end original
Win32 では、F<t/TEST> の代わりに常に F<t/harness> が使われるので、特別な
"test_harness" ターゲットはありません。
=begin original
Under Win32's "test" target you may use the TEST_SWITCHES and
TEST_FILES environment variables to control the behaviour of
F<t/harness>. This means you can say
=end original
Win32の "test" ターゲットでは、環境変数 TEST_SWITCHES とTEST_FILES を
使って F<t/harness> の動作を制御することができます。
これは次のようにできるということです:
nmake test TEST_FILES="op/*.t"
nmake test TEST_SWITCHES="-torture" TEST_FILES="op/*.t"
=item * test-notty test_notty
=begin original
Sets PERL_SKIP_TTY_TEST to true before running normal test.
=end original
通常のテストを実行する前に PERL_SKIP_TTY_TEST を真に設定します。
=back
=head2 Parallel tests
(並列テスト)
=begin original
The core distribution can now run its regression tests in parallel on
Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS>
in your environment to the number of tests to run in parallel, and run
C<make test_harness>. On a Bourne-like shell, this can be done as
=end original
コア配布は、Unix 風のプラットフォームでは退行テストを並列に
実行できるようになりました。
C<make test> を実行する代わりに、並列に実行するテストの数を
環境変数 C<TEST_JOBS> に設定して、
C<make test_harness> を実行してください。
Bourne 風のシェルでは、これは次のようになります:
TEST_JOBS=3 make test_harness # Run 3 tests in parallel
=begin original
An environment variable is used, rather than parallel make itself,
because L<TAP::Harness> needs to be able to schedule individual
non-conflicting test scripts itself, and there is no standard interface
to C<make> utilities to interact with their job schedulers.
=end original
並列 make 自身ではなく環境変数が使われます;
L<TAP::Harness> は衝突しないテストスクリプトを自身でスケジュールできる
必要があり、C<make> ユーティリティとこれらのジョブスケジューラを
相互作用させる標準的なインターフェースはないからです。
=begin original
Note that currently some test scripts may fail when run in parallel (most
notably C<ext/IO/t/io_dir.t>). If necessary, run just the failing scripts
again sequentially and see if the failures go away.
=end original
現在の所、並列に実行すると失敗するかもしれないテストがいくつか
あることに注意してください (もっとも顕著なものは C<ext/IO/t/io_dir.t>)。
もし必要なら、失敗したスクリプトを単に直列に再び実行して、
失敗しなくなるかを見てください。
=head2 Running tests by hand
(手動でテストを実行する)
=begin original
You can run part of the test suite by hand by using one of the following
commands from the F<t/> directory:
=end original
F<t/> ディレクトリで以下のコマンドの一つを使うことでテストスイートの一部を
手動で実行できます:
./perl -I../lib TEST list-of-.t-files
=begin original
or
=end original
または
./perl -I../lib harness list-of-.t-files
=begin original
(If you don't specify test scripts, the whole test suite will be run.)
=end original
(テストスクリプトを指定しないと、テストスイート全体が実行されます。)
=head2 Using F<t/harness> for testing
(テストに F<t/harness> を使う)
=begin original
If you use C<harness> for testing, you have several command line options
available to you. The arguments are as follows, and are in the order
that they must appear if used together.
=end original
テストに C<harness> を使う場合は、いくつかのコマンドラインオプションを
使えます。
引数は次のとおりで、一緒に使った場合に現れなければならない
順序になっています:
harness -v -torture -re=pattern LIST OF FILES TO TEST
harness -v -torture -re LIST OF PATTERNS TO MATCH
=begin original
If C<LIST OF FILES TO TEST> is omitted, the file list is obtained from
the manifest. The file list may include shell wildcards which will be
expanded out.
=end original
C<LIST OF FILES TO TEST> が省略された場合、ファイルリストは
マニフェストから取得されます。
ファイルリストにはシェルワイルドカードが含まれている可能性があります。
=over 4
=item * -v
=begin original
Run the tests under verbose mode so you can see what tests were run,
and debug output.
=end original
テストを詳細モードで実行するので、実行されたテストとデバッグ出力を
確認できます。
=item * -torture
=begin original
Run the torture tests as well as the normal set.
=end original
通常のセットと同様に拷問テストを実行します。
=item * -re=PATTERN
=begin original
Filter the file list so that all the test files run match PATTERN. Note
that this form is distinct from the B<-re LIST OF PATTERNS> form below
in that it allows the file list to be provided as well.
=end original
すべてのテストファイルが PATTERN にマッチングするようにファイルリストを
フィルタリングします。
この形式は、ファイルリストも指定できるという点で、次の
B<-re LIST OF PATTERNS> 形式とは異なることに注意してください。
=item * -re LIST OF PATTERNS
=begin original
Filter the file list so that all the test files run match
/(LIST|OF|PATTERNS)/. Note that with this form the patterns are joined
by '|' and you cannot supply a list of files, instead the test files
are obtained from the MANIFEST.
=end original
実行するすべてのテストファイルが match/(LIST OF PATTERNS)/ に
マッチングするようにファイルリストをフィルタリングします。
この形式では、パターンは''で結合され、ファイルのリストを指定できません。
かわりに、テストファイルは MANIFEST から取得されます。
=back
=begin original
You can run an individual test by a command similar to
=end original
次のようなコマンドで、個々のテストを実行できます:
./perl -I../lib path/to/foo.t
=begin original
except that the harnesses set up some environment variables that may
affect the execution of the test:
=end original
ただし、ハーネスは、テストの実行に影響を与える可能性のあるいくつかの
環境変数を設定します:
=over 4
=item * PERL_CORE=1
=begin original
indicates that we're running this test as part of the perl core test
suite. This is useful for modules that have a dual life on CPAN.
=end original
これは、perl コアテストスイートのこのテスト部分を実行していることを示します。
これは、CPAN上で二重管理されているモジュールに役立ちます。
=item * PERL_DESTRUCT_LEVEL=2
=begin original
is set to 2 if it isn't set already (see
L<perlhacktips/PERL_DESTRUCT_LEVEL>).
=end original
まだ設定されていない場合は 2 に設定されます
(L<perlhacktips/PERL_DESTRUCT_LEVEL> を参照)。
=item * PERL
=begin original
(used only by F<t/TEST>) if set, overrides the path to the perl
executable that should be used to run the tests (the default being
F<./perl>).
=end original
(F<t/TEST> でのみ使用)設定されている場合、テストの実行に使う
perl 実行可能ファイルへのパスを上書きします(デフォルトは F<./perl>)。
=item * PERL_SKIP_TTY_TEST
=begin original
if set, tells to skip the tests that need a terminal. It's actually set
automatically by the Makefile, but can also be forced artificially by
running 'make test_notty'.
=end original
設定すると、ターミナルが必要なテストを飛ばします。
これは実際には Makefile で自動的に設定されますが、
'make test_notty' を実行して人為的に設定することもできます。
=back
=head3 Other environment variables that may influence tests
(テストに影響を与えるかも知れないその他の環境変数)
=over 4
=item * PERL_TEST_Net_Ping
=begin original
Setting this variable runs all the Net::Ping modules tests, otherwise
some tests that interact with the outside world are skipped. See
L<perl58delta>.
=end original
この変数を設定すると、すべての Net::Ping モジュールテストが実行されます;
そうでない場合、外部世界と対話する一部のテストはスキップされます。
L<perl58delta> を参照してください。
=item * PERL_TEST_NOVREXX
=begin original
Setting this variable skips the vrexx.t tests for OS2::REXX.
=end original
この変数を設定すると、OS2::REXX の vrexx.t テストがスキップされます。
=item * PERL_TEST_NUMCONVERTS
=begin original
This sets a variable in op/numconvert.t.
=end original
op/numconvert.t に変数を設定します。
=back
=begin original
See also the documentation for the Test and Test::Harness modules, for
more environment variables that affect testing.
=end original
テストに影響を与える環境変数については、Test および
Test::Harness モジュールの文書も参照してください。
=head1 MORE READING FOR GUTS HACKERS
=begin original
To hack on the Perl guts, you'll need to read the following things:
=end original
Perl の本質をハックするためには、以下を読む必要があります:
=over 4
=item * L<perlsource>
=begin original
An overview of the Perl source tree. This will help you find the files
you're looking for.
=end original
An overview of the Perl source tree. This will help you find the files
you're looking for.
(TBT)
=item * L<perlinterp>
=begin original
An overview of the Perl interpreter source code and some details on how
Perl does what it does.
=end original
An overview of the Perl interpreter source code and some details on how
Perl does what it does.
(TBT)
=item * L<perlhacktut>
=begin original
This document walks through the creation of a small patch to Perl's C
code. If you're just getting started with Perl core hacking, this will
help you understand how it works.
=end original
This document walks through the creation of a small patch to Perl's C
code. If you're just getting started with Perl core hacking, this will
help you understand how it works.
(TBT)
=item * L<perlhacktips>
=begin original
More details on hacking the Perl core. This document focuses on lower
level details such as how to write tests, compilation issues,
portability, debugging, etc.
=end original
More details on hacking the Perl core. This document focuses on lower
level details such as how to write tests, compilation issues,
portability, debugging, etc.
(TBT)
=begin original
If you plan on doing serious C hacking, make sure to read this.
=end original
If you plan on doing serious C hacking, make sure to read this.
(TBT)
=item * L<perlguts>
=begin original
This is of paramount importance, since it's the documentation of what
goes where in the Perl source. Read it over a couple of times and it
might start to make sense - don't worry if it doesn't yet, because the
best way to study it is to read it in conjunction with poking at Perl
source, and we'll do that later on.
=end original
これは、Perl ソースのどこに何があるかを記述した文書なので、非常に重要です。
この文書を何度か読んでみると、分かりはじめてくるかもしれませんが、
まだでも心配する必要はありません;
なぜなら、この文書を学ぶ最善の方法は、Perl ソースを調べながら
読むことであり、これは後で行いますから。
=begin original
Gisle Aas's "illustrated perlguts", also known as I<illguts>, has very
helpful pictures:
=end original
Gisle Aas の、 I<illguts> としても知られる "illustrated perlguts" には、
とても役に立つ絵があります。
L<http://search.cpan.org/dist/illguts/>
=item * L<perlxstut> and L<perlxs>
=begin original
A working knowledge of XSUB programming is incredibly useful for core
hacking; XSUBs use techniques drawn from the PP code, the portion of
the guts that actually executes a Perl program. It's a lot gentler to
learn those techniques from simple examples and explanation than from
the core itself.
=end original
XSUB プログラミングの実用的な知識は、コアハッキングに非常に役立ちます;
XSUBs では、Perl プログラムを実際に実行するコア部分である
PP コードから引き出されたテクニックを使います。
これらのテクニックをコア自体から学ぶよりも、
簡単な例や説明から学ぶ方がはるかにやさしいです。
=item * L<perlapi>
=begin original
The documentation for the Perl API explains what some of the internal
functions do, as well as the many macros used in the source.
=end original
Perl API の文書では、内部関数の機能や、ソースで使われる多くのマクロについて
説明しています。
=item * F<Porting/pumpkin.pod>
=begin original
This is a collection of words of wisdom for a Perl porter; some of it
is only useful to the pumpkin holder, but most of it applies to anyone
wanting to go about Perl development.
=end original
これは、Perl porters のための英知を集めたものです;
その中にはパンプキンを持っている人にしか役に立たないものもありますが、
そのほとんどは Perl 開発を行おうとする人にも当てはまります。
=item * The perl5-porters FAQ
=begin original
This should be available from
http://dev.perl.org/perl5/docs/p5p-faq.html . It contains hints on
reading perl5-porters, information on how perl5-porters works and how
Perl development in general works.
=end original
http://dev.perl.org/perl5/docs/p5p-faq.html から入手できます。
perl5-porters を読むためのヒント、perl5-porters がどのように動作するか、
そして Perl 開発がどのように一般的に動作するかについての情報が
含まれています。
=back
=head1 CPAN TESTERS AND PERL SMOKERS
=begin original
The CPAN testers ( http://testers.cpan.org/ ) are a group of volunteers
who test CPAN modules on a variety of platforms.
=end original
CPAN testers (http://testers.cpan.org/) は、さまざまな
プラットフォームで CPAN モジュールをテストするボランティアのグループです。
=begin original
Perl Smokers ( http://www.nntp.perl.org/group/perl.daily-build/ and
http://www.nntp.perl.org/group/perl.daily-build.reports/ )
automatically test Perl source releases on platforms with various
configurations.
=end original
Perl Smokers ( http://www.nntp.perl.org/group/perl.daily-build/ と
http://www.nntp.perl.org/group/perl.daily-build.reports/ ) は、
さまざまな構成のプラットフォームでPerlソースリリースを自動的にテストします。
=begin original
Both efforts welcome volunteers. In order to get involved in smoke
testing of the perl itself visit
L<http://search.cpan.org/dist/Test-Smoke/>. In order to start smoke
testing CPAN modules visit
L<http://search.cpan.org/dist/CPANPLUS-YACSmoke/> or
L<http://search.cpan.org/dist/minismokebox/> or
L<http://search.cpan.org/dist/CPAN-Reporter/>.
=end original
どちらの取り組みもボランティアを歓迎しています。
Perl 自体のスモークテストに参加するには、
L<http://search.cpan.org/dist/Test-Smoke/> を訪れてください。
CPAN モジュールのスモークテストを開始するには、
L<http://search.cpan.org/dist/CPANPLUS-YACSmoke/> または
L<http://search.cpan.org/dist/minismokebox/> または
L<http://search.cpan.org/dist/CPAN-Reporter/> を訪れてください。
=head1 WHAT NEXT?
=begin original
If you've read all the documentation in the document and the ones
listed above, you're more than ready to hack on Perl.
=end original
If you've read all the documentation in the document and the ones
listed above, you're more than ready to hack on Perl.
(TBT)
=begin original
Here's some more recommendations
=end original
Here's some more recommendations
(TBT)
=over 4
=item *
=begin original
Subscribe to perl5-porters, follow the patches and try and understand
them; don't be afraid to ask if there's a portion you're not clear on -
who knows, you may unearth a bug in the patch...
=end original
perl5-porters を購読して、パッチを追いかけ、試してみて理解します;
はっきりしない部分を訊ねるのを恐れないでください - あなたがパッチのバグを
掘り出すかも知れないことを知っています…
=item *
=begin original
Do read the README associated with your operating system, e.g.
README.aix on the IBM AIX OS. Don't hesitate to supply patches to that
README if you find anything missing or changed over a new OS release.
=end original
オペレーティングシステムに関連づけられた README (例えば IBM AIX OS なら
README.aix) を読みます。
新しい OS のリリースで抜けていたり変更されていることに気付いたら、
その README へのパッチを提供することを遠慮しないでください。
=item *
=begin original
Find an area of Perl that seems interesting to you, and see if you can
work out how it works. Scan through the source, and step over it in the
debugger. Play, poke, investigate, fiddle! You'll probably get to
understand not just your chosen area but a much wider range of
F<perl>'s activity as well, and probably sooner than you'd think.
=end original
自分にとって興味深いと思われる Perl の分野を見つけて、作業をすると
どのように動作するかを見ます。
ソースをスキャンして、デバッガでステップ実行します。
遊んでつついて調べていじります!
おそらく、選んだ分野だけではなく、F<perl> のもっと広い範囲の動作も
理解する必要があって、それはおそらくあなたが考えているより早いでしょう。
=back
=head2 "The Road goes ever on and on, down from the door where it began."
("道はつづくよ、先へ先へと、戸口より出て、遠くへつづく。")
=begin original
If you can do these things, you've started on the long road to Perl
porting. Thanks for wanting to help make Perl better - and happy
hacking!
=end original
これらのことができれば、Perl porting への長い道の開始です。
Perl をよりよくする助けをしようとしてくれてありがとう - そして happy hacking!
=head2 Metaphoric Quotations
(比喩的な引用)
=begin original
If you recognized the quote about the Road above, you're in luck.
=end original
上述の道に関する引用に気付いたなら、運があります。
=begin original
Most software projects begin each file with a literal description of
each file's purpose. Perl instead begins each with a literary allusion
to that file's purpose.
=end original
ほとんどのソフトウェアプロジェクトでは、それぞれのファイルは、ファイルの
目的の文字通りの説明で始まります。
Perl はそうではなく、ファイルの目的の文学的な言及で始まります。
=begin original
Like chapters in many books, all top-level Perl source files (along
with a few others here and there) begin with an epigramic inscription
that alludes, indirectly and metaphorically, to the material you're
about to read.
=end original
多くの本の章のように、トップレベル (およびあちこちにあるいくつかの)
Perl ソースファイルは、今から読もうとしているものへの暗示的、間接的、
隠喩的な警句的碑文で始まります。
=begin original
Quotations are taken from writings of J.R.R. Tolkien pertaining to his
Legendarium, almost always from I<The Lord of the Rings>. Chapters and
page numbers are given using the following editions:
=end original
引用は J.R.R. Tolkien の著作とそれに付随する世界から取られます; ほとんど常に
I<The Lord of the Rings> (指輪物語) からです。
章と頁番号は以下の版から取られています:
=over 4
=item *
=begin original
I<The Hobbit>, by J.R.R. Tolkien. The hardcover, 70th-anniversary
edition of 2007 was used, published in the UK by Harper Collins
Publishers and in the US by the Houghton Mifflin Company.
=end original
J.R.R. Tolkien による I<The Hobbit> (ホビットの冒険)。
イギリスでは Harper Collins Publishers から、アメリカでは the Houghton
Mifflin Company から出版された、2007 年の 70 周年記念ハードカバー版が
使われています。
=item *
=begin original
I<The Lord of the Rings>, by J.R.R. Tolkien. The hardcover,
50th-anniversary edition of 2004 was used, published in the UK by
Harper Collins Publishers and in the US by the Houghton Mifflin
Company.
=end original
J.R.R. Tolkien による I<The Lord of the Rings> (指輪物語)。
イギリスでは Harper Collins Publishers から、アメリカでは the Houghton
Mifflin Company から出版された、2004 年の 50 周年記念ハードカバー版が
使われています。
=item *
=begin original
I<The Lays of Beleriand>, by J.R.R. Tolkien and published posthumously
by his son and literary executor, C.J.R. Tolkien, being the 3rd of the
12 volumes in Christopher's mammoth I<History of Middle Earth>. Page
numbers derive from the hardcover edition, first published in 1983 by
George Allen & Unwin; no page numbers changed for the special 3-volume
omnibus edition of 2002 or the various trade-paper editions, all again
now by Harper Collins or Houghton Mifflin.
=end original
J.R.R. Tolkien による I<The Lays of Beleriand>; 死後、息子であり
遺著管理者である C.J.R. Tolkien によって出版された 12 巻からなる巨大な
I<History of Middle Earth> の第 3 巻。
頁番号は George Allen & Unwin から 1983 年に出版されたハードカバー版に
依っています; Harper Collins や Houghton Mifflin による、2002 年の特別 3 巻
オムニバス版や様々な trade-paper 版でも頁番号は変わっていません。
=back
=begin original
Other JRRT books fair game for quotes would thus include I<The
Adventures of Tom Bombadil>, I<The Silmarillion>, I<Unfinished Tales>,
and I<The Tale of the Children of Hurin>, all but the first
posthumously assembled by CJRT. But I<The Lord of the Rings> itself is
perfectly fine and probably best to quote from, provided you can find a
suitable quote there.
=end original
その他の JRRT の本である I<The Adventures of Tom Bombadil>
(トム・ボンバディルの冒険)、I<The Silmarillion>(シルマリルの物語)、
I<Unfinished Tales>(終わらざりし物語)、
I<The Tale of the Children of Hurin> も引用の元となります (最初のもの以外は
死後 CJRT によって編纂されたものです)。
しかし、適切な引用が見つけられるなら、I<The Lord of the Rings> は引用元として
完全によく、おそらく最良のものです。
=begin original
So if you were to supply a new, complete, top-level source file to add
to Perl, you should conform to this peculiar practice by yourself
selecting an appropriate quotation from Tolkien, retaining the original
spelling and punctuation and using the same format the rest of the
quotes are in. Indirect and oblique is just fine; remember, it's a
metaphor, so being meta is, after all, what it's for.
=end original
それで、Perl に追加するための新しくて完全なトップレベルソースファイルを
提供しようとしているなら、Tolkien から適切な引用を自分で選択して、
元の綴りと句読点を残して他の引用と同じ形式を使うという、特有の慣例に
従うべきです。
間接的で遠回しでもかまいません; これはメタファーであり、メタであると
いうことは、結局、ためにするものであるということを忘れないでください。
=head1 AUTHOR
=begin original
This document was originally written by Nathan Torkington, and is
maintained by the perl5-porters mailing list.
=end original
この文書はもともと Nathan Torkington によって書かれ、
perl5-porters メーリングリストで管理されています。
=begin meta
Translate: SHIRAKATA Kentaro <argrath@ub32.org>
Status: in progress
=end meta