Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 15131] ファイルの概要

このコミットは、Go言語のコマンドラインツールgoのドキュメントファイルsrc/cmd/go/doc.goを更新するものです。具体的には、go testコマンドに関連するフラグの説明が修正されています。

コミット

cmd/go: update doc.go

R=golang-dev, adg CC=golang-dev https://golang.org/cl/7279047

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/49fe632c7d93dcf83d16cf7ee7fd09b165ce4b94

元コミット内容

commit 49fe632c7d93dcf83d16cf7ee7fd09b165ce4b94
Author: Shenghou Ma <minux.ma@gmail.com>
Date:   Tue Feb 5 05:45:35 2013 +0800

    cmd/go: update doc.go
    
    R=golang-dev, adg
    CC=golang-dev
    https://golang.org/cl/7279047
---
 src/cmd/go/doc.go | 87 ++++++++++++++++++++++++++++++-------------------------\n 1 file changed, 47 insertions(+), 40 deletions(-)\n\ndiff --git a/src/cmd/go/doc.go b/src/cmd/go/doc.go
index 5f402624ef..6de4405625 100644
--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -679,31 +679,47 @@ Description of testing flags
 The 'go test' command takes both flags that apply to 'go test' itself
 and flags that apply to the resulting test binary.
 
-The test binary, called pkg.test, where pkg is the name of the
-directory containing the package sources, has its own flags:\n+The following flags are recognized by the 'go test' command and\n+control the execution of any test:\n \n-\t-test.v\n-\t    Verbose output: log all tests as they are run.\n-\n-\t-test.run pattern\n-\t    Run only those tests and examples matching the regular\n-\t    expression.\n-\n-\t-test.bench pattern\n+\t-bench regexp\n \t    Run benchmarks matching the regular expression.\n-\t    By default, no benchmarks run.\n+\t    By default, no benchmarks run. To run all benchmarks,\n+\t    use '-bench .' or '-bench=.'.\n \n-\t-test.benchmem\n+\t-benchmem\n \t    Print memory allocation statistics for benchmarks.\n \n-\t-test.cpuprofile cpu.out\n+\t-benchtime t\n+\t\tRun enough iterations of each benchmark to take t, specified\n+\t\tas a time.Duration (for example, -benchtime 1h30s).\n+\t\tThe default is 1 second (1s).\n+\n+\t-blockprofile block.out\n+\t    Write a goroutine blocking profile to the specified file\n+\t    when all tests are complete.\n+\n+\t-blockprofilerate n\n+\t    Control the detail provided in goroutine blocking profiles by setting\n+\t    runtime.BlockProfileRate to n.  See 'godoc runtime BlockProfileRate'.\n+\t    The profiler aims to sample, on average, one blocking event every\n+\t    n nanoseconds the program spends blocked.  By default,\n+\t    if -test.blockprofile is set without this flag, all blocking events\n+\t    are recorded, equivalent to -test.blockprofilerate=1.\n+\n+\t-cpu 1,2,4\n+\t    Specify a list of GOMAXPROCS values for which the tests or\n+\t    benchmarks should be executed.  The default is the current value\n+\t    of GOMAXPROCS.\n+\n+\t-cpuprofile cpu.out\n \t    Write a CPU profile to the specified file before exiting.\n \n-\t-test.memprofile mem.out\n+\t-memprofile mem.out\n \t    Write a memory profile to the specified file when all tests\n \t    are complete.\n \n-\t-test.memprofilerate n\n+\t-memprofilerate n\n \t    Enable more precise (and expensive) memory profiles by setting\n \t    runtime.MemProfileRate.  See 'godoc runtime MemProfileRate'.\n \t    To profile all memory allocations, use -test.memprofilerate=1\n@@ -711,44 +727,35 @@ directory containing the package sources, has its own flags:\n \t    garbage collector, provided the test can run in the available\n \t    memory without garbage collection.\n \n-\t-test.blockprofile block.out\n-\t    Write a goroutine blocking profile to the specified file\n-\t    when all tests are complete.\n-\n-\t-test.blockprofilerate n\n-\t    Control the detail provided in goroutine blocking profiles by setting\n-\t    runtime.BlockProfileRate to n.  See 'godoc runtime BlockProfileRate'.\n-\t    The profiler aims to sample, on average, one blocking event every\n-\t    n nanoseconds the program spends blocked.  By default,\n-\t    if -test.blockprofile is set without this flag, all blocking events\n-\t    are recorded, equivalent to -test.blockprofilerate=1.\n-\n-\t-test.parallel n\n+\t-parallel n\n \t    Allow parallel execution of test functions that call t.Parallel.\n \t    The value of this flag is the maximum number of tests to run\n \t    simultaneously; by default, it is set to the value of GOMAXPROCS.\n \n-\t-test.short\n+\t-run regexp\n+\t    Run only those tests and examples matching the regular\n+\t    expression.\n+\n+\t-short\n \t    Tell long-running tests to shorten their run time.\n \t    It is off by default but set during all.bash so that installing\n \t    the Go tree can run a sanity check but not spend time running\n \t    exhaustive tests.\n \n-\t-test.timeout t\n+\t-timeout t\n \t\tIf a test runs longer than t, panic.\n \n-\t-test.benchtime t\n-\t\tRun enough iterations of each benchmark to take t.\n-\t\tThe default is 1 second.\n+\t-v\n+\t    Verbose output: log all tests as they are run.\n \n-\t-test.cpu 1,2,4\n-\t    Specify a list of GOMAXPROCS values for which the tests or\n-\t    benchmarks should be executed.  The default is the current value\n-\t    of GOMAXPROCS.\n+The test binary, called pkg.test where pkg is the name of the\n+directory containing the package sources, can be invoked directly\n+after building it with 'go test -c'. When invoking the test binary\n+directly, each of the standard flag names must be prefixed with 'test.',\n+as in -test.run=TestMyFunc or -test.v.\n \n-For convenience, each of these -test.X flags of the test binary is\n-also available as the flag -X in 'go test' itself.  Flags not listed\n-here are passed through unaltered.  For instance, the command\n+When running 'go test', flags not listed above are passed through\n+unaltered. For instance, the command\n \n \tgo test -x -v -cpuprofile=prof.out -dir=testdata -update\n \n```

## 変更の背景

このコミットの主な目的は、`go test`コマンドのドキュメントを改善し、ユーザーがテストフラグをより正確に理解し、使用できるようにすることです。特に、以下の点が変更の背景として挙げられます。

1.  **フラグ名の統一と明確化**: 以前のドキュメントでは、`go test`コマンドに直接渡すフラグと、生成されるテストバイナリに渡すフラグの区別が曖昧でした。特に、テストバイナリに渡すフラグには`-test.`というプレフィックスが必要でしたが、`go test`コマンドに直接渡す場合はプレフィックスが不要でした。このコミットでは、`go test`コマンドに直接渡す際のフラグ名から`-test.`プレフィックスを削除し、より簡潔で直感的な表記に統一しています。
2.  **プロファイリング関連フラグの追加と詳細化**: `benchtime`、`blockprofile`、`blockprofilerate`、`cpu`といったプロファイリングや実行制御に関する重要なフラグの説明が追加または詳細化されています。これにより、ユーザーはテストのパフォーマンス分析や実行環境の制御をより細かく行えるようになります。
3.  **ドキュメントの整理と可読性の向上**: フラグの説明の順序が変更され、関連するフラグが近くに配置されるなど、ドキュメント全体の構成が改善されています。これにより、ユーザーは必要な情報をより見つけやすくなっています。

## 前提知識の解説

このコミットの変更内容を理解するためには、以下のGo言語のテストに関する基本的な知識が必要です。

*   **`go test`コマンド**: Go言語の標準的なテスト実行ツールです。Goのソースコード内のテスト関数（`TestXxx`）、ベンチマーク関数（`BenchmarkXxx`）、サンプル関数（`ExampleXxx`）を自動的に発見し、実行します。
*   **テストフラグ**: `go test`コマンドには、テストの実行方法を制御するための様々なフラグが用意されています。例えば、特定のテストのみを実行したり、ベンチマークを実行したり、プロファイリング情報を出力したりすることができます。
*   **テストバイナリ**: `go test`コマンドは、内部的にテストコードをコンパイルして実行可能なバイナリ（通常は`pkg.test`という名前）を生成します。このバイナリは、`go test -c`コマンドを使って明示的に生成し、後から直接実行することも可能です。
*   **`GOMAXPROCS`**: Goランタイムが同時に実行できるOSスレッドの最大数を制御する環境変数です。テストの並列実行やCPUプロファイリングにおいて重要な役割を果たします。
*   **プロファイリング**: プロファイリングとは、プログラムの実行中にその性能特性（CPU使用率、メモリ割り当て、ゴルーチンのブロッキングなど）を測定・分析することです。Goには、標準でCPUプロファイリング、メモリプロファイリング、ブロッキングプロファイリングなどの機能が組み込まれています。
    *   **CPUプロファイリング**: プログラムがCPU時間をどこで消費しているかを分析します。
    *   **メモリプロファイリング**: プログラムがメモリをどのように割り当て、使用しているかを分析します。
    *   **ブロッキングプロファイリング**: ゴルーチンが同期プリミティブ（ミューテックス、チャネルなど）によってブロックされている時間を分析します。
*   **正規表現 (Regular Expression)**: テスト名やベンチマーク名をパターンマッチングするために使用されます。特定の文字列パターンに一致するテストのみを実行する際に便利です。

## 技術的詳細

このコミットは、`src/cmd/go/doc.go`ファイル内の`go test`コマンドのフラグに関するドキュメントを大幅に修正しています。主要な変更点は以下の通りです。

1.  **フラグ名のプレフィックス削除**:
    *   以前のドキュメントでは、`go test`コマンドに渡すフラグの多くが`-test.v`、`-test.run`、`-test.bench`のように`-test.`プレフィックスを持っていました。
    *   このコミットでは、`go test`コマンドに直接渡す際のフラグ名からこの`-test.`プレフィックスが削除され、`-v`、`-run`、`-bench`のように簡潔な表記に変更されました。
    *   ただし、生成されたテストバイナリを`go test -c`でビルドし、直接実行する場合には、引き続き`-test.`プレフィックスが必要である旨が明記されています（例: `-test.run=TestMyFunc`）。これは、`go test`コマンドが内部的にフラグを処理し、テストバイナリに渡す際にプレフィックスを付与する仕組みになっているためです。

2.  **新しいフラグの説明の追加と既存フラグの詳細化**:
    *   `-benchtime t`: ベンチマークの実行時間を指定するフラグが追加されました。これにより、ユーザーはベンチマークが指定された時間（例: `1h30s`）実行されるまで繰り返されるように設定できます。デフォルトは1秒です。
    *   `-blockprofile block.out` と `-blockprofilerate n`: ゴルーチンのブロッキングプロファイルに関するフラグが追加されました。これにより、ユーザーはゴルーチンがブロックされている状況を分析し、並行処理のボトルネックを特定できます。`blockprofilerate`は、プロファイルの詳細度を制御します。
    *   `-cpu 1,2,4`: `GOMAXPROCS`の値を指定してテストやベンチマークを実行できるフラグが追加されました。これにより、異なるCPUコア数でのパフォーマンスを比較分析することが可能になります。
    *   `-memprofile mem.out` と `-memprofilerate n`: メモリプロファイルに関する説明が更新され、より詳細な情報が提供されています。特に、`memprofilerate=1`を設定することで、すべてのメモリ割り当てをプロファイルできることが明記されました。
    *   `-parallel n`: 並列テスト実行に関するフラグの説明が更新され、`t.Parallel`を呼び出すテスト関数の同時実行数を制御できることが明確化されました。
    *   `-run regexp`: 特定のテストやサンプルのみを実行するための正規表現パターンを指定するフラグです。
    *   `-short`: 長時間実行されるテストを短縮するためのフラグです。
    *   `-timeout t`: テストが指定された時間より長く実行された場合にパニックを起こすフラグです。
    *   `-v`: 詳細な出力を表示するフラグです。

3.  **ドキュメントの構成変更**:
    *   フラグの説明の順序が変更され、より論理的なグループ分けがなされています。例えば、プロファイリング関連のフラグがまとまって配置されています。
    *   各フラグの説明文も、より明確で簡潔になるように修正されています。

これらの変更により、`go test`コマンドのドキュメントは、より正確で包括的になり、ユーザーがテストやベンチマーク、プロファイリング機能を効果的に活用するための情報が充実しました。

## コアとなるコードの変更箇所

```diff
--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -679,31 +679,47 @@ Description of testing flags
 The 'go test' command takes both flags that apply to 'go test' itself
 and flags that apply to the resulting test binary.
 
-The test binary, called pkg.test, where pkg is the name of the
-directory containing the package sources, has its own flags:\n+The following flags are recognized by the 'go test' command and\n+control the execution of any test:\n \n-\t-test.v\n-\t    Verbose output: log all tests as they are run.\n-\n-\t-test.run pattern
-\t    Run only those tests and examples matching the regular
-\t    expression.\n-\n-\t-test.bench pattern
+\t-bench regexp
 \t    Run benchmarks matching the regular expression.\n-\t    By default, no benchmarks run.\n+\t    By default, no benchmarks run. To run all benchmarks,\n+\t    use '-bench .' or '-bench=.'.\n \n-\t-test.benchmem
+\t-benchmem
 \t    Print memory allocation statistics for benchmarks.\n \n-\t-test.cpuprofile cpu.out
+\t-benchtime t
+\t\tRun enough iterations of each benchmark to take t, specified\n+\t\tas a time.Duration (for example, -benchtime 1h30s).\n+\t\tThe default is 1 second (1s).\n+\n+\t-blockprofile block.out
+\t    Write a goroutine blocking profile to the specified file\n+\t    when all tests are complete.\n+\n+\t-blockprofilerate n
+\t    Control the detail provided in goroutine blocking profiles by setting\n+\t    runtime.BlockProfileRate to n.  See 'godoc runtime BlockProfileRate'.\n+\t    The profiler aims to sample, on average, one blocking event every\n+\t    n nanoseconds the program spends blocked.  By default,\n+\t    if -test.blockprofile is set without this flag, all blocking events\n+\t    are recorded, equivalent to -test.blockprofilerate=1.\n+\n+\t-cpu 1,2,4
+\t    Specify a list of GOMAXPROCS values for which the tests or\n+\t    benchmarks should be executed.  The default is the current value\n+\t    of GOMAXPROCS.\n+\n+\t-cpuprofile cpu.out
 \t    Write a CPU profile to the specified file before exiting.\n \n-\t-test.memprofile mem.out
+\t-memprofile mem.out
 \t    Write a memory profile to the specified file when all tests\n \t    are complete.\n \n-\t-test.memprofilerate n
+\t-memprofilerate n
 \t    Enable more precise (and expensive) memory profiles by setting\n \t    runtime.MemProfileRate.  See 'godoc runtime MemProfileRate'.\n \t    To profile all memory allocations, use -test.memprofilerate=1\n@@ -711,44 +727,35 @@ directory containing the package sources, has its own flags:\n \t    garbage collector, provided the test can run in the available\n \t    memory without garbage collection.\n \n-\t-test.blockprofile block.out
-\t    Write a goroutine blocking profile to the specified file\n-\t    when all tests are complete.\n-\n-\t-test.blockprofilerate n
-\t    Control the detail provided in goroutine blocking profiles by setting\n-\t    runtime.BlockProfileRate to n.  See 'godoc runtime BlockProfileRate'.\n-\t    The profiler aims to sample, on average, one blocking event every\n-\t    n nanoseconds the program spends blocked.  By default,\n-\t    if -test.blockprofile is set without this flag, all blocking events\n-\t    are recorded, equivalent to -test.blockprofilerate=1.\n-\n-\t-test.parallel n
+\t-parallel n
 \t    Allow parallel execution of test functions that call t.Parallel.\n \t    The value of this flag is the maximum number of tests to run\n \t    simultaneously; by default, it is set to the value of GOMAXPROCS.\n \n-\t-test.short
+\t-run regexp
+\t    Run only those tests and examples matching the regular\n+\t    expression.\n+\n+\t-short
 \t    Tell long-running tests to shorten their run time.\n \t    It is off by default but set during all.bash so that installing\n \t    the Go tree can run a sanity check but not spend time running\n \t    exhaustive tests.\n \n-\t-test.timeout t
+\t-timeout t
 \t\tIf a test runs longer than t, panic.\n \n-\t-test.benchtime t
-\t\tRun enough iterations of each benchmark to take t.\n-\t\tThe default is 1 second.\n+\t-v
+\t    Verbose output: log all tests as they are run.\n \n-\t-test.cpu 1,2,4
-\t    Specify a list of GOMAXPROCS values for which the tests or\n-\t    benchmarks should be executed.  The default is the current value\n-\t    of GOMAXPROCS.\n+The test binary, called pkg.test where pkg is the name of the\n+directory containing the package sources, can be invoked directly\n+after building it with 'go test -c'. When invoking the test binary\n+directly, each of the standard flag names must be prefixed with 'test.',\n+as in -test.run=TestMyFunc or -test.v.\n \n-For convenience, each of these -test.X flags of the test binary is\n-also available as the flag -X in 'go test' itself.  Flags not listed\n-here are passed through unaltered.  For instance, the command\n+When running 'go test', flags not listed above are passed through\n+unaltered. For instance, the command\n \n \tgo test -x -v -cpuprofile=prof.out -dir=testdata -update\n \n```

## コアとなるコードの解説

上記の差分は、`src/cmd/go/doc.go`ファイル内の`go test`コマンドのドキュメントセクションに対する変更を示しています。

*   **行 682-683 の変更**:
    *   変更前: "The test binary, called pkg.test, where pkg is the name of the directory containing the package sources, has its own flags:"
    *   変更後: "The following flags are recognized by the 'go test' command and control the execution of any test:"
    *   この変更は、ドキュメントの焦点を「テストバイナリのフラグ」から「`go test`コマンドが認識するフラグ」へとシフトさせています。これにより、ユーザーが`go test`コマンドに直接渡すフラグについて説明していることが明確になります。

*   **フラグ名の変更（`-test.`プレフィックスの削除）**:
    *   `-test.v` が `-v` に
    *   `-test.run pattern` が `-run regexp` に
    *   `-test.bench pattern` が `-bench regexp` に
    *   `-test.benchmem` が `-benchmem` に
    *   `-test.cpuprofile cpu.out` が `-cpuprofile cpu.out` に
    *   `-test.memprofile mem.out` が `-memprofile mem.out` に
    *   `-test.memprofilerate n` が `-memprofilerate n` に
    *   `-test.parallel n` が `-parallel n` に
    *   `-test.short` が `-short` に
    *   `-test.timeout t` が `-timeout t` に
    *   これらの変更は、`go test`コマンドに直接渡す際に`-test.`プレフィックスが不要になったことを反映しています。これにより、コマンドラインでの入力が簡潔になります。

*   **新しいフラグの追加と説明の更新**:
    *   `-benchtime t`、`-blockprofile block.out`、`-blockprofilerate n`、`-cpu 1,2,4` といった新しいフラグの説明が追加されています。これらは、ベンチマークの実行時間制御、ゴルーチンのブロッキングプロファイリング、および異なる`GOMAXPROCS`値でのテスト実行を可能にするためのものです。
    *   既存のフラグの説明も、より詳細で分かりやすくなるように修正されています。例えば、`-bench`フラグの説明には、すべてのベンチマークを実行するための例（`-bench .`または`-bench=.`）が追加されています。

*   **テストバイナリの直接実行に関する説明の追加**:
    *   変更後: "The test binary, called pkg.test where pkg is the name of the directory containing the package sources, can be invoked directly after building it with 'go test -c'. When invoking the test binary directly, each of the standard flag names must be prefixed with 'test.', as in -test.run=TestMyFunc or -test.v."
    *   この新しい段落は、`go test -c`でビルドされたテストバイナリを直接実行する場合に、フラグに引き続き`-test.`プレフィックスが必要であることを明確に説明しています。これは、`go test`コマンドがフラグを処理する際の内部的な挙動と、テストバイナリが直接フラグを解釈する際の挙動の違いをユーザーに伝えるために重要です。

*   **フラグのパススルーに関する説明の更新**:
    *   変更前: "For convenience, each of these -test.X flags of the test binary is also available as the flag -X in 'go test' itself. Flags not listed here are passed through unaltered."
    *   変更後: "When running 'go test', flags not listed above are passed through unaltered. For instance, the command..."
    *   この変更は、`go test`コマンドが認識しないフラグは、変更されずにテストバイナリに渡されるという挙動をより簡潔に説明しています。

全体として、このコミットは`go test`コマンドのドキュメントを大幅に改善し、ユーザーがテストフラグをより正確かつ効果的に使用できるようにするためのものです。

## 関連リンク

*   Go Gerrit Change-ID: [https://golang.org/cl/7279047](https://golang.org/cl/7279047)

## 参考にした情報源リンク

*   Go Command Documentation: `go test` (現在の最新ドキュメント)
    *   [https://pkg.go.dev/cmd/go#hdr-Test_packages](https://pkg.go.dev/cmd/go#hdr-Test_packages)
*   Go `runtime`パッケージのドキュメント (プロファイリング関連)
    *   [https://pkg.go.dev/runtime#BlockProfileRate](https://pkg.go.dev/runtime#BlockProfileRate)
    *   [https://pkg.go.dev/runtime#MemProfileRate](https://pkg.go.dev/runtime#MemProfileRate)
*   Go `testing`パッケージのドキュメント
    *   [https://pkg.go.dev/testing](https://pkg.go.dev/testing)
*   Go `time`パッケージのドキュメント (Durationの形式)
    *   [https://pkg.go.dev/time#ParseDuration](https://pkg.go.dev/time#ParseDuration)
*   Go `regexp`パッケージのドキュメント (正規表現の構文)
    *   [https://pkg.go.dev/regexp](https://pkg.go.dev/regexp)
*   Go `GOMAXPROCS`に関する情報
    *   [https://go.dev/doc/effective_go#concurrency](https://go.dev/doc/effective_go#concurrency)
    *   [https://pkg.go.dev/runtime#GOMAXPROCS](https://pkg.go.dev/runtime#GOMAXPROCS)