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

このコミットは、Goコマンドラインツール (cmd/go) に、GoとC/C++間の呼び出しに関する基本的なドキュメントを追加するものです。これは、この主題に関するより詳細なドキュメントの「フレームワーク」として位置づけられています。具体的には、go help c という新しいヘルプトピックが追加され、cgo ツールと SWIG プログラムを用いたGoとC/C++の相互運用について説明されています。

コミット

commit 3d3bccc42145260869f9832107d8bdb5782a8608
Author: Ian Lance Taylor <iant@golang.org>
Date:   Tue Sep 17 17:10:48 2013 -0700

    cmd/go: add basic docs on calling between Go and C/C++
    
    This is a framework for docs on the subject more than it is
    actual docs.
    
    The section header in go/doc.go just says "C", not "C/C++,"
    because otherwise godoc doesn't recognize the line as a
    section header.
    
    Fixes #5473.
    
    R=golang-dev, r
    CC=golang-dev
    https://golang.org/cl/13280050

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

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

元コミット内容

cmd/go: add basic docs on calling between Go and C/C++

このコミットは、GoとC/C++間の呼び出しに関する基本的なドキュメントを追加するものです。これは、実際のドキュメントというよりも、この主題に関するドキュメントのフレームワークです。

go/doc.go のセクションヘッダーは「C」とだけ記述されており、「C/C++」とはなっていません。これは、そうしないと godoc がその行をセクションヘッダーとして認識しないためです。

Issue #5473 を修正します。

変更の背景

このコミットは、GoプログラムとC/C++コードを連携させる方法に関する公式ドキュメントの不足を解消するために行われました。Go言語は、既存のC/C++ライブラリとの連携を可能にする cgo などのメカニズムを提供していますが、その使用方法に関する包括的なドキュメントが不足していました。

コミットメッセージにある Fixes #5473 は、この変更がGoのIssueトラッカーで報告された特定の課題を解決するものであることを示しています。Issue #5473 の内容は「go help にC/C++との連携に関するドキュメントを追加する」というものであったと推測されます。

このコミットは、GoとC/C++の相互運用性に関する情報へのアクセスを容易にし、開発者がこれらの言語を組み合わせてアプリケーションを構築する際の障壁を低減することを目的としています。

前提知識の解説

このコミットの理解には、以下の概念に関する知識が役立ちます。

Go言語: Googleによって開発されたオープンソースのプログラミング言語。並行処理に強く、シンプルで効率的なコード記述を特徴とします。
C/C++言語: システムプログラミングや高性能なアプリケーション開発に広く用いられるプログラミング言語。Go言語とは異なるメモリ管理やコンパイルモデルを持ちます。
相互運用性 (Interoperability): 異なるプログラミング言語で書かれたコードが互いに連携して動作する能力。
cgo: Go言語に組み込まれているツールで、GoコードからCコードを呼び出し、またCコードからGoコードを呼び出すことを可能にします。cgo は、Cの関数やデータ構造をGoの型にマッピングし、GoとCの間の呼び出し規約の差異を吸収します。Goのソースファイル内にCのコードを直接記述し、import "C" を使用することで有効になります。
SWIG (Simplified Wrapper and Interface Generator): 異なるプログラミング言語（Go、Python、Javaなど）とC/C++/Objective-Cプログラムやライブラリを接続するためのオープンソースツール。SWIGは、C/C++のヘッダーファイルから、ターゲット言語のラッパーコードを自動生成します。cgo がGoに特化したツールであるのに対し、SWIGはより汎用的な目的で使用されます。
go build: Goのソースコードをコンパイルして実行可能ファイルやライブラリを生成するコマンド。このコマンドは、Goのコードだけでなく、cgo や SWIG を介して連携するC/C++コードのコンパイルも管理します。
godoc: Goのソースコードからドキュメントを生成し、表示するためのツール。Goのコメント規約に従って記述されたコメントを解析し、APIドキュメントとして整形します。
セクションヘッダー (Section Header): godoc がドキュメント内で特定のセクションを識別するために使用する特別なコメント形式。通常、// SectionName のように記述されます。

技術的詳細

このコミットの主要な技術的変更点は、go help c という新しいヘルプトピックの導入と、その内容です。

go help c の追加:
- src/cmd/go/help.go に helpC という新しい Command 構造体が定義されています。この構造体には、UsageLine (c)、Short (calling between Go and C/C++)、そして Long フィールドに詳細な説明が含まれています。
- src/cmd/go/main.go の commands スライスに helpC が追加され、go コマンドが go help c を認識し、対応するドキュメントを表示できるようになります。
ドキュメントの内容:
- go help c のドキュメントは、GoとC/C++を連携させる2つの主要な方法を説明しています。
  - cgo ツール: Goディストリビューションの一部であり、godoc cmd/cgo で詳細なドキュメントを参照できることが示されています。
  - SWIG プログラム: 汎用的なインターフェースツールであり、http://swig.org/ で情報が得られることが示されています。また、go build が .swig 拡張子のファイルをSWIGに渡し、.swigcxx 拡張子のファイルを -c++ オプション付きでSWIGに渡すことが明記されています。
- コンパイルの挙動: cgo または SWIG が使用される場合、go build は以下のファイルをそれぞれのコンパイラに渡すことが説明されています。
  - .c, .s, .S ファイルはCコンパイラへ。
  - .cc, .cpp, .cxx ファイルはC++コンパイラへ。
- 環境変数: CまたはC++コンパイラを指定するために、CC または CXX 環境変数を設定できることが述べられています。
既存のヘルプメッセージの更新:
- src/cmd/go/build.go と src/cmd/go/doc.go の両方で、go help build および go help doc のヘルプメッセージが更新され、GoとC/C++間の呼び出しに関する詳細情報のために go help c を実行するよう促す記述が追加されています。
godoc の認識問題への対応:
- コミットメッセージで言及されているように、src/cmd/go/doc.go 内のセクションヘッダーが「C」とだけ記述されているのは、godoc が「C/C++」のような形式をセクションヘッダーとして正しく認識しないという制約に対応するためです。これは、godoc のパーサーが特定のパターンに厳密に依存していることを示唆しています。

このコミットは、Goのビルドシステムとドキュメント生成システムが、外部言語との連携をどのようにサポートしているかを示す良い例です。特に、go build がC/C++ソースファイルを自動的に検出し、適切なコンパイラに渡す機能は、GoとC/C++のハイブリッドプロジェクトを容易にする上で重要です。

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

このコミットで変更された主要なファイルとコードスニペットは以下の通りです。

src/cmd/go/build.go:

--- a/src/cmd/go/build.go
+++ b/src/cmd/go/build.go
@@ -94,7 +94,8 @@ in an element in the list, surround it with either single or double quotes.
 
 For more about specifying packages, see 'go help packages'.
 For more about where packages and binaries are installed,
-see 'go help gopath'.
+run 'go help gopath'.  For more about calling between Go and C/C++,\n+run 'go help c'.
 
 See also: go install, go get, go clean.
 	`,

src/cmd/go/doc.go:

--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -32,6 +32,7 @@ Use "go help [command]" for more information about a command.
 
 Additional help topics:
 
+    c           calling between Go and C/C++
     gopath      GOPATH environment variable
     packages    description of package lists
     remote      remote import path syntax
@@ -111,7 +112,8 @@ in an element in the list, surround it with either single or double quotes.
 
 For more about specifying packages, see 'go help packages'.
 For more about where packages and binaries are installed,
-see 'go help gopath'.
+run 'go help gopath'.  For more about calling between Go and C/C++,\n+run 'go help c'.
 
 See also: go install, go get, go clean.
 
@@ -463,6 +465,25 @@ The -x flag prints commands as they are executed.\n See also: go fmt, go fix.\n \n \n+Calling between Go and C\n+\n+There are two different ways to call between Go and C/C++ code.\n+\n+The first is the cgo tool, which is part of the Go distribution.  For\n+information on how to use it see the cgo documentation (godoc cmd/cgo).\n+\n+The second is the SWIG program, which is a general tool for\n+interfacing between languages.  For information on SWIG see\n+http://swig.org/.  When running go build, any file with a .swig\n+extension will be passed to SWIG.  Any file with a .swigcxx extension\n+will be passed to SWIG with the -c++ option.\n+\n+When either cgo or SWIG is used, go build will pass any .c, .s, or .S\n+files to the C compiler, and any .cc, .cpp, .cxx files to the C++\n+compiler.  The CC or CXX environment variables may be set to determine\n+the C or C++ compiler, respectively, to use.\n+\n+\n GOPATH environment variable

src/cmd/go/help.go:

--- a/src/cmd/go/help.go
+++ b/src/cmd/go/help.go
@@ -4,6 +4,28 @@
 
 package main
 
+var helpC = &Command{
+	UsageLine: "c",
+	Short:     "calling between Go and C/C++",
+	Long: `
+There are two different ways to call between Go and C/C++ code.
+
+The first is the cgo tool, which is part of the Go distribution.  For
+information on how to use it see the cgo documentation (godoc cmd/cgo).\n+\n+The second is the SWIG program, which is a general tool for\n+interfacing between languages.  For information on SWIG see\n+http://swig.org/.  When running go build, any file with a .swig\n+extension will be passed to SWIG.  Any file with a .swigcxx extension\n+will be passed to SWIG with the -c++ option.\n+\n+When either cgo or SWIG is used, go build will pass any .c, .s, or .S\n+files to the C compiler, and any .cc, .cpp, .cxx files to the C++\n+compiler.  The CC or CXX environment variables may be set to determine\n+the C or C++ compiler, respectively, to use.\n+	`,
+}
+\n var helpPackages = &Command{
 	UsageLine: "packages",
 	Short:     "description of package lists",

src/cmd/go/main.go:

--- a/src/cmd/go/main.go
+++ b/src/cmd/go/main.go
@@ -88,6 +88,7 @@ var commands = []*Command{\n     	cmdVersion,\n     	cmdVet,\n     \n    +	helpC,\n     	helpGopath,\n     	helpPackages,\n     	helpRemote,

コアとなるコードの解説

このコミットの核心は、GoコマンドのヘルプシステムにGoとC/C++の相互運用に関する新しいエントリを追加することです。

src/cmd/go/help.go における helpC の定義:
- helpC は Command 型の変数として定義されており、go help コマンドが認識する新しいサブコマンドを表します。
- UsageLine: "c" は、このヘルプトピックが go help c として呼び出されることを指定します。
- Short: "calling between Go and C/C++" は、go help を実行した際に表示される短い説明です。
- Long フィールドには、GoとC/C++間の呼び出しに関する詳細な説明が複数行の文字列リテラルとして記述されています。この説明は、cgo と SWIG という2つの主要なツールに焦点を当て、それぞれの簡単な説明と、関連するドキュメントへの参照（godoc cmd/cgo や http://swig.org/）を提供しています。また、go build がC/C++ソースファイルをどのように処理するか、および CC/CXX 環境変数の役割についても説明しています。
src/cmd/go/main.go における helpC の登録:
- var commands = []*Command{...} というスライスは、go コマンドが認識するすべてのサブコマンドを定義しています。
- このスライスに helpC, が追加されることで、go コマンドは c を有効なヘルプトピックとして認識し、ユーザーが go help c を実行した際に helpC に定義された Long フィールドの内容を表示するようになります。
src/cmd/go/build.go および src/cmd/go/doc.go における参照の追加:
- これらのファイルは、それぞれ go help build と go help doc のヘルプメッセージを定義しています。
- 既存のヘルプメッセージに「For more about calling between Go and C/C++,\nrun 'go help c'.」という行が追加されています。これにより、GoとC/C++の連携に興味を持つユーザーが、関連する新しいヘルプトピックに容易に誘導されるようになります。

この変更は、Goのドキュメンテーションの改善に貢献し、特にGoとC/C++の相互運用という複雑なトピックに関する情報へのアクセス性を向上させています。

参考にした情報源リンク

Go言語の公式ドキュメント
cgo および SWIG の公式ドキュメント
Go言語のソースコード（特に src/cmd/go ディレクトリ内のファイル）
GoのIssueトラッカー (https://github.com/golang/go/issues)

comemo