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

このコミットは、Go言語のcmd/cgoツールにおける#cgoディレクティブのドキュメントを更新するものです。具体的には、#cgoディレクティブが受け入れる構文が、単なるGOOS、GOARCH、またはGOOS/GOARCHの組み合わせだけでなく、より広範なビルド制約（build constraints）をサポートしていることを明確にするための変更です。

コミット

commit 3c1ece2cb4caeb1a7ed6954e456dbe5bd6fd4c24
Author: Russ Cox <rsc@golang.org>
Date:   Mon Sep 23 16:29:53 2013 -0400

    cmd/cgo: update #cgo docs to reflect reality
    
    The syntax accepted is full build constraints, not just
    GOOS, GOARCH, and GOOS/GOARCH.
    
    R=golang-dev, iant
    CC=golang-dev
    https://golang.org/cl/13504048

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

https://github.com/golang/go/commit/3c1ece2cb4caeb1a7ed6954e456dbe5bd6fd4c24

元コミット内容

src/cmd/cgo/doc.go ファイルのドキュメントが更新され、#cgoディレクティブの条件指定に関する記述が修正されました。

変更前: Options prefixed by $GOOS, $GOARCH, or $GOOS/$GOARCH are only defined in matching systems. （$GOOS、$GOARCH、または$GOOS/$GOARCHでプレフィックスされたオプションは、一致するシステムでのみ定義されます。）

変更後: The directive can include a list of build constraints limiting its effect to systems satisfying one of the constraints (see http://golang.org/pkg/go/build/#hdr-Build_Constraints for details about the constraint syntax). （ディレクティブは、制約のいずれかを満たすシステムにその効果を制限するビルド制約のリストを含めることができます（制約構文の詳細については、http://golang.org/pkg/go/build/#hdr-Build_Constraints を参照してください）。）

また、例も更新されました。 変更前: // #cgo linux CFLAGS: -DLINUX=1

変更後: // #cgo amd64 386 CFLAGS: -DX86=1

変更の背景

このコミットの背景には、cmd/cgoツールにおける#cgoディレクティブの実際の挙動と、それに関する既存のドキュメントとの間に乖離があったことが挙げられます。以前のドキュメントでは、#cgoディレクティブの条件指定がGOOS（オペレーティングシステム）やGOARCH（アーキテクチャ）といった限定的なものにしか対応していないかのように記述されていました。しかし、実際のcgoの実装では、Goのビルドシステムが提供する「ビルド制約（build constraints）」の完全な構文をサポートしていました。

この乖離は、開発者が#cgoディレクティブを使用する際に誤解を招く可能性がありました。例えば、特定のGoバージョン、タグ、またはその他のカスタムビルド制約に基づいてC/C++コンパイラのフラグやリンカフラグを条件付きで適用したい場合、ドキュメントの記述だけを見ると、それが不可能であるかのように思えてしまいます。

Russ Cox氏によるこのコミットは、このドキュメントの不正確さを修正し、#cgoディレクティブがGoのビルド制約の全機能を活用できることを明確にすることで、開発者がより柔軟かつ正確にC/C++コードとGoコードを連携させられるようにすることを目的としています。これにより、クロスプラットフォーム開発や特定の環境に特化したビルド設定がより容易になります。

前提知識の解説

このコミットを理解するためには、以下のGo言語の概念について理解しておく必要があります。

1. Cgo: Cgoは、GoプログラムからC言語のコードを呼び出すためのGoのツールです。また、C言語のコードからGoの関数を呼び出すことも可能です。Cgoを使用することで、既存のCライブラリをGoプロジェクトに統合したり、Goでは実装が難しい低レベルの操作を行ったりすることができます。Cgoは、Goのソースファイル内に特別なコメントブロック（import "C"の直前）を記述することで有効になります。このコメントブロック内にCのコードを直接記述したり、Cのヘッダーファイルをインクルードしたりできます。

2. #cgo ディレクティブ: #cgoディレクティブは、CgoがC/C++コンパイラやリンカを呼び出す際に使用するフラグ（CFLAGS, CPPFLAGS, CXXFLAGS, LDFLAGSなど）をGoのソースコード内で指定するための特別なコメント行です。これにより、Goのビルドプロセスの一部としてC/C++コードをコンパイル・リンクする際の挙動を制御できます。例えば、特定のライブラリをリンクしたり、プリプロセッサマクロを定義したりするのに使われます。

3. ビルド制約 (Build Constraints): Go言語には、特定のファイルが特定のビルド環境でのみコンパイルされるように制御するための「ビルド制約」という強力なメカニズムがあります。これは、ファイルの先頭に// +buildまたは//go:build（Go 1.17以降）コメント行を記述することで指定されます。ビルド制約は、論理AND ( または,で区切る) や論理OR ( で区切る) を使って組み合わせることができ、GOOS（例: linux, windows）、GOARCH（例: amd64, arm64）、Goのバージョン（例: go1.18）、カスタムタグ（例: debug, integration）など、様々な条件を指定できます。 例えば、// +build linux,amd64 はLinuxかつamd64アーキテクチャの場合にのみファイルをコンパイルし、// +build debug || release はdebugタグまたはreleaseタグが指定された場合にコンパイルします。

このコミットは、#cgoディレクティブが、このビルド制約の完全な構文をサポートしているにもかかわらず、ドキュメントがその事実を反映していなかったという点に焦点を当てています。

技術的詳細

このコミットの技術的な核心は、#cgoディレクティブの条件指定が、Goのビルド制約パーサーと同じロジックを使用しているという点にあります。つまり、#cgoディレクティブの後に続く条件は、go/buildパッケージで定義されているビルド制約の構文規則に完全に準拠しています。

具体的には、#cgoディレクティブは以下のような形式を取ります。

// #cgo [build constraints] CFLAGS: -D_SOME_MACRO
// #cgo [build constraints] LDFLAGS: -lfoo

ここで[build constraints]の部分は、go/buildパッケージが解釈する任意のビルド制約の組み合わせが可能です。例えば、以下のような複雑な条件も指定できます。

• // #cgo linux,amd64 CFLAGS: -D_LINUX_AMD64
  • LinuxかつAMD64アーキテクチャの場合にのみ適用。
• // #cgo !windows CFLAGS: -D_NOT_WINDOWS
  • Windows以外のシステムの場合にのみ適用。
• // #cgo debug,go1.16 CFLAGS: -D_DEBUG_GO116
  • debugタグが有効で、かつGoのバージョンが1.16以上の場合にのみ適用。
• // #cgo arm || arm64 CFLAGS: -D_ARM_OR_ARM64
  • ARMまたはARM64アーキテクチャの場合にのみ適用。

以前のドキュメントでは、この[build constraints]の部分がGOOS、GOARCH、またはGOOS/GOARCHの単純な組み合わせに限定されているかのように誤解を招く記述がされていました。このコミットは、この誤解を解消し、#cgoディレクティブがGoのビルド制約の柔軟性を完全に享受できることを明示しています。

これにより、Cgoを使用するGoパッケージは、よりきめ細かくプラットフォーム固有のコンパイル・リンクオプションを制御できるようになります。例えば、特定のOSバージョンやCPUの機能拡張（例: AVX命令セットの有無）に基づいて異なるC/C++コンパイルフラグを適用するといった高度なビルド設定が可能になります。これは、特にクロスコンパイル環境や、多様なハードウェア環境をターゲットとする組み込みシステム開発において非常に有用です。

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

変更は src/cmd/cgo/doc.go ファイルに集中しています。

--- a/src/cmd/cgo/doc.go
+++ b/src/cmd/cgo/doc.go
@@ -27,11 +27,13 @@ http://golang.org/doc/articles/c_go_cgo.html.
 CFLAGS, CPPFLAGS, CXXFLAGS and LDFLAGS may be defined with pseudo #cgo
 directives within these comments to tweak the behavior of the C or C++
 compiler.  Values defined in multiple directives are concatenated
-together.  Options prefixed by $GOOS, $GOARCH, or $GOOS/$GOARCH are
-only defined in matching systems.  For example:\n
+together.  The directive can include a list of build constraints limiting its
+effect to systems satisfying one of the constraints
+(see http://golang.org/pkg/go/build/#hdr-Build_Constraints for details about the constraint syntax).\n
+For example:\n
 \n \t// #cgo CFLAGS: -DPNG_DEBUG=1\n
-\t// #cgo linux CFLAGS: -DLINUX=1\n
+\t// #cgo amd64 386 CFLAGS: -DX86=1\n
 \t// #cgo LDFLAGS: -lpng\n
 \t// #include <png.h>\n
 \timport "C"\n

コアとなるコードの解説

このコミットの変更は、src/cmd/cgo/doc.go内のコメント、つまりcgoツールのドキュメント部分のみです。実際のcgoのコード（パーサーやビルド制約の評価ロジック）自体には変更がありません。これは、cgoが既にビルド制約の完全な構文をサポートしていたため、ドキュメントを「現実（reality）」に合わせるだけでよかったことを意味します。

具体的には、以下の2点が変更されています。

1. 条件指定の記述の修正:

   • 変更前: Options prefixed by $GOOS, $GOARCH, or $GOOS/$GOARCH are only defined in matching systems.
     • これは、条件がGOOSやGOARCHといった環境変数に限定されるかのような印象を与えていました。
   • 変更後: The directive can include a list of build constraints limiting its effect to systems satisfying one of the constraints (see http://golang.org/pkg/go/build/#hdr-Build_Constraints for details about the constraint syntax).
     • この新しい記述は、#cgoディレクティブが「ビルド制約のリスト」を受け入れることを明確にしています。さらに、go/buildパッケージのドキュメントへのリンクを提供することで、ビルド制約の完全な構文とセマンティクスを開発者が参照できるようにしています。これは、Goのドキュメントにおける一般的なパターンであり、関連する詳細情報へのポインタを提供することで、ドキュメントの簡潔さを保ちつつ、必要に応じて深い情報にアクセスできるようにします。

2. 例の更新:

   • 変更前: // #cgo linux CFLAGS: -DLINUX=1
     • これはGOOSによる単純な条件の例でした。
   • 変更後: // #cgo amd64 386 CFLAGS: -DX86=1
     • この新しい例は、複数のアーキテクチャ（amd64と386）をOR条件で指定できることを示しています。これは、GOOSやGOARCHの単純な組み合わせだけでなく、より複雑なビルド制約が機能することを示す良い例です。amd64または386のいずれかのアーキテクチャでビルドされる場合に-DX86=1というCフラグが適用されることを意味します。

これらの変更は、cgoのドキュメントの正確性を向上させ、開発者が#cgoディレクティブの真の能力を理解し、活用できるようにするための重要な改善です。

関連リンク

• Go言語のCgoドキュメント: https://golang.org/doc/articles/c_go_cgo.html
• Go言語のビルド制約に関するドキュメント (go/buildパッケージ): https://golang.org/pkg/go/build/#hdr-Build_Constraints

参考にした情報源リンク

• Go言語の公式ドキュメント
• Go言語のソースコード (src/cmd/cgo/doc.go, go/buildパッケージ)
• GitHubのコミット履歴
• Go言語のメーリングリストやIssueトラッカー（golang-devなど）での議論（コミットメッセージにR=golang-devなどの記述があるため）
• 一般的なGo言語のビルドシステムに関する知識
• Cgoに関する技術記事やチュートリアル

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

このコミットは、Go言語のcmd/cgoツールにおける#cgoディレクティブのドキュメントを更新するものです。具体的には、#cgoディレクティブが受け入れる構文が、単なるGOOS、GOARCH、またはGOOS/GOARCHの組み合わせだけでなく、より広範なビルド制約（build constraints）をサポートしていることを明確にするための変更です。

コミット

commit 3c1ece2cb4caeb1a7ed6954e456dbe5bd6fd4c24
Author: Russ Cox <rsc@golang.org>
Date:   Mon Sep 23 16:29:53 2013 -0400

    cmd/cgo: update #cgo docs to reflect reality
    
    The syntax accepted is full build constraints, not just
    GOOS, GOARCH, and GOOS/GOARCH.
    
    R=golang-dev, iant
    CC=golang-dev
    https://golang.org/cl/13504048

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

https://github.com/golang/go/commit/3c1ece2cb4caeb1a7ed6954e456dbe5bd6fd4c24

元コミット内容

src/cmd/cgo/doc.go ファイルのドキュメントが更新され、#cgoディレクティブの条件指定に関する記述が修正されました。

変更前: Options prefixed by $GOOS, $GOARCH, or $GOOS/$GOARCH are only defined in matching systems. （$GOOS、$GOARCH、または$GOOS/$GOARCHでプレフィックスされたオプションは、一致するシステムでのみ定義されます。）

変更後: The directive can include a list of build constraints limiting its effect to systems satisfying one of the constraints (see http://golang.org/pkg/go/build/#hdr-Build_Constraints for details about the constraint syntax). （ディレクティブは、制約のいずれかを満たすシステムにその効果を制限するビルド制約のリストを含めることができます（制約構文の詳細については、http://golang.org/pkg/go/build/#hdr-Build_Constraints を参照してください）。）

また、例も更新されました。 変更前: // #cgo linux CFLAGS: -DLINUX=1

変更後: // #cgo amd64 386 CFLAGS: -DX86=1

変更の背景

このコミットの背景には、cmd/cgoツールにおける#cgoディレクティブの実際の挙動と、それに関する既存のドキュメントとの間に乖離があったことが挙げられます。以前のドキュメントでは、#cgoディレクティブの条件指定がGOOS（オペレーティングシステム）やGOARCH（アーキテクチャ）といった限定的なものにしか対応していないかのように記述されていました。しかし、実際のcgoの実装では、Goのビルドシステムが提供する「ビルド制約（build constraints）」の完全な構文をサポートしていました。

この乖離は、開発者が#cgoディレクティブを使用する際に誤解を招く可能性がありました。例えば、特定のGoバージョン、タグ、またはその他のカスタムビルド制約に基づいてC/C++コンパイラのフラグやリンカフラグを条件付きで適用したい場合、ドキュメントの記述だけを見ると、それが不可能であるかのように思えてしまいます。

Russ Cox氏によるこのコミットは、このドキュメントの不正確さを修正し、#cgoディレクティブがGoのビルド制約の全機能を活用できることを明確にすることで、開発者がより柔軟かつ正確にC/C++コードとGoコードを連携させられるようにすることを目的としています。これにより、クロスプラットフォーム開発や特定の環境に特化したビルド設定がより容易になります。

前提知識の解説

このコミットを理解するためには、以下のGo言語の概念について理解しておく必要があります。

1. Cgo: Cgoは、GoプログラムからC言語のコードを呼び出すためのGoのツールです。また、C言語のコードからGoの関数を呼び出すことも可能です。Cgoを使用することで、既存のCライブラリをGoプロジェクトに統合したり、Goでは実装が難しい低レベルの操作を行ったりすることができます。Cgoは、Goのソースファイル内に特別なコメントブロック（import "C"の直前）を記述することで有効になります。このコメントブロック内にCのコードを直接記述したり、Cのヘッダーファイルをインクルードしたりできます。

2. #cgo ディレクティブ: #cgoディレクティブは、CgoがC/C++コンパイラやリンカを呼び出す際に使用するフラグ（CFLAGS, CPPFLAGS, CXXFLAGS, LDFLAGSなど）をGoのソースコード内で指定するための特別なコメント行です。これにより、Goのビルドプロセスの一部としてC/C++コードをコンパイル・リンクする際の挙動を制御できます。例えば、特定のライブラリをリンクしたり、プリプロセッサマクロを定義したりするのに使われます。

3. ビルド制約 (Build Constraints): Go言語には、特定のファイルが特定のビルド環境でのみコンパイルされるように制御するための「ビルド制約」という強力なメカニズムがあります。これは、ファイルの先頭に// +buildまたは//go:build（Go 1.17以降）コメント行を記述することで指定されます。ビルド制約は、論理AND ( または,で区切る) や論理OR ( で区切る) を使って組み合わせることができ、GOOS（例: linux, windows）、GOARCH（例: amd64, arm）、Goのバージョン（例: go1.18）、カスタムタグ（例: debug, integration）など、様々な条件を指定できます。 例えば、// +build linux,amd64 はLinuxかつamd64アーキテクチャの場合にのみファイルをコンパイルし、// +build debug || release はdebugタグまたはreleaseタグが指定された場合にコンパイルします。

このコミットは、#cgoディレクティブが、このビルド制約の完全な構文をサポートしているにもかかわらず、ドキュメントがその事実を反映していなかったという点に焦点を当てています。

技術的詳細

このコミットの技術的な核心は、#cgoディレクティブの条件指定が、Goのビルド制約パーサーと同じロジックを使用しているという点にあります。つまり、#cgoディレクティブの後に続く条件は、go/buildパッケージで定義されているビルド制約の構文規則に完全に準拠しています。

具体的には、#cgoディレクティブは以下のような形式を取ります。

// #cgo [build constraints] CFLAGS: -D_SOME_MACRO
// #cgo [build constraints] LDFLAGS: -lfoo

ここで[build constraints]の部分は、go/buildパッケージが解釈する任意のビルド制約の組み合わせが可能です。例えば、以下のような複雑な条件も指定できます。

• // #cgo linux,amd64 CFLAGS: -D_LINUX_AMD64
  • LinuxかつAMD64アーキテクチャの場合にのみ適用。
• // #cgo !windows CFLAGS: -D_NOT_WINDOWS
  • Windows以外のシステムの場合にのみ適用。
• // #cgo debug,go1.16 CFLAGS: -D_DEBUG_GO116
  • debugタグが有効で、かつGoのバージョンが1.16以上の場合にのみ適用。
• // #cgo arm || arm64 CFLAGS: -D_ARM_OR_ARM64
  • ARMまたはARM64アーキテクチャの場合にのみ適用。

以前のドキュメントでは、この[build constraints]の部分がGOOS、GOARCH、またはGOOS/GOARCHの単純な組み合わせに限定されているかのように誤解を招く記述がされていました。このコミットは、この誤解を解消し、#cgoディレクティブがGoのビルド制約の柔軟性を完全に享受できることを明示しています。

これにより、Cgoを使用するGoパッケージは、よりきめ細かくプラットフォーム固有のコンパイル・リンクオプションを制御できるようになります。例えば、特定のOSバージョンやCPUの機能拡張（例: AVX命令セットの有無）に基づいて異なるC/C++コンパイルフラグを適用するといった高度なビルド設定が可能になります。これは、特にクロスコンパイル環境や、多様なハードウェア環境をターゲットとする組み込みシステム開発において非常に有用です。

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

変更は src/cmd/cgo/doc.go ファイルに集中しています。

--- a/src/cmd/cgo/doc.go
+++ b/src/cmd/cgo/doc.go
@@ -27,11 +27,13 @@ http://golang.org/doc/articles/c_go_cgo.html.
 CFLAGS, CPPFLAGS, CXXFLAGS and LDFLAGS may be defined with pseudo #cgo
 directives within these comments to tweak the behavior of the C or C++
 compiler.  Values defined in multiple directives are concatenated
-together.  Options prefixed by $GOOS, $GOARCH, or $GOOS/$GOARCH are
-only defined in matching systems.  For example:\n
+together.  The directive can include a list of build constraints limiting its
+effect to systems satisfying one of the constraints
+(see http://golang.org/pkg/go/build/#hdr-Build_Constraints for details about the constraint syntax).\n
+For example:\n
 \n \t// #cgo CFLAGS: -DPNG_DEBUG=1\n
-\t// #cgo linux CFLAGS: -DLINUX=1\n
+\t// #cgo amd64 386 CFLAGS: -DX86=1\n
 \t// #cgo LDFLAGS: -lpng\n
 \t// #include <png.h>\n
 \timport "C"\n

コアとなるコードの解説

このコミットの変更は、src/cmd/cgo/doc.go内のコメント、つまりcgoツールのドキュメント部分のみです。実際のcgoのコード（パーサーやビルド制約の評価ロジック）自体には変更がありません。これは、cgoが既にビルド制約の完全な構文をサポートしていたため、ドキュメントを「現実（reality）」に合わせるだけでよかったことを意味します。

具体的には、以下の2点が変更されています。

1. 条件指定の記述の修正:

   • 変更前: Options prefixed by $GOOS, $GOARCH, or $GOOS/$GOARCH are only defined in matching systems.
     • これは、条件がGOOSやGOARCHといった環境変数に限定されるかのような印象を与えていました。
   • 変更後: The directive can include a list of build constraints limiting its effect to systems satisfying one of the constraints (see http://golang.org/pkg/go/build/#hdr-Build_Constraints for details about the constraint syntax).
     • この新しい記述は、#cgoディレクティブが「ビルド制約のリスト」を受け入れることを明確にしています。さらに、go/buildパッケージのドキュメントへのリンクを提供することで、ビルド制約の完全な構文とセマンティクスを開発者が参照できるようにしています。これは、Goのドキュメントにおける一般的なパターンであり、関連する詳細情報へのポインタを提供することで、ドキュメントの簡潔さを保ちつつ、必要に応じて深い情報にアクセスできるようにします。

2. 例の更新:

   • 変更前: // #cgo linux CFLAGS: -DLINUX=1
     • これはGOOSによる単純な条件の例でした。
   • 変更後: // #cgo amd64 386 CFLAGS: -DX86=1
     • この新しい例は、複数のアーキテクチャ（amd64と386）をOR条件で指定できることを示しています。これは、GOOSやGOARCHの単純な組み合わせだけでなく、より複雑なビルド制約が機能することを示す良い例です。amd64または386のいずれかのアーキテクチャでビルドされる場合に-DX86=1というCフラグが適用されることを意味します。

これらの変更は、cgoのドキュメントの正確性を向上させ、開発者が#cgoディレクティブの真の能力を理解し、活用できるようにするための重要な改善です。

関連リンク

• Go言語のCgoドキュメント: https://golang.org/doc/articles/c_go_cgo.html
• Go言語のビルド制約に関するドキュメント (go/buildパッケージ): https://golang.org/pkg/go/build/#hdr-Build_Constraints

参考にした情報源リンク

• Go言語の公式ドキュメント
• Go言語のソースコード (src/cmd/cgo/doc.go, go/buildパッケージ)
• GitHubのコミット履歴
• Go言語のメーリングリストやIssueトラッカー（golang-devなど）での議論（コミットメッセージにR=golang-devなどの記述があるため）
• 一般的なGo言語のビルドシステムに関する知識
• Cgoに関する技術記事やチュートリアル