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

このコミットは、Go言語の標準ライブラリの一部である go/build パッケージのAPI変更に関するドキュメントの更新です。具体的には、go/build パッケージがビルド実行機能を持たなくなり、パッケージ情報の計算に特化するようになったこと、および関連する型や関数の名称変更・置き換えについて説明しています。この変更は、Go 1.0リリースに向けたAPIの整理と、go コマンドへのビルド機能の集約の一環として行われました。

コミット

commit 9996f7f17adca8af6b34c4df6870e88d289a65a9
Author: Russ Cox <rsc@golang.org>
Date:   Thu Mar 1 18:17:28 2012 -0500

    doc: describe API changes to go/build
    
    R=golang-dev, gri, r
    CC=golang-dev
    https://golang.org/cl/5711059

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

https://github.com/golang/go/commit/9996f7f17adca8af6b34c4df6870e88d289a65a9

元コミット内容

doc: describe API changes to go/build

R=golang-dev, gri, r
CC=golang-dev
https://golang.org/cl/5711059

変更の背景

このコミットは、Go言語がバージョン1.0のリリースを控えていた時期に行われた、APIの安定化と整理の一環です。特に、go/build パッケージの役割が再定義され、ビルドの実行という機能が go コマンド（cmd/go）に集約されることになりました。

Go言語の初期段階では、go/build パッケージはGoパッケージの情報を解析するだけでなく、実際にコードをビルドする機能も一部持っていました。しかし、Go言語が成熟し、より堅牢で一貫性のあるビルドシステムが必要とされる中で、ビルドの実行ロジックは go コマンドという単一のエントリポイントに集約されるべきであるという設計思想が確立されました。これにより、go/build パッケージは純粋にGoパッケージの構造や依存関係を解析し、ビルドに必要なメタデータを提供する役割に特化することになりました。

この変更の主な目的は以下の通りです。

役割の明確化: go/build パッケージは「パッケージ情報の計算」に、go コマンドは「ビルドの実行」にそれぞれ特化することで、各コンポーネントの責任範囲を明確にする。
一貫性の向上: ビルドプロセス全体を go コマンドが管理することで、ユーザー体験とツールの挙動に一貫性を持たせる。
APIの簡素化と安定化: go/build パッケージからビルド実行に関連する複雑なAPI（Cmd や Script 型など）を削除し、よりシンプルで安定したAPIを提供する。これにより、将来的な変更の影響を最小限に抑える。
ドキュメントの更新: ユーザーが新しいAPIと設計思想に適応できるよう、公式ドキュメントを最新の状態に保つ。

このコミットは、これらの変更を公式ドキュメント（doc/go1.html および doc/go1.tmpl）に反映させることを目的としています。

前提知識の解説

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

Go言語のパッケージシステム: Go言語はコードをパッケージ（package）という単位で管理します。パッケージは関連する機能の集合であり、他のパッケージからインポートして利用できます。
go コマンド: Go言語の公式ツールチェインの中心となるコマンドです。コードのビルド、テスト、実行、依存関係の管理など、Go開発における多くのタスクを担います。例えば、go build はGoプログラムをコンパイルし、go run はコンパイルと実行を一度に行います。
go/build パッケージ: Go言語の標準ライブラリの一部で、Goのソースコードやパッケージに関する情報をプログラム的に解析するための機能を提供します。例えば、特定のディレクトリがGoパッケージであるかどうかの判定、パッケージの依存関係の解決、ビルドタグの処理などを行います。
Go 1.0リリース: Go言語の最初の安定版リリースであり、APIの互換性が保証されるようになった重要なマイルストーンです。Go 1.0以降、既存のコードを壊すようなAPI変更は極力避けられるようになりました。このコミットは、Go 1.0リリース前の最終調整段階で行われたものです。
HTMLとGoテンプレート: doc/go1.html は最終的なHTMLドキュメントであり、doc/go1.tmpl はGoの text/template パッケージまたは類似のテンプレートエンジンで処理されるテンプレートファイルです。Goのドキュメントはしばしばテンプレートから生成されます。

技術的詳細

このコミットがドキュメントを更新している go/build パッケージは、Go言語のビルドシステムの中核をなす重要なコンポーネントです。このパッケージは、Goのソースファイルやディレクトリ構造を解析し、Goパッケージに関する詳細な情報（例: パッケージ名、インポートパス、ソースファイル、依存関係、ビルドタグなど）を抽出する役割を担っています。

コミットが説明している変更の技術的ポイントは以下の通りです。

ビルド実行機能の削除:
- 以前の go/build パッケージには、Cmd や Script といった型が存在し、これらがビルドの実行に関連する機能を提供していました。
- 今回の変更により、これらの型は削除されました。これは、ビルドの実行という責任が go コマンド（cmd/go）に完全に移管されたことを意味します。go/build は純粋な「パッケージ情報プロバイダ」としての役割に特化します。
- これにより、go/build パッケージのAPIはよりシンプルになり、その目的が明確になります。
型名の変更:
- DirInfo 型が Package 型に名称変更されました。
- DirInfo はディレクトリに関する情報、特にGoパッケージとしての情報を保持していましたが、Package という名称の方がその役割をより直接的に表現しています。これはAPIのセマンティクスを改善する変更です。
関数の置き換え:
- FindTree および ScanDir 関数が、Import および ImportDir 関数に置き換えられました。
- FindTree はGoのソースツリー内でパッケージを検索する機能、ScanDir は特定のディレクトリをスキャンしてパッケージ情報を取得する機能を提供していました。
- 新しい Import 関数は、インポートパスに基づいてパッケージ情報を取得します。これは、Goのビルドシステムがインポートパスを解決する際の主要なメカニズムと一致します。
- ImportDir 関数は、特定のディレクトリパスに基づいてパッケージ情報を取得します。これは ScanDir の後継であり、より洗練されたAPIを提供します。
- これらの新しい関数は、go/build パッケージがビルド実行ではなく、パッケージ情報の取得に特化するという新しい設計思想に沿っています。

これらの変更は、Go言語のビルドシステム全体のアーキテクチャを改善し、go コマンドをGo開発における中心的なツールとして確立するための重要なステップでした。開発者は、Goパッケージの情報をプログラム的に取得したい場合は go/build を使用し、実際にコードをビルド、テスト、実行したい場合は go コマンドを使用するという明確な指針を得ることになります。

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

このコミットは、Go言語の公式ドキュメントである doc/go1.html と doc/go1.tmpl の2つのファイルを変更しています。どちらのファイルも同じ内容が追加されており、go/build パッケージのAPI変更について説明する新しい段落が挿入されています。

doc/go1.html および doc/go1.tmpl の変更点:

--- a/doc/go1.html
+++ b/doc/go1.html
@@ -1283,6 +1283,22 @@ with the iterator <a href="/pkg/go/token/#FileSet.Iterate"><code>Iterate</code><\n accepts a function argument instead.\n </p>\n \n+<p>\n+In package <a href="/pkg/go/build/"><code>go/build</code></a>, the API\n+has been nearly completely replaced.\n+The package still computes Go package information\n+but it does not run the build: the <code>Cmd</code> and <code>Script</code>\n+types are gone.\n+(To build code, use the new\n+<a href="/cmd/go/"><code>go</code></a> command instead.)\n+The <code>DirInfo</code> type is now named\n+<a href="/pkg/go/build/#Package"><code>Package</code></a>.\n+<code>FindTree</code> and <code>ScanDir</code> are replaced by\n+<a href="/pkg/go/build/#Import"><code>Import</code></a>\n+and\n+<a href="/pkg/go/build/#ImportDir"><code>ImportDir</code></a>.\n+</p>\n+\n <p>\n  <em>Updating</em>:\n  Code that uses packages in <code>go</code> will have to be updated by hand; the

この差分は、既存のドキュメントの <p> タグの後に、新しい <p> タグで囲まれたGo/buildパッケージの変更に関する説明が追加されていることを示しています。

コアとなるコードの解説

追加されたドキュメントのテキストは、go/build パッケージのAPI変更を簡潔かつ明確に説明しています。

<p>
In package <a href="/pkg/go/build/"><code>go/build</code></a>, the API
has been nearly completely replaced.
The package still computes Go package information
but it does not run the build: the <code>Cmd</code> and <code>Script</code>
types are gone.
(To build code, use the new
<a href="/cmd/go/"><code>go</code></a> command instead.)
The <code>DirInfo</code> type is now named
<a href="/pkg/go/build/#Package"><code>Package</code></a>.
<code>FindTree</code> and <code>ScanDir</code> are replaced by
<a href="/pkg/go/build/#Import"><code>Import</code></a>
and
<a href="/pkg/go/build/#ImportDir"><code>ImportDir</code></a>.
</p>

この段落は以下の重要な情報を伝えています。

APIのほぼ全面的な置き換え: go/build パッケージのAPIが大幅に変更されたことを強調しています。これは、単なる小さな修正ではなく、パッケージの設計思想の変更に伴う大きな再編であることを示唆しています。
役割の明確化:
- 「The package still computes Go package information but it does not run the build」：go/build パッケージが引き続きGoパッケージの情報を計算する役割を担う一方で、ビルドの実行機能は持たないことを明確に述べています。
- 「the Cmd and Script types are gone.」：ビルド実行に関連していた Cmd と Script 型が削除されたことを明記しています。
- 「To build code, use the new go command instead.」：コードをビルドするには、新しい go コマンドを使用すべきであるという指示を与えています。これは、ビルド機能が go コマンドに集約されたことをユーザーに促すものです。
型と関数の名称変更・置き換え:
- 「The DirInfo type is now named Package.」：DirInfo 型が Package 型に名称変更されたことを伝えています。
- 「FindTree and ScanDir are replaced by Import and ImportDir.」：FindTree と ScanDir 関数が、それぞれ Import と ImportDir 関数に置き換えられたことを示しています。

このドキュメントの追加により、Go 1.0リリースに向けて go/build パッケージのAPIを利用していた開発者は、自身のコードを新しいAPIに合わせて更新する必要があることが明確に伝えられます。特に、ビルド実行ロジックを go/build に依存していた場合は、go コマンドへの移行が必須となります。

参考にした情報源リンク

Go 1 Release Notes (Go 1.0のリリースノート): https://go.dev/doc/go1
- このコミットが変更している doc/go1.html は、Go 1.0のリリースノートの一部です。
Go Project Issue Tracker (GoのIssueトラッカー): https://go.dev/issue
Gerrit Code Review (Goのコードレビューシステム): https://go-review.googlesource.com/
- コミットメッセージに記載されている https://golang.org/cl/5711059 は、このGerrit上の変更リスト（Change-ID）へのリンクです。
Go Blog (Go公式ブログ): https://go.dev/blog/
- Go 1.0リリースに関する詳細な背景情報が提供されている可能性があります。
Go Wiki (GoコミュニティWiki): https://go.dev/wiki
- Goの歴史や設計に関する追加情報が見つかる可能性があります。

comemo