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

このコミットは、Go言語の公式ドキュメントの一部である doc/reference-cmd.html ファイルに対する更新です。具体的には、Goコマンドラインツールの使用方法に関する導入部分が大幅に改訂され、go コマンド、go cmd (サブコマンド形式)、および go tool cmd (ツール形式) の違いが明確に説明されています。これにより、ユーザーがGoのコマンドラインエコシステムをより正確に理解できるようになります。

コミット

commit b73046407fc284a9cf8dcd4b68ffedce16234e4c
Author: Rob Pike <r@golang.org>
Date:   Sat Mar 24 09:29:08 2012 +1100

    doc/reference-cmd.html: new introduction
    Compare and explain go, go cmd, and go tool cmd.
    The situation is not concisely explained elsewhere in the main docs.
    
    R=golang-dev, bradfitz
    CC=golang-dev
    https://golang.org/cl/5906043

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

https://github.com/golang/go/commit/b73046407fc284a9cf8dcd4b68ffedce16234e4c

元コミット内容

doc/reference-cmd.html: new introduction Compare and explain go, go cmd, and go tool cmd. The situation is not concisely explained elsewhere in the main docs.

このコミットの目的は、doc/reference-cmd.html ファイルの導入部分を更新し、go コマンド、go cmd (例: go fmt)、および go tool cmd (例: go tool fmt) の違いを比較し、説明することです。これらの概念が主要なドキュメントの他の場所で簡潔に説明されていないという問題意識がありました。

変更の背景

Go言語は、その開発当初から強力なコマンドラインツール群を提供しており、go コマンドはその中心的な役割を担っています。しかし、go build や go run のような直接的なサブコマンドと、go tool cover や go tool pprof のような go tool を介して呼び出されるツール、さらには gofmt や godoc のようにスタンドアロンのバイナリとしても提供されるコマンドが存在し、これらがどのように関連し、どのような使い分けが推奨されるのかが、当時のドキュメントでは不明瞭でした。

このコミットは、Go言語の初期段階において、ユーザーがGoのツールチェインをより効果的に利用できるよう、これらのコマンドの呼び出し方法とそれぞれの役割を明確に定義し、ドキュメントの導入部分で一元的に説明することを目的としています。特に、パッケージ全体に作用する go cmd と、個別のファイルに作用できる go tool cmd の違いは、ユーザーがGoのビルドシステムや開発ワークフローを理解する上で非常に重要でした。

前提知識の解説

このコミットの変更内容を理解するためには、以下のGo言語の基本的な概念とコマンドラインツールの知識が必要です。

Go言語のコマンドラインツール: Go言語は、ソースコードのビルド、テスト、フォーマット、ドキュメント生成など、開発プロセスを支援するための豊富なコマンドラインツールを提供しています。これらは通常、go コマンドを介して実行されます。
go コマンド: Go言語の主要なコマンドラインインターフェースです。go build、go run、go test、go get など、Goプロジェクトの管理と操作のための様々なサブコマンドを提供します。これらのサブコマンドは、通常、Goのパッケージ全体に対して操作を行います。
go tool コマンド: go コマンドのサブコマンドの一つで、Goツールチェインに含まれる低レベルなツールや、特定の用途に特化したツールを実行するために使用されます。例えば、go tool compile (コンパイラ)、go tool link (リンカ)、go tool pprof (プロファイリングツール) などがあります。go tool を介して実行されるツールは、しばしば個別のファイルやより詳細な制御を可能にします。
Goパッケージ: Go言語のコードはパッケージに組織化されます。パッケージは関連するGoソースファイルの集合であり、Goプログラムのビルドと依存関係管理の基本単位です。go コマンドのサブコマンドの多くは、このパッケージ単位で動作します。
gofmt と godoc: これらはGo言語の標準ツールであり、それぞれコードの自動フォーマットとドキュメントの生成・表示を行います。これらは go fmt や go doc のように go コマンドのサブコマンドとして実行できるだけでなく、gofmt や godoc というスタンドアロンのバイナリとしてもインストールされ、直接実行することも可能です。

技術的詳細

このコミットは、doc/reference-cmd.html のHTMLコンテンツを直接変更することで、Goコマンドラインツールの利用方法に関する説明を改善しています。

変更の核心は、Goのコマンド実行の3つの主要な形態を明確に区別し、それぞれの特徴と推奨される使用シナリオを説明することにあります。

go cmd (例: go fmt):
- これは最も一般的なGoコマンドの実行方法です。
- go プログラムのサブコマンドとして機能します。
- 通常、Goソースコードの完全なパッケージに対して操作を行います。
- go プログラムが、パッケージレベルの処理に適した引数で基盤となるバイナリを呼び出します。
go tool cmd (例: go tool fmt):
- これは、go tool サブコマンドを介して実行される形式です。
- スタンドアロンのバイナリとして、引数を変更せずに実行されます。
- この形式は、例えば、パッケージ全体ではなく単一のソースファイルをフォーマットする (go tool fmt myprogram.go) といった、より粒度の細かい操作を可能にします。
- prof や yacc のような一部のコマンドは、go tool サブコマンドを介してのみアクセス可能です。
スタンドアロンバイナリ (例: gofmt, godoc):
- fmt と doc の2つのコマンドは、gofmt と godoc という通常のバイナリとしてもインストールされます。
- これらは非常に頻繁に参照されるため、直接実行できるように提供されています。

この説明の追加により、ユーザーはGoのコマンドラインツールが提供する柔軟性を理解し、特定のタスクに対して最適なコマンド実行方法を選択できるようになります。また、yacc コマンドの説明も「Yacc is a version of yacc for Go.」から「Yacc is a version of yacc that generates parsers implemented in Go.」へと修正され、より正確な機能説明がなされています。

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

変更は doc/reference-cmd.html ファイルの <p> タグ内のテキストと、go および yacc コマンドのテーブル記述部分に集中しています。

--- a/doc/reference-cmd.html
+++ b/doc/reference-cmd.html
@@ -4,7 +4,38 @@
 }-->
 
 <p>
-Click on the links for more documentation and usage messages.
+There is a suite of programs to build and process Go source code.
+Instead of being run directly, programs in the suite are usually invoked
+by the <a href="/cmd/go/">go</a> program.
+</p>
+
+<p>
+The most common way to run these programs is as a subcommand of the go
+program,
+for instance as "go fmt". Run like this, the command operates on complete
+packages of Go source code, with the go program invoking the underlying binary
+with arguments appropriate to package-level processing.
+</p>
+
+<p>
+The programs can also be run as stand-alone binaries, with unmodified arguments,
+using the go tool subcommand, such as "go tool fmt".
+This style of invocation allows, for instance, reformatting a single source file rather than
+an entire package: "go tool fmt myprogram.go" as compared to
+"go fmt mypackage".
+Some of the commands, such as prof and yacc, are accessible
+only through the go tool subcommand.
+</p>
+
+<p>
+Finally, two of the commands, fmt and
+doc, are also installed as regular binaries called
+gofmt and godoc
+because they are so often referenced.
+</p>
+
+<p>
+Click on the links for more documentation, invocation methods, and usage details.
 </p>
 
 <table class="dir">
@@ -18,10 +49,9 @@ Click on the links for more documentation and usage messages.
 <td><a href="/cmd/go/">go</a></td>
 <td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
 <td>
-Go is a tool for managing Go source code.
-<br>
-Besides compiling and running Go programs, the go command is also used to
-invoke the other commands listed below. See the command docs for usage
+The <code>go</code> program manages Go source code and runs the other
+commands listed here.
+See the command docs for usage
 details.\n
 <br><br>\n
 </td>
@@ -76,7 +106,7 @@ calls whose arguments do not align with the format string.</td>\n
 <tr>
 <td><a href="/cmd/yacc/">yacc</a></td>
 <td>&nbsp;&nbsp;&nbsp;&nbsp;</td>
-<td>Yacc is a version of yacc for Go.</td>
+<td>Yacc is a version of yacc that generates parsers implemented in Go.</td>
 </tr>
 
 </table>

コアとなるコードの解説

このコミットの主要な変更は、doc/reference-cmd.html の冒頭部分に、Goコマンドラインツールの呼び出し方法に関する新しい導入テキストを追加したことです。

新しい導入パラグラフの追加:
- Goソースコードをビルドおよび処理するためのプログラムスイートが存在し、これらは通常 go プログラムによって呼び出されることを説明しています。
- 最も一般的な実行方法として、go fmt のように go プログラムのサブコマンドとして実行する方法を説明しています。この場合、コマンドはGoソースコードの完全なパッケージに対して動作します。
- go tool fmt のように go tool サブコマンドを使用して、引数を変更せずにスタンドアロンのバイナリとして実行する方法も説明しています。これにより、単一のソースファイルをフォーマットするなど、パッケージ全体ではなくより細かい粒度での操作が可能になります。また、prof や yacc のような一部のコマンドは go tool を介してのみアクセス可能であることも明記しています。
- fmt と doc の2つのコマンドが、gofmt と godoc という通常のバイナリとしてもインストールされる理由（頻繁に参照されるため）を説明しています。
- 最後に、より詳細なドキュメント、呼び出し方法、および使用法の詳細についてはリンクをクリックするよう促しています。
go コマンドの説明の簡潔化:
- 以前の「Go is a tool for managing Go source code. Besides compiling and running Go programs, the go command is also used to invoke the other commands listed below.」という説明が、「The go program manages Go source code and runs the other commands listed here.」と簡潔に修正されました。これは、新しい導入部分で go コマンドの役割がより詳細に説明されているため、重複を避けるための変更と考えられます。
yacc コマンドの説明の修正:
- 「Yacc is a version of yacc for Go.」から「Yacc is a version of yacc that generates parsers implemented in Go.」へと変更されました。これにより、yacc がGo言語でパーサーを生成するツールであることがより正確に伝わるようになりました。

これらの変更により、Goのコマンドラインツールの利用に関するドキュメントの明確性が大幅に向上し、特に初心者にとってGoのツールチェインの理解が容易になりました。

参考にした情報源リンク

Go言語の公式リポジトリ (GitHub): https://github.com/golang/go
Go Code Review Comments (golang.org/cl/5906043 に関連する可能性のあるレビュープロセス): https://go.dev/doc/contribute#code_reviews
Go言語の初期の歴史に関する情報 (一般的な背景知識): https://go.dev/blog/go-at-google (Go言語の誕生と初期の利用に関するブログ記事)
Yacc (一般的なパーサージェネレータの概念): https://en.wikipedia.org/wiki/Yacc (Wikipedia)
Go言語のツールチェインに関する一般的な情報 (Goのビルドシステムなど): https://go.dev/doc/code (Go Code Organization)
Go言語のコマンドラインツールに関する一般的な情報: https://go.dev/doc/effective_go#command-line (Effective Go - Command-line arguments)

comemo