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

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

このコミットは、Go言語のコマンドラインツール go における run および test サブコマンドに新たに追加された -exec フラグに関するドキュメントの追加と修正を目的としています。具体的には、go run および go test がどのようにコンパイルされたバイナリを実行するか、そして -exec フラグがその挙動にどのように影響するかについて、ユーザー向けのヘルプドキュメントを更新しています。

コミット

commit 280d46b03be642fbbb817332069d6b337774746e
Author: Russ Cox <rsc@golang.org>
Date:   Tue Feb 25 10:22:27 2014 -0500

    cmd/go: document new -exec flag on run/test
    
    The new flag was added by CL 68150047 (part of the NaCl replay),
    but the change, like the original, omitted documentation of the
    new behavior.
    
    LGTM=r
    R=r
    CC=golang-codereviews
    https://golang.org/cl/68580043

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

https://github.com/golang/go/commit/280d46b03be642fbbb817332069d6b337774746e

元コミット内容

このコミット自体は、go run および go test コマンドのヘルプメッセージと doc/go1.3.txt に、-exec フラグに関する説明を追加するものです。

変更の背景

このコミットの背景には、go run および go test コマンドに -exec フラグが既に追加されていたにもかかわらず、その機能が公式ドキュメントに記載されていなかったという問題があります。コミットメッセージによると、この新しいフラグは CL 68150047 (NaCl replay の一部) によって追加されましたが、その変更には新しい挙動に関するドキュメントが含まれていませんでした。

Go言語のツールチェインは、クロスコンパイルされたバイナリの実行をサポートするために、特定の環境でシミュレータやエミュレータを介して実行する必要がある場合があります。例えば、GOOS や GOARCH がシステムのデフォルトと異なる場合、go run はコンパイルされたバイナリを直接実行するのではなく、go_$GOOS_$GOARCH_exec という名前のプログラムを検索し、それを使用してバイナリを実行する仕組みを持っています。この仕組みは、特にGoogle Native Client (NaCl) のようなサンドボックス環境や、異なるアーキテクチャ向けのクロスコンパイルされたバイナリを開発マシン上でテストする際に重要となります。

-exec フラグは、この自動的な実行メカニズムをユーザーが明示的に制御できるようにするために導入されました。しかし、この重要な機能がドキュメント化されていなかったため、ユーザーがその存在や使い方を知ることができませんでした。このコミットは、そのドキュメントの欠落を補完し、ユーザーがこの機能を適切に利用できるようにすることを目的としています。

前提知識の解説

このコミットを理解するためには、以下の前提知識が役立ちます。

  • Go言語のビルドシステム: Go言語は、go build コマンドを使用してソースコードをコンパイルし、実行可能なバイナリを生成します。go run は、ソースファイルをコンパイルして一時的なバイナリを作成し、それをすぐに実行するコマンドです。go test は、テストコードをコンパイルしてテストバイナリを作成し、それを実行してテストを実行するコマンドです。
  • クロスコンパイル: Go言語は、異なるオペレーティングシステム (GOOS) やアーキテクチャ (GOARCH) 向けのバイナリを生成するクロスコンパイルをサポートしています。例えば、Linux上でWindows向けのバイナリをビルドすることができます。
  • 実行環境: コンパイルされたバイナリは、通常、直接実行されます。しかし、クロスコンパイルされたバイナリの場合、ターゲット環境が現在の実行環境と異なるため、直接実行できないことがあります。このような場合、シミュレータ、エミュレータ、または特定の実行ラッパープログラムが必要になります。
  • Google Native Client (NaCl): NaClは、ウェブブラウザ内でネイティブコードを安全に実行するための技術です。Go言語はNaCl向けのクロスコンパイルをサポートしており、NaCl環境でGoプログラムを実行するためには、特定の実行メカニズムが必要となります。
  • go help コマンド: Go言語のコマンドラインツールは、各サブコマンドの詳細なヘルプメッセージを提供します。go help <command> を実行することで、そのコマンドのオプションや使用方法を確認できます。このコミットは、このヘルプメッセージを更新するものです。
  • Change List (CL): Goプロジェクトでは、変更は "Change List" (CL) として提出され、レビューされます。コミットメッセージに記載されている CL 68150047 や CL 68580043 は、Goのコードレビューシステムにおける特定の変更セットを指します。

技術的詳細

このコミットの技術的な詳細は、主に go コマンドのドキュメント生成部分と、run および test サブコマンドの内部ロジックに関連しています。

  1. doc/go1.3.txt の更新:

    • doc/go1.3.txt は、Go 1.3 リリースにおける主要な変更点をまとめたドキュメントです。このファイルに cmd/go: add -exec to 'go run' and 'go test' (CL 68580043) という行が追加され、-exec フラグの導入が公式に記録されました。これは、ユーザーがGo 1.3の新機能としてこのフラグを認識できるようにするための重要な変更です。

  2. src/cmd/go/doc.go の更新:

    • src/cmd/go/doc.go は、go help コマンドで表示されるGoコマンド全体のヘルプメッセージを定義しているファイルです。
    • go run の使用法 (UsageLine) に [-exec xprog] が追加され、-exec フラグが利用可能であることが明示されました。
    • go run の詳細な説明 (Long フィールド) に、-exec フラグの挙動に関する新しい段落が追加されました。
      • デフォルトでは go run はコンパイルされたバイナリを直接実行すること (a.out arguments...)。
      • -exec フラグが指定された場合、xprog を使用してバイナリを実行すること (xprog a.out arguments...)。
      • -exec フラグが指定されず、GOOS または GOARCH がシステムのデフォルトと異なる場合、go_$GOOS_$GOARCH_exec という名前のプログラムが現在の検索パスから見つかれば、それを使用してバイナリを実行すること（例: go_nacl_386_exec a.out arguments...）。これは、クロスコンパイルされたプログラムをシミュレータや他の実行方法で実行できるようにするためのものです。
    • src/cmd/go/doc.go の go test のセクションにも、-exec xprog フラグの説明が追加されました。これは go run と同様の挙動を持つことが明記されています。
    • また、src/cmd/go/doc.go の go build のセクションで、CgoやSWIGを使用する際のファイル処理に関する説明が微修正されています。具体的には、.m ファイル（Objective-Cソースファイル）がCコンパイラに渡されるという記述が削除されています。これは、Go 1.3でObjective-Cのサポートが変更されたか、より正確な記述に修正されたことを示唆しています。

  3. src/cmd/go/run.go および src/cmd/go/test.go の更新:

    • これらのファイルは、それぞれ go run および go test サブコマンドの実際のロジックを実装しています。
    • cmdRun および cmdTest の UsageLine フィールドが更新され、-exec xprog オプションが追加されました。これは、go help run や go help test を実行した際に表示される簡潔な使用法メッセージに反映されます。
    • cmdRun の Long フィールドに、go run の -exec フラグに関する詳細な説明が追加されました。これは src/cmd/go/doc.go で追加された内容と重複しており、各コマンドのヘルプメッセージが独立して完全な情報を持つようにするためのものです。
    • cmdTest の Long フィールドにも、go test の -exec フラグに関する説明が追加されました。

これらの変更は、Goコマンドのユーザーインターフェースとドキュメントの一貫性を保ち、新しい機能の利用を促進するために重要です。特に、クロスコンパイル環境での開発者にとって、-exec フラグはデバッグやテストのワークフローを大幅に改善する可能性があります。

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

このコミットにおけるコアとなるコードの変更箇所は以下のファイルに集中しています。

  • doc/go1.3.txt: Go 1.3 リリースノートの更新。
  • src/cmd/go/doc.go: go help コマンドの全体的なドキュメント。特に go run と go test のセクション。
  • src/cmd/go/run.go: go run コマンドの定義とヘルプメッセージ。
  • src/cmd/go/test.go: go test コマンドの定義とヘルプメッセージ。

具体的な変更は、主に文字列リテラル（ヘルプメッセージのテキスト）の追加と修正です。

コアとなるコードの解説

doc/go1.3.txt

--- a/doc/go1.3.txt
+++ b/doc/go1.3.txt
@@ -10,3 +10,4 @@ cmd/go, go/build: support .m files (CL 60590044)
 unicode: upgrade from Unicode 6.2.0 to 6.3.0 (CL 65400044)
 runtime/debug: add SetPanicOnFault (CL 66590044)
 crypto/tls: ServerName or InsecureSkipVerify (CL 67010043)
+cmd/go: add -exec to 'go run' and 'go test' (CL 68580043)

この変更は、Go 1.3のリリースノートに、go run および go test に -exec フラグが追加されたことを示す行を追加しています。これは、この機能がGo 1.3の一部として公式にリリースされたことをユーザーに伝えるためのものです。

src/cmd/go/doc.go

--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -303,6 +303,7 @@ which calls strings.Join. The struct being passed to the template is:\n         IgnoredGoFiles []string // .go sources ignored due to build constraints\n         CFiles   []string       // .c source files\n         CXXFiles []string       // .cc, .cxx and .cpp source files\n+        MFiles   []string       // .m source files\n         HFiles   []string       // .h, .hh, hpp and .hxx source files\n         SFiles   []string       // .s source files\n         SwigFiles []string      // .swig files\n@@ -357,11 +358,20 @@ Compile and run Go program\n \n Usage:\n \n-\tgo run [build flags] gofiles... [arguments...]\n+\tgo run [build flags] [-exec xprog] gofiles... [arguments...]\n \n Run compiles and runs the main package comprising the named Go source files.\n A Go source file is defined to be a file ending in a literal \".go\" suffix.\n \n+By default, 'go run' runs the compiled binary directly: 'a.out arguments...'.\n+If the -exec flag is given, 'go run' invokes the binary using xprog: 'xprog a.out arguments...'.\n+If the -exec flag is not given, GOOS or GOARCH is different from the system\n+default, and a program named go_$GOOS_$GOARCH_exec can be found\n+on the current search path, 'go run' invokes the binary using that program,\n+for example 'go_nacl_386_exec a.out arguments...'. This allows execution of\n+cross-compiled programs when a simulator or other execution method is\n+available.\n+\n For more about build flags, see 'go help build'.\n \n See also: go build.\n@@ -408,6 +418,10 @@ In addition to the build flags, the flags handled by 'go test' itself are:\n \t    Install packages that are dependencies of the test.\n \t    Do not run the test.\n \n+\t-exec xprog\n+\t    Run the test binary using xprog. The behavior is the same as\n+\t    in 'go run'. See 'go help run' for details.\n+\n The test binary also accepts flags that control execution of the test; these\n flags are also accessible by 'go test'.  See 'go help testflag' for details.\n \n@@ -478,8 +492,8 @@ http://swig.org/.  When running go build, any file with a .swig\n extension will be passed to SWIG.  Any file with a .swigcxx extension\n will be passed to SWIG with the -c++ option.\n \n-When either cgo or SWIG is used, go build will pass any .c, .m, .s,\n-or .S files to the C compiler, and any .cc, .cpp, .cxx files to the C++\n+When either cgo or SWIG is used, go build will pass any .c, .s, or .S\n+files to the C compiler, and any .cc, .cpp, .cxx files to the C++\n compiler.  The CC or CXX environment variables may be set to determine\n the C or C++ compiler, respectively, to use.\n \n@@ -823,9 +837,7 @@ control the execution of any test:\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-\t    and set the environment variable GOGC=off to disable the\n-\t    garbage collector, provided the test can run in the available\n-\t    memory without garbage collection.\n+\t    and pass --alloc_space flag to the pprof tool.\n \n \t-outputdir directory\n \t    Place output files from profiling in the specified directory,\n```
このファイルは `go help` コマンドの出力内容を定義しており、このコミットの主要な変更点が含まれています。
*   `go run` の `Usage` と `Long` 説明に `-exec xprog` が追加され、その詳細な挙動（デフォルトの実行、`-exec` 指定時の挙動、クロスコンパイル時の自動検出）が説明されています。
*   `go test` のセクションにも同様に `-exec xprog` の説明が追加され、`go run` と同じ挙動であることが示されています。
*   Cgo/SWIG関連の記述から `.m` ファイルの言及が削除されています。これはObjective-Cのサポートに関する変更か、より正確な記述への修正です。
*   メモリプロファイリングに関する説明も微修正され、`GOGC=off` の代わりに `pprof` ツールへの `--alloc_space` フラグの利用が推奨されています。

### `src/cmd/go/run.go`

```diff
--- a/src/cmd/go/run.go
+++ b/src/cmd/go/run.go
@@ -30,12 +30,21 @@ func findExecCmd() []string {\n }\n \n var cmdRun = &Command{\n-\tUsageLine: "run [build flags] gofiles... [arguments...]",\n+\tUsageLine: "run [build flags] [-exec xprog] gofiles... [arguments...]",\n \tShort:     "compile and run Go program",\n \tLong: `\n Run compiles and runs the main package comprising the named Go source files.\n A Go source file is defined to be a file ending in a literal ".go" suffix.\n \n+By default, 'go run' runs the compiled binary directly: 'a.out arguments...'.\n+If the -exec flag is given, 'go run' invokes the binary using xprog: 'xprog a.out arguments...'.\n+If the -exec flag is not given, GOOS or GOARCH is different from the system\n+default, and a program named go_$GOOS_$GOARCH_exec can be found\n+on the current search path, 'go run' invokes the binary using that program,\n+for example 'go_nacl_386_exec a.out arguments...'. This allows execution of\n+cross-compiled programs when a simulator or other execution method is\n+available.\n+\n For more about build flags, see 'go help build'.\n \n See also: go build.\n```
このファイルは `go run` コマンドの定義を含んでいます。`UsageLine` と `Long` フィールドが更新され、`go help run` を実行した際に表示されるヘルプメッセージに `-exec` フラグに関する情報が追加されています。これは `src/cmd/go/doc.go` の内容と同期しており、各コマンドのヘルプが独立して完全な情報を持つようにしています。

### `src/cmd/go/test.go`

```diff
--- a/src/cmd/go/test.go
+++ b/src/cmd/go/test.go
@@ -72,6 +72,10 @@ In addition to the build flags, the flags handled by 'go test' itself are:\n \t    Install packages that are dependencies of the test.\n \t    Do not run the test.\n \n+\t-exec xprog\n+\t    Run the test binary using xprog. The behavior is the same as\n+\t    in 'go run'. See 'go help run' for details.\n+\n The test binary also accepts flags that control execution of the test; these\n flags are also accessible by 'go test'.  See 'go help testflag' for details.\n \n```
このファイルは `go test` コマンドの定義を含んでいます。`Long` フィールドが更新され、`go help test` を実行した際に表示されるヘルプメッセージに `-exec` フラグに関する情報が追加されています。ここでも `go run` と同様の挙動であることが明記されています。

これらの変更は、Goコマンドのユーザーエクスペリエンスを向上させ、新しい機能の発見と利用を容易にするための重要なドキュメントの更新です。

## 関連リンク

*   Go言語公式ドキュメント: [https://go.dev/doc/](https://go.dev/doc/)
*   Goコマンドリファレンス: [https://go.dev/cmd/go/](https://go.dev/cmd/go/)
*   Go 1.3 リリースノート (このコミットが反映されているバージョン): [https://go.dev/doc/go1.3](https://go.dev/doc/go1.3)

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

*   Go言語のソースコード (GitHub): [https://github.com/golang/go](https://github.com/golang/go)
*   Goのコードレビューシステム (Gerrit): [https://go.dev/cl/](https://go.dev/cl/) (コミットメッセージに記載されているCL番号を検索することで、関連する変更履歴や議論を確認できます。)
*   Google Native Client (NaCl) (Go言語との関連性について): [https://developer.chrome.com/docs/native-client/](https://developer.chrome.com/docs/native-client/) (現在は非推奨ですが、当時の背景を理解する上で参考になります。)
*   `go run` コマンドの挙動に関する議論 (Stack Overflowなど): `go run` の `-exec` フラグやクロスコンパイル時の挙動について、より深い理解を得るために、コミュニティの議論や質問が参考になる場合があります。