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

このコミットは、Go言語の標準ライブラリにおけるsyscallパッケージのFchflags関数に関するAPI例外の追加を扱っています。具体的には、api/except.txtファイルに新たなエントリを追加することで、特定のプラットフォーム（FreeBSD/ARM、NetBSD/ARM）でのビルド問題を解消することを目的としています。

コミット

commit ec8a24adbd710652212f763d2bc757480a7c45a2
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date:   Wed Jan 22 10:48:58 2014 -0800

    api: add Fchflags exception to more platforms
    
    Unbreaks the build.
    
    R=golang-codereviews, dsymonds
    CC=golang-codereviews
    https://golang.org/cl/53820045

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

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

元コミット内容

このコミットの元の内容は、api/except.txtファイルに以下の4行を追加することです。

--- a/api/except.txt
+++ b/api/except.txt
@@ -5,6 +5,10 @@ pkg syscall (darwin-amd64), func Fchflags(string, int) error
 pkg syscall (darwin-amd64-cgo), func Fchflags(string, int) error
 pkg syscall (freebsd-386), func Fchflags(string, int) error
 pkg syscall (freebsd-amd64), func Fchflags(string, int) error
+pkg syscall (freebsd-arm), func Fchflags(string, int) error
+pkg syscall (freebsd-arm-cgo), func Fchflags(string, int) error
+pkg syscall (netbsd-arm), func Fchflags(string, int) error
+pkg syscall (netbsd-arm-cgo), func Fchflags(string, int) error
 pkg testing, func RegisterCover(Cover)
 pkg text/template/parse, type DotNode bool
 pkg text/template/parse, type Node interface { Copy, String, Type }

これらの行は、syscallパッケージのFchflags関数が、freebsd-arm、freebsd-arm-cgo、netbsd-arm、netbsd-arm-cgoの各プラットフォームにおいて、GoのAPIチェッカーによって例外として扱われるべきであることを示しています。

変更の背景

コミットメッセージには「Unbreaks the build.」（ビルドを壊さないようにする）と簡潔に記されています。これは、Goのビルドシステムが、特定のプラットフォームでsyscall.Fchflags関数が見つからない、または期待されるシグネチャと異なるためにビルドエラーが発生していたことを示唆しています。

Go言語の標準ライブラリは、様々なオペレーティングシステムとアーキテクチャをサポートしています。しかし、OSやアーキテクチャによっては、特定のシステムコールやAPIが利用できなかったり、その動作が異なったりすることがあります。Fchflagsはファイルフラグを変更するためのシステムコールであり、Unix系のシステムで利用されますが、その実装や利用可能性はOSやバージョンによって異なります。

Goのビルドプロセスには、APIの互換性をチェックするメカニズムが含まれています。これは、Goのリリース間でAPIの意図しない変更が発生しないようにするためのものです。もし、あるプラットフォームで特定の関数が利用できない、あるいはそのシグネチャが異なる場合、APIチェッカーはエラーを報告し、ビルドを中断させることがあります。

このコミットは、freebsd-armおよびnetbsd-armという特定のARMアーキテクチャ上のFreeBSDおよびNetBSD環境において、Fchflags関数がGoのAPIチェ互換性チェックの対象外となるように設定することで、これらのプラットフォームでのビルド問題を解決しています。これは、これらの環境ではFchflagsが利用できないか、Goの期待する形で提供されていないため、ビルドを成功させるためには例外として扱う必要があると判断されたことを意味します。

前提知識の解説

Fchflagsシステムコール

Fchflagsは、Unix系オペレーティングシステムにおけるシステムコールの一つで、開いているファイルディスクリプタに関連付けられたファイルのフラグ（属性）を変更するために使用されます。ファイルフラグは、ファイルの動作や特性を制御するビットマスクであり、例えば、ファイルが変更不可であるか、削除不可であるか、あるいは特定のセキュリティ属性を持つかなどを指定できます。

このシステムコールは、主にBSD系のOS（FreeBSD, NetBSD, OpenBSD, macOSなど）で利用されます。Linuxには直接的なfchflagsシステムコールは存在せず、同様の機能はioctlやchattrコマンドを通じて提供されるファイル属性によって実現されます。

Go言語のsyscallパッケージは、OSのシステムコールをGoプログラムから呼び出すための低レベルなインターフェースを提供します。これにより、GoプログラムはOS固有の機能にアクセスできます。

GoのAPI互換性チェックとapi/except.txt

Go言語は、後方互換性を非常に重視しています。新しいGoのバージョンがリリースされる際、既存のGoプログラムが新しいバージョンでコンパイルできなくなるようなAPIの変更は極力避けるように設計されています。この互換性を保証するための一つのメカニズムが、APIの変更をチェックするツールです。

Goのビルドシステムには、標準ライブラリのAPIが以前のバージョンから変更されていないかを検証するステップが含まれています。このチェックは、GoのソースコードからAPI情報を抽出し、既知のAPIセットと比較することで行われます。

しかし、前述のように、特定のOSやアーキテクチャでは、一部のAPIが利用できない、あるいはその実装が異なる場合があります。このような場合、APIチェッカーが誤って「APIが変更された」と判断し、ビルドエラーを引き起こす可能性があります。

api/except.txtファイルは、このような「例外」を定義するために存在します。このファイルにエントリを追加することで、特定のパッケージ、関数、型などが、特定のプラットフォームにおいてAPI互換性チェックの対象外となるように指示できます。これにより、Goのビルドシステムは、そのAPIがそのプラットフォームで存在しない、または異なる形式であっても、エラーを報告せずにビルドを続行できるようになります。

api/except.txtのエントリの一般的な形式は以下のようになります。

pkg <パッケージ名> (<OS>-<アーキテクチャ>), <要素の種類> <要素名> <型/シグネチャ>

例えば、pkg syscall (darwin-amd64), func Fchflags(string, int) errorは、macOS (darwin) のAMD64アーキテクチャにおいて、syscallパッケージのFchflags関数がAPIチェックの例外であることを示します。

技術的詳細

このコミットの技術的な核心は、GoのビルドシステムにおけるAPI互換性チェックの「ホワイトリスト」メカニズムにあります。api/except.txtは、Goのツールチェーンが標準ライブラリのAPIを検証する際に参照する重要な設定ファイルです。

Goのビルドプロセスでは、go tool apiコマンド（またはそれに相当する内部処理）が実行され、Goのソースコードから公開APIのリストが生成されます。この生成されたAPIリストは、Goのリリースごとに「ゴールデンファイル」として保存されている既知のAPIリストと比較されます。この比較により、APIの追加、削除、変更が検出されます。

通常、APIの削除やシグネチャの変更は、後方互換性を損なうため、エラーとして扱われます。しかし、api/except.txtに記載されたエントリは、このチェックから除外されます。つまり、api/except.txtにpkg syscall (freebsd-arm), func Fchflags(string, int) errorと記述することで、Goのビルドシステムは、FreeBSD/ARM環境でsyscall.Fchflags関数が見つからなくても、それをAPIの削除とは見なさず、ビルドエラーを発生させないようになります。

これは、FchflagsシステムコールがFreeBSDのARMポートで利用できないか、あるいはGoのsyscallパッケージがそのプラットフォームでFchflagsを実装していない（または実装できない）場合に特に重要です。Goのsyscallパッケージは、各OSのシステムコールをGoの関数としてラップしていますが、すべてのOSのすべてのシステムコールをサポートしているわけではありません。特定のシステムコールが特定のプラットフォームで利用できない場合、そのプラットフォーム向けのGoのビルドでは、その関数は存在しないことになります。APIチェッカーがその事実を認識しないと、ビルドが失敗してしまいます。

このコミットは、freebsd-arm、freebsd-arm-cgo、netbsd-arm、netbsd-arm-cgoという4つの特定のプラットフォームターゲットに対して、Fchflags関数をAPIチェックの例外として追加しています。cgoが付いているものは、C言語との相互運用機能（cgo）が有効なビルドを指します。これは、cgoの有無にかかわらず、これらのARMベースのBSDシステムでFchflagsが問題を引き起こすことを示唆しています。

この変更は、Goのクロスプラットフォーム対応の複雑さの一端を示しています。Goは単一のコードベースから多数のプラットフォーム向けにコンパイルできますが、その過程でOSやアーキテクチャ固有の差異を吸収するための調整が必要になります。api/except.txtはそのような調整を行うための重要なメカニズムの一つです。

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

変更はapi/except.txtファイルのみです。

--- a/api/except.txt
+++ b/api/except.txt
@@ -5,6 +5,10 @@ pkg syscall (darwin-amd64), func Fchflags(string, int) error
 pkg syscall (darwin-amd64-cgo), func Fchflags(string, int) error
 pkg syscall (freebsd-386), func Fchflags(string, int) error
 pkg syscall (freebsd-amd64), func Fchflags(string, int) error
+pkg syscall (freebsd-arm), func Fchflags(string, int) error
+pkg syscall (freebsd-arm-cgo), func Fchflags(string, int) error
+pkg syscall (netbsd-arm), func Fchflags(string, int) error
+pkg syscall (netbsd-arm-cgo), func Fchflags(string, int) error
 pkg testing, func RegisterCover(Cover)
 pkg text/template/parse, type DotNode bool
 pkg text/template/parse, type Node interface { Copy, String, Type }\

具体的には、以下の4行が追加されています。

1. pkg syscall (freebsd-arm), func Fchflags(string, int) error
2. pkg syscall (freebsd-arm-cgo), func Fchflags(string, int) error
3. pkg syscall (netbsd-arm), func Fchflags(string, int) error
4. pkg syscall (netbsd-arm-cgo), func Fchflags(string, int) error

コアとなるコードの解説

追加された各行は、GoのAPIチェッカーに対して、特定のプラットフォームにおけるsyscall.Fchflags関数の存在を無視するように指示しています。

• pkg syscall: syscallパッケージ内のAPIに関する例外であることを示します。
• (freebsd-arm): ターゲットOSがFreeBSDで、アーキテクチャがARMであることを示します。
• (freebsd-arm-cgo): ターゲットOSがFreeBSDで、アーキテクチャがARM、かつcgoが有効なビルドであることを示します。
• (netbsd-arm): ターゲットOSがNetBSDで、アーキテクチャがARMであることを示します。
• (netbsd-arm-cgo): ターゲットOSがNetBSDで、アーキテクチャがARM、かつcgoが有効なビルドであることを示します。
• func Fchflags(string, int) error: 例外とするAPIが、Fchflagsという名前の関数であり、stringとint型の引数を取り、errorを返すシグネチャを持つことを示します。

これらのエントリが存在することで、Goのビルドシステムは、これらの特定のプラットフォームでFchflags関数が見つからなくても、それをAPIの欠落や変更とは見なさず、ビルドを正常に完了させることができます。これは、これらの環境ではFchflagsが利用できないか、Goの標準ライブラリがそのプラットフォームでFchflagsを実装していないため、ビルドを成功させるための必要な調整です。

関連リンク

• Go言語の公式ウェブサイト: https://golang.org/
• Goのsyscallパッケージのドキュメント: https://pkg.go.dev/syscall (このコミット時点のバージョンとは異なる可能性があります)
• GoのAPI互換性に関する議論やドキュメント（一般的な情報源）

参考にした情報源リンク

• Go言語のソースコードリポジトリ (GitHub): https://github.com/golang/go
• Goのapi/except.txtファイル: https://github.com/golang/go/blob/master/api/except.txt (現在のバージョン)
• GoのAPI互換性チェックに関する情報 (Goのドキュメントやブログ記事など)
• Unix系OSにおけるfchflagsシステムコールに関するmanページやドキュメント。
• Goのコードレビューシステム (Gerrit): https://golang.org/cl/53820045 (コミットメッセージに記載されているChange-ID)

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

このコミットは、Go言語の標準ライブラリにおけるsyscallパッケージのFchflags関数に関するAPI例外の追加を扱っています。具体的には、api/except.txtファイルに新たなエントリを追加することで、特定のプラットフォーム（FreeBSD/ARM、NetBSD/ARM）でのビルド問題を解消することを目的としています。

コミット

commit ec8a24adbd710652212f763d2bc757480a7c45a2
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date:   Wed Jan 22 10:48:58 2014 -0800

    api: add Fchflags exception to more platforms
    
    Unbreaks the build.
    
    R=golang-codereviews, dsymonds
    CC=golang-codereviews
    https://golang.org/cl/53820045

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

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

元コミット内容

このコミットの元の内容は、api/except.txtファイルに以下の4行を追加することです。

--- a/api/except.txt
+++ b/api/except.txt
@@ -5,6 +5,10 @@ pkg syscall (darwin-amd64), func Fchflags(string, int) error
 pkg syscall (darwin-amd64-cgo), func Fchflags(string, int) error
 pkg syscall (freebsd-386), func Fchflags(string, int) error
 pkg syscall (freebsd-amd64), func Fchflags(string, int) error
+pkg syscall (freebsd-arm), func Fchflags(string, int) error
+pkg syscall (freebsd-arm-cgo), func Fchflags(string, int) error
+pkg syscall (netbsd-arm), func Fchflags(string, int) error
+pkg syscall (netbsd-arm-cgo), func Fchflags(string, int) error
 pkg testing, func RegisterCover(Cover)
 pkg text/template/parse, type DotNode bool
 pkg text/template/parse, type Node interface { Copy, String, Type }

これらの行は、syscallパッケージのFchflags関数が、freebsd-arm、freebsd-arm-cgo、netbsd-arm、netbsd-arm-cgoの各プラットフォームにおいて、GoのAPIチェッカーによって例外として扱われるべきであることを示しています。

変更の背景

コミットメッセージには「Unbreaks the build.」（ビルドを壊さないようにする）と簡潔に記されています。これは、Goのビルドシステムが、特定のプラットフォームでsyscall.Fchflags関数が見つからない、または期待されるシグネチャと異なるためにビルドエラーが発生していたことを示唆しています。

Go言語の標準ライブラリは、様々なオペレーティングシステムとアーキテクチャをサポートしています。しかし、OSやアーキテクチャによっては、特定のシステムコールやAPIが利用できなかったり、その動作が異なったりすることがあります。Fchflagsはファイルフラグを変更するためのシステムコールであり、Unix系のシステムで利用されますが、その実装や利用可能性はOSやバージョンによって異なります。

Goのビルドプロセスには、APIの互換性をチェックするメカニズムが含まれています。これは、Goのリリース間でAPIの意図しない変更が発生しないようにするためのものです。もし、あるプラットフォームで特定の関数が利用できない、あるいはそのシグネチャが異なる場合、APIチェッカーはエラーを報告し、ビルドを中断させることがあります。

このコミットは、freebsd-armおよびnetbsd-armという特定のARMアーキテクチャ上のFreeBSDおよびNetBSD環境において、Fchflags関数がGoのAPI互換性チェックの対象外となるように設定することで、これらのプラットフォームでのビルド問題を解決しています。これは、これらの環境ではFchflagsが利用できないか、Goの期待する形で提供されていないため、ビルドを成功させるためには例外として扱う必要があると判断されたことを意味します。

前提知識の解説

Fchflagsシステムコール

Fchflagsは、Unix系オペレーティングシステムにおけるシステムコールの一つで、開いているファイルディスクリプタに関連付けられたファイルのフラグ（属性）を変更するために使用されます。ファイルフラグは、ファイルの動作や特性を制御するビットマスクであり、例えば、ファイルが変更不可であるか、削除不可であるか、あるいは特定のセキュリティ属性を持つかなどを指定できます。

このシステムコールは、主にBSD系のOS（FreeBSD, NetBSD, OpenBSD, macOSなど）で利用されます。Linuxには直接的なfchflagsシステムコールは存在せず、同様の機能はioctlやchattrコマンドを通じて提供されるファイル属性によって実現されます。

Go言語のsyscallパッケージは、OSのシステムコールをGoプログラムから呼び出すための低レベルなインターフェースを提供します。これにより、GoプログラムはOS固有の機能にアクセスできます。

GoのAPI互換性チェックとapi/except.txt

Go言語は、後方互換性を非常に重視しています。新しいGoのバージョンがリリースされる際、既存のGoプログラムが新しいバージョンでコンパイルできなくなるようなAPIの変更は極力避けるように設計されています。この互換性を保証するための一つのメカニズムが、APIの変更をチェックするツールです。

Goのビルドシステムには、標準ライブラリのAPIが以前のバージョンから変更されていないかを検証するステップが含まれています。このチェックは、GoのソースコードからAPI情報を抽出し、既知のAPIセットと比較することで行われます。

しかし、前述のように、特定のOSやアーキテクチャでは、一部のAPIが利用できない、あるいはその実装が異なる場合があります。このような場合、APIチェッカーが誤って「APIが変更された」と判断し、ビルドエラーを引き起こす可能性があります。

api/except.txtファイルは、このような「例外」を定義するために存在します。このファイルにエントリを追加することで、特定のパッケージ、関数、型などが、特定のプラットフォームにおいてAPI互換性チェックの対象外となるように指示できます。これにより、Goのビルドシステムは、そのAPIがそのプラットフォームで存在しない、または異なる形式であっても、エラーを報告せずにビルドを続行できるようになります。

api/except.txtのエントリの一般的な形式は以下のようになります。

pkg <パッケージ名> (<OS>-<アーキテクチャ>), <要素の種類> <要素名> <型/シグネチャ>

例えば、pkg syscall (darwin-amd64), func Fchflags(string, int) errorは、macOS (darwin) のAMD64アーキテクチャにおいて、syscallパッケージのFchflags関数がAPIチェックの例外であることを示します。

技術的詳細

このコミットの技術的な核心は、GoのビルドシステムにおけるAPI互換性チェックの「ホワイトリスト」メカニズムにあります。api/except.txtは、Goのツールチェーンが標準ライブラリのAPIを検証する際に参照する重要な設定ファイルです。

Goのビルドプロセスでは、go tool apiコマンド（またはそれに相当する内部処理）が実行され、Goのソースコードから公開APIのリストが生成されます。この生成されたAPIリストは、Goのリリースごとに「ゴールデンファイル」として保存されている既知のAPIリストと比較されます。この比較により、APIの追加、削除、変更が検出されます。

通常、APIの削除やシグネチャの変更は、後方互換性を損なうため、エラーとして扱われます。しかし、api/except.txtに記載されたエントリは、このチェックから除外されます。つまり、api/except.txtにpkg syscall (freebsd-arm), func Fchflags(string, int) errorと記述することで、Goのビルドシステムは、FreeBSD/ARM環境でsyscall.Fchflags関数が見つからなくても、それをAPIの削除とは見なさず、ビルドエラーを発生させないようになります。

これは、FchflagsシステムコールがFreeBSDのARMポートで利用できないか、あるいはGoのsyscallパッケージがそのプラットフォームでFchflagsを実装していない（または実装できない）場合に特に重要です。Goのsyscallパッケージは、各OSのシステムコールをGoの関数としてラップしていますが、すべてのOSのすべてのシステムコールをサポートしているわけではありません。特定のシステムコールが特定のプラットフォームで利用できない場合、そのプラットフォーム向けのGoのビルドでは、その関数は存在しないことになります。APIチェッカーがその事実を認識しないと、ビルドが失敗してしまいます。

このコミットは、freebsd-arm、freebsd-arm-cgo、netbsd-arm、netbsd-arm-cgoという4つの特定のプラットフォームターゲットに対して、Fchflags関数をAPIチェックの例外として追加しています。cgoが付いているものは、C言語との相互運用機能（cgo）が有効なビルドを指します。これは、cgoの有無にかかわらず、これらのARMベースのBSDシステムでFchflagsが問題を引き起こすことを示唆しています。

この変更は、Goのクロスプラットフォーム対応の複雑さの一端を示しています。Goは単一のコードベースから多数のプラットフォーム向けにコンパイルできますが、その過程でOSやアーキテクチャ固有の差異を吸収するための調整が必要になります。api/except.txtはそのような調整を行うための重要なメカニズムの一つです。

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

変更はapi/except.txtファイルのみです。

--- a/api/except.txt
+++ b/api/except.txt
@@ -5,6 +5,10 @@ pkg syscall (darwin-amd64), func Fchflags(string, int) error
 pkg syscall (darwin-amd64-cgo), func Fchflags(string, int) error
 pkg syscall (freebsd-386), func Fchflags(string, int) error
 pkg syscall (freebsd-amd64), func Fchflags(string, int) error
+pkg syscall (freebsd-arm), func Fchflags(string, int) error
+pkg syscall (freebsd-arm-cgo), func Fchflags(string, int) error
+pkg syscall (netbsd-arm), func Fchflags(string, int) error
+pkg syscall (netbsd-arm-cgo), func Fchflags(string, int) error
 pkg testing, func RegisterCover(Cover)
 pkg text/template/parse, type DotNode bool
 pkg text/template/parse, type Node interface { Copy, String, Type }\

具体的には、以下の4行が追加されています。

1. pkg syscall (freebsd-arm), func Fchflags(string, int) error
2. pkg syscall (freebsd-arm-cgo), func Fchflags(string, int) error
3. pkg syscall (netbsd-arm), func Fchflags(string, int) error
4. pkg syscall (netbsd-arm-cgo), func Fchflags(string, int) error

コアとなるコードの解説

追加された各行は、GoのAPIチェッカーに対して、特定のプラットフォームにおけるsyscall.Fchflags関数の存在を無視するように指示しています。

• pkg syscall: syscallパッケージ内のAPIに関する例外であることを示します。
• (freebsd-arm): ターゲットOSがFreeBSDで、アーキテクチャがARMであることを示します。
• (freebsd-arm-cgo): ターゲットOSがFreeBSDで、アーキテクチャがARM、かつcgoが有効なビルドであることを示します。
• (netbsd-arm): ターゲットOSがNetBSDで、アーキテクチャがARMであることを示します。
• (netbsd-arm-cgo): ターゲットOSがNetBSDで、アーキテクチャがARM、かつcgoが有効なビルドであることを示します。
• func Fchflags(string, int) error: 例外とするAPIが、Fchflagsという名前の関数であり、stringとint型の引数を取り、errorを返すシグネチャを持つことを示します。

これらのエントリが存在することで、Goのビルドシステムは、これらの特定のプラットフォームでFchflags関数が見つからなくても、それをAPIの欠落や変更とは見なさず、ビルドを正常に完了させることができます。これは、これらの環境ではFchflagsが利用できないか、Goの標準ライブラリがそのプラットフォームでFchflagsを実装していないため、ビルドを成功させるための必要な調整です。

関連リンク

• Go言語の公式ウェブサイト: https://golang.org/
• Goのsyscallパッケージのドキュメント: https://pkg.go.dev/syscall (このコミット時点のバージョンとは異なる可能性があります)
• GoのAPI互換性に関する議論やドキュメント（一般的な情報源）

参考にした情報源リンク

• Go言語のソースコードリポジトリ (GitHub): https://github.com/golang/go
• Goのapi/except.txtファイル: https://github.com/golang/go/blob/master/api/except.txt (現在のバージョン)
• GoのAPI互換性チェックに関する情報 (Goのドキュメントやブログ記事など)
• Unix系OSにおけるfchflagsシステムコールに関するmanページやドキュメント。
• Goのコードレビューシステム (Gerrit): https://golang.org/cl/53820045 (コミットメッセージに記載されているChange-ID)
• Web search results for "Go Fchflags" (provided by the tool)