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

このコミットは、Go言語のソースコードリポジトリにおけるsrc/run.batファイルの変更を記録しています。具体的には、go tool apiコマンドに新しいフラグ-exceptが追加されたことを示しています。

コミット

src/run.bat: add new flag for api tool Fixes build. Makes me annoyed.

R=golang-dev, dsymonds CC=golang-dev https://golang.org/cl/6591074

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

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

元コミット内容

commit dfa139aaa0ec9bfb2b23a66a315a88f757fdbea7
Author: Rob Pike <r@golang.org>
Date:   Thu Oct 4 11:49:33 2012 +1000

    src/run.bat: add new flag for api tool
    Fixes build.
    Makes me annoyed.
    
    R=golang-dev, dsymonds
    CC=golang-dev
    https://golang.org/cl/6591074

変更の背景

このコミットの背景には、Go言語のビルドプロセスにおけるAPI互換性チェックの問題があったと考えられます。コミットメッセージの「Fixes build.」と「Makes me annoyed.」という記述から、go tool apiコマンドが何らかの理由でビルドを妨げており、その問題を解決するためにこの変更が導入されたことが示唆されます。

Go言語では、後方互換性を非常に重視しており、新しいバージョンで既存のAPIが変更されることは厳しく管理されています。go tool apiは、このAPI互換性をチェックするためのツールです。しかし、開発中のコードベースでは、一時的にAPIの変更が発生したり、特定の変更が意図的に許可されたりする場合があります。このような状況で、go tool apiがエラーを発生させ、ビルドが中断されることがあったと推測されます。

-exceptフラグの追加は、特定のAPI変更を一時的に無視することで、ビルドを続行できるようにするための緊急的な対応であった可能性が高いです。「Makes me annoyed.」という表現は、開発者がこの問題に直面し、迅速な解決策が必要であったことを示しています。

前提知識の解説

`go tool api`

go tool apiは、Go言語の標準ツールチェーンに含まれるコマンドの一つで、GoのAPIの互換性をチェックするために使用されます。Go言語のバージョンアップにおいて、既存のプログラムが新しいGoバージョンでも問題なく動作するように、APIの変更は厳しく管理されています。このツールは、Goの標準ライブラリや公開APIが、以前のバージョンと比較して互換性のない変更が加えられていないかを検証します。

主な用途は以下の通りです。

後方互換性の維持: Go言語の重要な設計原則の一つは、後方互換性を維持することです。go tool apiは、新しいGoバージョンがリリースされる際に、既存のコードが壊れないことを保証するために使われます。
APIの変更管理: 開発者がGoの標準ライブラリに新しい機能を追加したり、既存の機能を変更したりする際に、意図しないAPIの変更が発生しないかを確認します。
go1.txtとnext.txt: 通常、このツールは2つのAPI定義ファイル（go1.txtやnext.txtなど）を比較します。go1.txtは安定版のAPI定義を、next.txtは開発中のAPI定義を表すことが多いです。

`run.bat`

run.batは、Windows環境で実行されるバッチファイルです。Go言語のプロジェクトにおいて、このようなファイルは通常、ビルド、テスト、リンティング、その他の開発タスクを自動化するために使用されます。Unix系システムにおけるMakefileやシェルスクリプトに相当します。

このファイルは、Goのソースコードをコンパイルし、テストを実行し、API互換性チェックのような追加の検証ステップを実行する一連のコマンドを含んでいます。

API互換性チェックの重要性

Go言語では、APIの安定性が非常に重視されています。これは、Goで書かれたアプリケーションが、Goの新しいバージョンにアップグレードされた際にも、再コンパイルするだけで動作し続けることを保証するためです。APIの互換性が損なわれると、多くの既存プロジェクトが影響を受け、アップグレードが困難になります。go tool apiのようなツールは、この互換性を自動的に検証し、開発者が意図しない破壊的変更を導入するのを防ぐ役割を担っています。

技術的詳細

このコミットは、src/run.batファイル内のgo tool apiコマンドの呼び出しに、-except ..\api\except.txtという新しい引数を追加しています。

変更前:

go tool api -c ..\api\go1.txt -next ..\api\next.txt

変更後:

go tool api -c ..\api\go1.txt -next ..\api\next.txt -except ..\api\except.txt

`go tool api`のフラグ

-c <file>: 比較の基準となるAPI定義ファイルを指定します。この場合、..\api\go1.txtはGo 1の安定したAPI定義を指していると考えられます。
-next <file>: 比較対象となる新しいAPI定義ファイルを指定します。..\api\next.txtは、現在開発中のGoバージョンのAPI定義を指します。
-except <file>: このフラグは、go tool apiがAPI互換性チェックを行う際に、特定の変更を例外として扱うためのファイルパスを指定します。..\api\except.txtファイルには、無視すべきAPIの変更（例えば、特定の関数の削除やシグネチャの変更など）がリストされていると推測されます。

`-except`フラグの役割

-exceptフラグの導入は、go tool apiが報告する互換性エラーの一部を意図的に抑制することを可能にします。これは、以下のようなシナリオで有用です。

意図的な破壊的変更: ごく稀に、Goのコア開発チームが、特定のAPIに対して後方互換性のない変更を意図的に行う場合があります。このような場合、except.txtにその変更を記述することで、go tool apiがエラーを報告しないようにできます。
一時的な開発中の変更: 開発ブランチでは、APIが頻繁に変更されることがあります。これらの変更が最終的に安定版にマージされる前に、一時的にビルドを通過させるために-exceptを使用することがあります。
特定の環境での差異: 特定のプラットフォームやビルド設定において、APIの振る舞いに微細な差異が生じ、それがgo tool apiによってエラーとして検出される場合があります。これを抑制するためにも使用されることがあります。

except.txtファイルは、通常、APIの変更内容を記述する特定のフォーマットに従っています。例えば、削除された関数名や変更されたメソッドシグネチャなどが記述されるでしょう。これにより、go tool apiは、そのファイルにリストされた変更については警告やエラーを出さずに、他の互換性のない変更のみを報告するようになります。

この変更は、ビルドプロセスをより柔軟にし、開発者がAPIの互換性に関する厳格なルールを一時的に緩和できるようにすることで、開発の効率を向上させることを目的としています。

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

diff --git a/src/run.bat b/src/run.bat
index ea87d3d806..67762e1df0 100644
--- a/src/run.bat
+++ b/src/run.bat
@@ -97,7 +97,7 @@ echo.
 if %FAIL%==1 goto fail
 
 echo # Checking API compatibility.
-go tool api -c ..\api\go1.txt -next ..\api\next.txt
+go tool api -c ..\api\go1.txt -next ..\api\next.txt -except ..\api\except.txt
 if errorlevel 1 goto fail
 echo.

コアとなるコードの解説

上記の差分は、src/run.batファイル内の97行目付近の変更を示しています。

-で始まる行は削除された行、+で始まる行は追加された行です。
変更前は、go tool apiコマンドが-c ..\api\go1.txt -next ..\api\next.txtという引数で実行されていました。これは、Go 1のAPI定義（go1.txt）と、次のバージョンのAPI定義（next.txt）を比較し、互換性のない変更がないかをチェックするものです。
変更後、このコマンドに-except ..\api\except.txtという新しい引数が追加されました。これにより、go tool apiは、except.txtファイルに記述されたAPIの変更については、互換性エラーとして報告しないようになります。

この変更は、ビルドスクリプトの一部としてAPI互換性チェックが実行される際に、特定のAPI変更を許容するためのメカニズムを導入したことを意味します。これにより、開発者は一時的にAPIの互換性チェックを緩和し、ビルドを成功させることが可能になります。これは、特に開発の初期段階や、特定のAPI変更が意図的である場合に有用です。

参考にした情報源リンク

Go言語の公式ドキュメント（go tool apiに関する情報）
Go言語のソースコードリポジトリ（src/cmd/go/internal/tool/api.goなど、go tool apiの実装に関する情報）
Go言語のIssueトラッカーやメーリングリスト（API互換性に関する議論や問題報告）

comemo