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

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

このコミットは、Go言語の標準ライブラリのAPI定義ファイルである api/go1.txt を更新し、ビルドの問題を修正することを目的としています。具体的には、cmd/api ツールによって生成されるAPIシグネチャが実際のGo 1 APIと一致するように修正され、その結果として api/go1.txt が再生成されています。

コミット

commit 7cda7dbe9aa688c105ae9ed55a2e39e7dff3d0ac
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date:   Tue Sep 18 22:04:07 2012 -0700

    api: fix build; regenerate api.txt with fixed signatures
    
    Update to tip (to get 6475062 and 6525047)
    Rebuild cmd/api.
    Switch to a go1 release branch.
    Run go tool api > api/go1.txt.new in release branch.
    Back to tip.
    
    R=golang-dev, mikioh.mikioh
    CC=golang-dev
    https://golang.org/cl/6528047

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

https://github.com/golang/go/commit/7cda7dbe9aa688c105ae9ed55a2e39e7dff3d0ac

元コミット内容

このコミットの元の内容は、api: fix build; regenerate api.txt with fixed signatures です。これは、API関連のビルド問題を修正し、修正されたシグネチャで api.txt を再生成したことを示しています。さらに、以下の手順が実行されたことが記されています。

  • tip (開発ブランチの最新状態) への更新 (コミット 6475062 と 6525047 を取り込むため)
  • cmd/api ツールの再ビルド
  • go1 リリースブランチへの切り替え
  • リリースブランチで go tool api > api/go1.txt.new を実行し、新しいAPI定義ファイルを生成
  • tip へ戻る

変更の背景

Go言語は、Go 1以降、厳格な後方互換性ポリシーを維持しています。これは、Go 1の仕様に準拠して書かれたプログラムが、将来のGoのバージョンでも変更なしにコンパイルおよび実行できることを保証するものです。この互換性を維持するために、Goの標準ライブラリの公開APIは api/go1.txt というファイルに記録されています。このファイルは、cmd/api ツールによって生成され、GoのAPIが意図せず変更されていないかをチェックするために使用されます。

このコミットが行われた背景には、おそらく cmd/api ツール自体、またはその生成プロセスに問題があり、api/go1.txt に記録されているAPIシグネチャが実際のGo 1のAPIと一致しなくなっていたことが考えられます。これにより、ビルドエラーが発生したり、APIの互換性チェックが正しく機能しなくなったりする可能性がありました。このコミットは、その問題を修正し、api/go1.txt を最新かつ正確なAPI定義で更新することで、Go 1の互換性保証を維持することを目的としています。

前提知識の解説

  • Go 1 互換性保証 (Go 1 Compatibility Guarantee): Go言語の最も重要な設計原則の一つで、Go 1以降のバージョンでは、既存のGo 1プログラムが変更なしに動作し続けることを保証します。これは、Goエコシステムの安定性と信頼性を高める上で不可欠です。この保証は、言語仕様と標準ライブラリの主要部分に適用されます。
  • api/go1.txt: Goの標準ライブラリの公開APIの定義を記述したテキストファイルです。各パッケージの関数、型、変数、メソッドなどのシグネチャが一覧形式で記述されています。このファイルは、Goのリリースプロセスにおいて、APIの意図しない変更がないかを自動的にチェックするために使用されます。
  • cmd/api ツール: Goのソースコードから公開APIのシグネチャを抽出し、api/go1.txt のような形式で出力するためのツールです。このツールは、APIの互換性チェックの自動化に不可欠な役割を果たします。
  • tip: Go言語開発における「tip」とは、開発ブランチ（通常は master または main）の最新の状態を指します。これは、まだリリースされていない最新の変更が含まれる不安定なバージョンです。
  • リリースブランチ (Release Branch): Goの新しいバージョンがリリースされる前に、安定化のために作成されるブランチです。このブランチでは、新機能の追加は停止され、バグ修正と安定性の向上が主な焦点となります。

技術的詳細

このコミットの技術的詳細は、主に api/go1.txt の変更内容に集約されます。差分を見ると、多くのパッケージで関数やメソッドのシグネチャが変更されています。これらの変更は、既存の関数に引数が追加されたり、戻り値の型が変更されたりするものがほとんどです。

例えば、pkg bytes パッケージの多くの関数 (Compare, Contains, Count, Equal, EqualFold, HasPrefix, HasSuffix, Index, LastIndex, Replace, Split, SplitAfter, SplitAfterN, SplitN) で、引数が追加されています。これは、これらの関数が以前は単一の引数を受け取っていたものが、実際には複数の引数を必要とするように変更されたことを示唆しています。

同様に、pkg crypto/cipher の Block インターフェースの Decrypt および Encrypt メソッド、BlockMode インターフェースの CryptBlocks メソッド、Stream インターフェースの XORKeyStream メソッドなどでも、引数が追加されています。

これらの変更は、GoのAPIが進化する過程で、api/go1.txt の定義が実際のコードベースと乖離してしまった結果と考えられます。cmd/api ツールを再ビルドし、go1 リリースブランチで api/go1.txt を再生成することで、この乖離が修正され、APIの定義が実際のコードベースと同期されました。これにより、Go 1の互換性保証が正しく機能するようになります。

特に注目すべきは、image パッケージにおける At, Set, PixOffset などのメソッドで、引数として int が一つだったものが (int, int) のように2つの引数（X座標とY座標）を受け取るように変更されている点です。これは、画像処理における座標指定の一般的なパターンに合わせた修正であり、APIの使いやすさや正確性を向上させるものです。

また、syscall パッケージの多くの関数でも引数の追加や変更が見られます。これは、システムコールインターフェースがOSやアーキテクチャによって異なる場合があるため、より汎用的なシグネチャに調整された可能性があります。

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

このコミットのコアとなるコードの変更箇所は、api/go1.txt ファイルの差分全体です。このファイルは、Goの標準ライブラリの公開APIの定義をテキスト形式で記述したものであり、このコミットではその内容が大幅に更新されています。

差分の例をいくつか示します。

pkg bytes パッケージの変更例:

-pkg bytes, func Compare([]byte) int
+pkg bytes, func Compare([]byte, []byte) int
-pkg bytes, func Contains([]byte) bool
+pkg bytes, func Contains([]byte, []byte) bool
...
-pkg bytes, func Replace([]byte, int) []byte
+pkg bytes, func Replace([]byte, []byte, []byte, int) []byte
-pkg bytes, func Split([]byte) [][]byte
+pkg bytes, func Split([]byte, []byte) [][]byte

pkg image パッケージの変更例:

-pkg image, func Pt(int) Point
+pkg image, func Pt(int, int) Point
-pkg image, func Rect(int) Rectangle
+pkg image, func Rect(int, int, int, int) Rectangle
...
-pkg image, method (*Alpha) At(int) color.Color
+pkg image, method (*Alpha) At(int, int) color.Color
-pkg image, method (*Alpha) Set(int, color.Color)
+pkg image, method (*Alpha) Set(int, int, color.Color)

pkg syscall パッケージの変更例:

-pkg syscall (darwin-386), func RawSyscall(uintptr) (uintptr, Errno)
+pkg syscall (darwin-386), func RawSyscall(uintptr, uintptr, uintptr, uintptr) (uintptr, uintptr, Errno)
-pkg syscall (darwin-386), func Link(string, string) error
-pkg syscall (darwin-386), func Rename(string, string) error
-pkg syscall (darwin-386), func Symlink(string, string) error

これらの差分は、GoのAPIがより正確に、またはより汎用的に定義されるように変更されたことを示しています。特に、引数の追加は、以前のAPI定義が不完全であったか、または特定のコンテキストでのみ有効なシグネチャを記述していた可能性を示唆しています。

コアとなるコードの解説

このコミット自体は、Goのソースコードのロジックを変更するものではなく、Goの公開APIの「スナップショット」である api/go1.txt を更新するものです。したがって、直接的な「コアとなるコードの変更」は api/go1.txt の内容そのものになります。

このファイルは、go tool api コマンドによって自動生成されるため、手動で編集されることは稀です。このコミットの目的は、cmd/api ツールが正しく動作し、Go 1のAPIの正確な表現を生成するようにすることでした。

api/go1.txt の各行は、Goの公開APIの要素（パッケージ、関数、型、メソッド、変数、定数など）とそのシグネチャを記述しています。例えば、pkg bytes, func Compare([]byte, []byte) int という行は、bytes パッケージに Compare という関数があり、それが2つの []byte 型の引数を受け取り、int 型の値を返すことを示しています。

このコミットで行われた変更は、主に以下のパターンに分類されます。

  1. 引数の追加: 多くの関数やメソッドで、不足していた引数が追加されています。これは、APIの定義がより完全になり、実際の使用方法と一致するようになったことを意味します。例えば、bytes.Compare は以前は1つの []byte を受け取るように見えましたが、実際には2つの []byte を比較する関数であるため、2つ目の引数が追加されました。
  2. 戻り値の変更: 一部の関数で、戻り値の型や数が変更されています。これは、APIのセマンティクスがより正確に反映されるようになったことを示します。
  3. インターフェースのシグネチャ変更: container/heap.Interface や image.Image などのインターフェースのメソッドシグネチャが変更されています。これにより、これらのインターフェースを実装する型が、より正確なメソッドシグネチャを持つことが期待されます。
  4. プラットフォーム固有のAPIの修正: syscall パッケージのように、OSやアーキテクチャによってAPIが異なる場合があるパッケージで、より正確なシグネチャが反映されています。

これらの変更は、GoのAPIの正確な定義を維持し、Go 1の互換性保証を遵守するために不可欠なものです。api/go1.txt が正確であることで、Goの開発者は将来のバージョンアップ時にも既存のコードが問題なく動作することを信頼できます。

関連リンク

  • Go 1 Compatibility Guarantee: https://go.dev/doc/go1compat
  • GoのAPI互換性に関するブログ記事など（具体的なリンクはコミットメッセージにはないため、一般的な情報源を挙げる）

参考にした情報源リンク

  • Go 1 Compatibility Guarantee: https://go.dev/doc/go1compat
  • Go言語の公式ドキュメント (GoのAPIやツールの一般的な情報源として)
  • GitHubのGoリポジトリ (コミット履歴やコードベースの構造を理解するため)