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

このコミットは、Go言語の公式リポジトリにおけるgo runコマンドのドキュメントを、現在の実際の挙動に合わせて更新するものです。具体的には、go runコマンドがファイル名を指定せずに実行された場合に、すべての非テストGoソースファイルをコンパイルして実行するという記述が削除されています。これは、go runの実際の動作がその記述と異なっていたため、ドキュメントの正確性を保つための修正です。

コミット

commit 70f3b6097bb3c083f39c313fba3889d4e39ef680
Author: Dominik Honnef <dominik.honnef@gmail.com>
Date:   Sat May 18 19:22:30 2013 +0800

    cmd/go: Update documentation of go run to match current behaviour.
    
    Fixes #5511.
    
    R=golang-dev, minux.ma
    CC=golang-dev
    https://golang.org/cl/9530043

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

https://github.com/golang/go/commit/70f3b6097bb3c083f39c313fba3889d4e39ef680

元コミット内容

cmd/go: Update documentation of go run to match current behaviour.

Fixes #5511.

R=golang-dev, minux.ma
CC=golang-dev
https://golang.org/cl/9530043

変更の背景

この変更は、Go言語のIssueトラッカーで報告されたIssue #5511に対応するものです。Issue #5511では、go runコマンドのドキュメントに「ファイル名が指定されていない場合、すべての非テストGoソースファイルをコンパイルして実行する」という記述があるにもかかわらず、実際のgo runの挙動がその通りではないことが指摘されました。

具体的には、go runは常に明示的に指定されたGoソースファイル（または単一のパッケージ）をコンパイルして実行することを意図しており、引数なしで実行された場合にカレントディレクトリ内のすべてのGoファイルを自動的に見つけて実行するような動作はしません。もし引数なしで実行しようとすると、通常は「no Go files listed」といったエラーが発生します。

このドキュメントと実際の挙動の不一致がユーザーの混乱を招く可能性があったため、ドキュメントを修正し、go runの正確な動作を反映させることが必要とされました。

前提知識の解説

go runコマンド: go runはGo言語のツールチェインの一部であり、Goのソースファイルをコンパイルして実行するためのコマンドです。通常、開発中に単一のGoプログラムを素早くテストしたり実行したりする際に使用されます。このコマンドは、内部的に一時ディレクトリに実行可能ファイルをビルドし、その後その実行可能ファイルを起動します。
Goのパッケージとメインパッケージ: Goのプログラムはパッケージに分割されます。実行可能なプログラムは、main関数を含むmainパッケージを持つ必要があります。go runは、指定されたソースファイルがmainパッケージに属していることを期待します。
Goのビルドフラグ: go runコマンドは、go buildコマンドと同様に、コンパイル時の挙動を制御するためのビルドフラグ（例: -tags, -ldflagsなど）を受け入れます。
ドキュメンテーションの重要性: ソフトウェアのドキュメンテーションは、ユーザーがツールやライブラリを正しく理解し、効果的に使用するために不可欠です。ドキュメントが実際の挙動と異なる場合、ユーザーは誤解し、予期せぬ問題に直面する可能性があります。
Goのソースコード構造: Goのツールチェインのソースコードは、src/cmd/goディレクトリ以下にgoコマンドの実装が含まれています。doc.goファイルはGoコマンド全体のドキュメントを定義し、run.goファイルはgo runコマンドの具体的な実装と、そのコマンド固有の短いドキュメントを含んでいます。

技術的詳細

このコミットの技術的な詳細は、ドキュメントの正確性を確保するために、冗長または誤解を招く可能性のある記述を削除することにあります。

変更前は、src/cmd/go/doc.goとsrc/cmd/go/run.goの両方に、go runコマンドの説明として以下の行が含まれていました。

If no files are named, it compiles and runs all non-test Go source files.

この記述は、go runが引数なしで実行された場合に、カレントディレクトリ内のすべてのGoソースファイル（テストファイルを除く）を自動的に見つけて実行するという誤った印象を与えていました。しかし、go runの実際の動作は、常に明示的に指定されたGoファイル（または単一のパッケージ）を対象とします。引数なしでgo runを実行すると、Goツールはどのファイルをコンパイルして実行すべきか判断できず、エラーを返します。

このコミットでは、上記の誤解を招く記述を両方のファイルから削除することで、go runのドキュメントが実際の挙動と一致するように修正されました。これにより、ユーザーはgo runコマンドの正しい使用方法を理解しやすくなります。

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

このコミットでは、以下の2つのファイルからそれぞれ1行ずつ削除が行われています。

src/cmd/go/doc.go
src/cmd/go/run.go

それぞれの変更は以下の通りです。

diff --git a/src/cmd/go/doc.go b/src/cmd/go/doc.go
index df82ab45b0..ddf7263abb 100644
--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -370,7 +370,6 @@ Usage:
 	go run [build flags] gofiles... [arguments...]
 
 Run compiles and runs the main package comprising the named Go source files.
-If no files are named, it compiles and runs all non-test Go source files.
 
 For more about build flags, see 'go help build'.
 
diff --git a/src/cmd/go/run.go b/src/cmd/go/run.go
index 91bdc1be2a..b505693635 100644
--- a/src/cmd/go/run.go
+++ b/src/cmd/go/run.go
@@ -16,7 +16,6 @@ var cmdRun = &Command{
 	Short:     "compile and run Go program",
 	Long: `
 Run compiles and runs the main package comprising the named Go source files.
-If no files are named, it compiles and runs all non-test Go source files.
 
 For more about build flags, see 'go help build'.

コアとなるコードの解説

削除された行は、go runコマンドのLong説明の一部でした。

src/cmd/go/doc.go: このファイルは、go helpコマンドで表示されるGoコマンド全体の包括的なドキュメントを生成するために使用されます。go runに関するセクションも含まれており、そこから誤った記述が削除されました。
src/cmd/go/run.go: このファイルは、go runコマンド自体の実装と、そのコマンド固有の短い説明（Shortフィールド）および詳細な説明（Longフィールド）を含んでいます。Longフィールドから、同様に誤った記述が削除されました。

これらの変更は、コードの機能的な動作には影響を与えません。これは純粋にドキュメンテーションの修正であり、ユーザーがgo runコマンドの正しい挙動を理解できるようにするためのものです。この修正により、go runのドキュメントは、常にファイル名を指定する必要があるという実際の要件を正確に反映するようになりました。

参考にした情報源リンク

Go Issue #5511: go run documentation is misleading: https://github.com/golang/go/issues/5511
Go Command Documentation (現在のgo runのドキュメントの挙動を確認するため): https://pkg.go.dev/cmd/go (またはgo help runコマンドの出力)
Go言語のソースコード構造に関する一般的な知識

comemo