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

このコミットは、Go言語のコマンドラインツール go のドキュメント、特に go run と go test コマンドにおけるフラグの扱いに関する説明を改善するものです。テストバイナリに渡すフラグの指定方法について、より明確なガイダンスを提供することを目的としています。

コミット

commit 59fb90ac85be4c2c024d84287e03c200ef4fa24e
Author: Rob Pike <r@golang.org>
Date:   Mon Jun 3 16:39:42 2013 -0400

    cmd/go: document flag passing for tests
    Fixes #5566.
    
    R=rsc
    CC=gobot, golang-dev
    https://golang.org/cl/9882043

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

https://github.com/golang/go/commit/59fb90ac85be4c2c024d84287e03c200ef4fa24e

元コミット内容

cmd/go: document flag passing for tests Fixes #5566.

このコミットは、go コマンドがテストバイナリにフラグを渡す方法に関するドキュメントを修正するものです。具体的には、Go issue 5566で報告された問題に対応しています。

変更の背景

Go言語の go test コマンドは、テストの実行を自動化するための強力なツールです。しかし、テストバイナリ自体に特定のフラグ（例えば、テストの実行方法を制御するカスタムフラグや、テスト対象のアプリケーションが使用する設定フラグなど）を渡したい場合、その構文がユーザーにとって直感的ではないという問題がありました。

Go issue 5566（"cmd/go: document flag passing for tests"）では、この点が明確に指摘されていました。ユーザーは go test コマンドに渡すフラグと、その後にテストバイナリに渡されるフラグの区別がつきにくいと感じていました。特に、go test コマンド自身が認識しないフラグがどのように扱われるかについて、ドキュメントが不足していました。

このコミットは、この混乱を解消し、ユーザーがテストバイナリに意図した通りにフラグを渡せるように、公式ドキュメントを改善することを目的としています。

前提知識の解説

go test コマンド: Go言語の標準テストツール。パッケージ内のテスト関数（TestXxx、BenchmarkXxx、ExampleXxx）を実行します。
テストバイナリ: go test コマンドがテストを実行するために内部的にビルドする実行可能ファイル。このバイナリは、テストコードと、テストに必要な依存関係を含んでいます。
コマンドラインフラグ: プログラムの動作を制御するために、コマンドラインから渡される引数。通常、- または -- で始まります（例: -v、--timeout 10s）。
go help testflag: go test コマンドが認識するテスト関連のフラグ（例: -v (詳細出力)、-run (特定のテストを実行)、-timeout (タイムアウト設定)）に関するヘルプを表示するコマンド。
go help build: ビルドプロセスを制御するフラグ（例: -race (データ競合検出)、-tags (ビルドタグ)）に関するヘルプを表示するコマンド。
go help packages: パッケージの指定方法に関するヘルプを表示するコマンド。

このコミットの核心は、go test コマンドが自身のフラグと、テストバイナリに渡すべきフラグをどのように区別するかという点にあります。Goツールは、コマンドライン引数を解析する際に、自身が認識するフラグを先に処理します。そして、自身が認識しない - で始まる最初の引数を見つけると、それ以降のすべての引数をテストバイナリへの引数として扱います。この挙動が明示的にドキュメント化されていなかったため、ユーザーは混乱していました。

技術的詳細

このコミットは、主に src/cmd/go/doc.go と src/cmd/go/test.go のドキュメント文字列を更新することで、go test コマンドのフラグ処理に関する説明を明確にしています。

変更のポイントは以下の通りです。

go test の Usage Line の変更: go test [-c] [-i] [build flags] [packages] [flags for test binary] から go test [-c] [-i] [build and test flags] [packages] [flags for test binary] へ変更されました。これは、go test コマンド自身がビルドフラグだけでなく、テスト関連のフラグも受け取ることをより明確にするためです。
テストバイナリへのフラグ渡しに関する説明の追加: 最も重要な変更は、go test のドキュメントに以下の説明が追加されたことです。「If the test binary needs any other flags, they should be presented after the package names. The go tool treats as a flag the first argument that begins with a minus sign that it does not recognize itself; that argument and all subsequent arguments are passed as arguments to the test binary.」（もしテストバイナリが他のフラグを必要とする場合、それらはパッケージ名の後に指定されるべきです。goツールは、自身が認識しないマイナス記号で始まる最初の引数をフラグとして扱い、その引数とそれに続くすべての引数をテストバイナリへの引数として渡します。）この説明により、go test コマンドとテストバイナリへのフラグの分離ルールが明確になりました。
go run のドキュメントの修正: go run コマンドのドキュメントにも、「A Go source file is defined to be a file ending in a literal ".go" suffix.」という定義が追加されました。これは、go run がどのファイルをGoソースファイルとして認識するかを明確にするための補足的な変更です。

これらの変更は、コードの動作自体を変更するものではなく、ユーザーがGoツールをより効果的に使用できるようにするためのドキュメントの改善に焦点を当てています。

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

`src/cmd/go/doc.go`

--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -373,6 +373,7 @@ Usage:
 	go run [build flags] gofiles... [arguments...]
 
 Run compiles and runs the main package comprising the named Go source files.
+A Go source file is defined to be a file ending in a literal ".go" suffix.
 
 For more about build flags, see 'go help build'.
 
@@ -383,7 +384,7 @@ Test packages
 
 Usage:
 
-\tgo test [-c] [-i] [build flags] [packages] [flags for test binary]
+\tgo test [-c] [-i] [build and test flags] [packages] [flags for test binary]\n
 
 'Go test' automates testing the packages named by the import paths.
 It prints a summary of the test results in the format:
@@ -421,6 +422,11 @@ In addition to the build flags, the flags handled by 'go test' itself are:
 The test binary also accepts flags that control execution of the test; these
 flags are also accessible by 'go test'.  See 'go help testflag' for details.
 
+If the test binary needs any other flags, they should be presented after the
+package names. The go tool treats as a flag the first argument that begins with
+a minus sign that it does not recognize itself; that argument and all subsequent
+arguments are passed as arguments to the test binary.\n
+
 For more about build flags, see 'go help build'.
 For more about specifying packages, see 'go help packages'.

`src/cmd/go/run.go`

--- a/src/cmd/go/run.go
+++ b/src/cmd/go/run.go
@@ -16,6 +16,7 @@ var cmdRun = &Command{
 	Short:     "compile and run Go program",
 	Long: `
 Run compiles and runs the main package comprising the named Go source files.
+A Go source file is defined to be a file ending in a literal ".go" suffix.
 
 For more about build flags, see 'go help build'.

`src/cmd/go/test.go`

--- a/src/cmd/go/test.go
+++ b/src/cmd/go/test.go
@@ -32,7 +32,7 @@ func init() {
 
 var cmdTest = &Command{
 	CustomFlags: true,
-\tUsageLine:   "test [-c] [-i] [build flags] [packages] [flags for test binary]",
+\tUsageLine:   "test [-c] [-i] [build and test flags] [packages] [flags for test binary]",
 	Short:       "test packages",
 	Long: `
 'Go test' automates testing the packages named by the import paths.
@@ -71,6 +71,11 @@ In addition to the build flags, the flags handled by 'go test' itself are:
 The test binary also accepts flags that control execution of the test; these
 flags are also accessible by 'go test'.  See 'go help testflag' for details.
 
+If the test binary needs any other flags, they should be presented after the
+package names. The go tool treats as a flag the first argument that begins with
+a minus sign that it does not recognize itself; that argument and all subsequent
+arguments are passed as arguments to the test binary.\n
+
 For more about build flags, see 'go help build'.
 For more about specifying packages, see 'go help packages'.

コアとなるコードの解説

このコミットの主要な変更は、src/cmd/go/doc.go と src/cmd/go/test.go 内のドキュメント文字列（Goのコマンドラインヘルプメッセージとして表示される部分）の修正です。

src/cmd/go/doc.go: このファイルは、go help コマンドで表示される一般的なヘルプドキュメントを定義しています。
- go run のセクションに、Goソースファイルの定義（.go サフィックスを持つファイル）が追加されました。これは、go run がどのファイルを処理対象とするかを明確にするための補足です。
- go test のセクションでは、Usage: の行が更新され、[build flags] が [build and test flags] に変更されました。これにより、go test がビルド関連のフラグだけでなく、テスト固有のフラグも受け取ることを示唆しています。
- 最も重要なのは、go test のフラグに関する説明の最後に、テストバイナリにフラグを渡すための新しい段落が追加されたことです。この段落は、go ツールがどのように引数を解析し、自身が認識しない - で始まる引数をテストバイナリに渡すかを具体的に説明しています。
src/cmd/go/run.go: go run コマンドの定義ファイルです。
- cmdRun 構造体の Long フィールド（go help run で表示される詳細な説明）に、src/cmd/go/doc.go と同様にGoソースファイルの定義が追加されました。
src/cmd/go/test.go: go test コマンドの定義ファイルです。
- cmdTest 構造体の UsageLine フィールドが [build and test flags] に更新されました。これは doc.go と同様の変更です。
- cmdTest 構造体の Long フィールド（go help test で表示される詳細な説明）に、src/cmd/go/doc.go と同じテストバイナリへのフラグ渡しに関する新しい段落が追加されました。

これらの変更は、Goツールのユーザーエクスペリエンスを向上させるための、非常に重要なドキュメントの改善です。これにより、ユーザーは go test コマンドの挙動をより正確に理解し、テストバイナリにカスタムフラグを渡す際に発生する可能性のある混乱を避けることができます。

参考にした情報源リンク

Go issue 5566 の内容
Go言語の公式ドキュメント (go help test および go help run の出力)
Go言語のソースコード (src/cmd/go/doc.go, src/cmd/go/run.go, src/cmd/go/test.go)
Go言語のコマンドラインツールの一般的な挙動に関する知識

comemo