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

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

このコミットは、Go言語の公式ドキュメントの一部である doc/articles/c_go_cgo.html ファイルに対する変更です。このファイルは、GoプログラムからC言語のコードを呼び出すためのメカニズムである cgo の使用方法について解説しています。具体的には、cgo がC言語のコメントブロックをどのように解釈するか、および #cgo や //export といったディレクティブの役割に関する説明を修正・拡充しています。また、文書全体で不適切なアポストロフィ文字を修正しています。

コミット

doc/articles/c_go_cgo.html ファイルにおいて、cgo のCコメントの解釈に関する記述を修正し、#cgo ディレクティブについて言及するように変更しました。また、無効なアポストロフィ文字を修正しました。

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

https://github.com/golang/go/commit/5ac186975c8a792a4504060001df12fa3ba2ba4e

元コミット内容

doc/articles/c_go_cgo.html: correct "C" comment to mention #cgo
    
Also fix invalid apostrophe characters.
    
R=r, gri, adg
CC=golang-dev
https://golang.org/cl/5874058

変更の背景

この変更の背景には、cgo のドキュメントの正確性と明確性を向上させるという目的があります。以前のドキュメントでは、import "C" の直前に記述されるC言語のコメントブロックが cgo によってどのように処理されるかについて、説明が不十分でした。特に、#cgo ディレクティブの存在とその機能について明示されていませんでした。

#cgo ディレクティブは、Cコンパイラやリンカに渡すフラグを指定するために非常に重要であり、cgo を利用するGoプログラムのビルドプロセスに直接影響を与えます。この情報が欠落していると、ユーザーが cgo を効果的に使用する上で混乱や誤解を招く可能性がありました。

また、ドキュメント全体にわたって使用されていた一部のアポストロフィ文字が、HTMLエンティティとして正しく表示されない、あるいは一般的なテキストエディタで扱いにくい文字であったため、より標準的なアポストロフィに修正する必要がありました。これは、ドキュメントの可読性とメンテナンス性を向上させるための一般的な修正です。

前提知識の解説

cgoとは

cgo は、Go言語のプログラムからC言語のコードを呼び出す（またはその逆）ためのGoツールです。Goは通常、GoランタイムとGoコンパイラによって完全に独立したバイナリを生成しますが、cgo を使用することで、既存のCライブラリやシステムコールをGoプログラムから直接利用できるようになります。これは、特にOSレベルの機能へのアクセス、パフォーマンスが重要な部分、または既存のC/C++コードベースとの連携が必要な場合に非常に有用です。

cgo を使用するには、Goのソースファイル内で import "C" という特別なインポート文を使用します。このインポート文の直前には、C言語のコードを記述するための特別なコメントブロックを配置します。

import "C" とCコメントブロック

Goのソースファイルで import "C" を記述すると、cgo ツールがそのファイルを処理します。このインポート文の直前にある複数行コメント（/* ... */）は、C言語のヘッダファイルのように扱われます。このコメントブロック内に記述されたC言語のコードは、GoプログラムがC関数を呼び出す際に必要な宣言を提供します。

例:

package main

/*
#include <stdio.h>
void my_c_function() {
    printf("Hello from C!\n");
}
*/
import "C"

func main() {
    C.my_c_function()
}

#cgo ディレクティブ

#cgo ディレクティブは、import "C" のコメントブロック内で使用される特別な指示子です。これらは cgo ツールによって解釈され、Cコンパイラ（GCCやClangなど）やリンカに渡すオプションを指定するために使用されます。#cgo で始まる行は、最終的なCヘッダには含まれず、cgo ツールによって処理された後に削除されます。

一般的な用途としては、以下のようなものがあります。

  • コンパイラフラグの指定: CFLAGS を使ってコンパイラに渡すオプション（例: -I でインクルードパスを追加、-D でマクロを定義）。
  • リンカフラグの指定: LDFLAGS を使ってリンカに渡すオプション（例: -L でライブラリパスを追加、-l でリンクするライブラリを指定）。
  • pkg-config の利用: pkg-config を使ってライブラリのコンパイル・リンク情報を自動的に取得。

例:

/*
#cgo CFLAGS: -I/opt/local/include
#cgo LDFLAGS: -L/opt/local/lib -lmylib
#include <mylib.h>
*/
import "C"

//export ディレクティブ

//export ディレクティブは、Goの関数をC言語のコードから呼び出せるようにするために使用されます。Goの関数定義の直前に //export FunctionName と記述することで、そのGo関数がC言語からエクスポートされ、C言語のコードから通常のC関数として呼び出せるようになります。

重要な制約として、//export ディレクティブを使用する場合、import "C" のコメントブロック内のCコードは宣言のみに限定され、定義（関数の実装など）を含めることはできません。これは、cgo がGoとCの間のシンボル解決をどのように行うかに関連する技術的な制約です。

技術的詳細

このコミットの技術的な詳細は、cgo のドキュメントにおけるCコメントブロックの解釈と、#cgo および //export ディレクティブの役割に関する説明の正確性を向上させることにあります。

変更前は、Cコメントブロックについて「Cgoはこのコメントを認識し、パッケージのC部分をコンパイルする際のヘッダとして使用します」とだけ記述されていました。これは部分的には正しいものの、#cgo ディレクティブの存在と、それがヘッダとして扱われるCコードから分離されるという重要な側面が欠落していました。

変更後では、この点が大幅に改善されています。

  1. #cgo ディレクティブの明示的な言及: 「Cgoはこのコメントを認識します。#cgo で始まる行は削除されます。これらは cgo のディレクティブとなります。」という記述が追加されました。これにより、#cgo が特別な意味を持つこと、そしてそれが最終的なCヘッダには含まれないことが明確になりました。

  2. Cヘッダとしての残りの行の役割の明確化: 「残りの行は、パッケージのC部分をコンパイルする際のヘッダとして使用されます。」と続き、#cgo 行が処理された後に残るCコードが実際にCコンパイラに渡されるヘッダであることを強調しています。

  3. //export ディレクティブとの関連性の追加: 「制限があります: プログラムが //export ディレクティブを使用する場合、コメント内のCコードは宣言（extern int f();）のみを含めることができ、定義（int f() { return 1; }）を含めることはできません。」という重要な制約が追加されました。これは、cgo を使用してGo関数をCにエクスポートする際の一般的な落とし穴であり、ドキュメントに明記されることでユーザーのデバッグ作業を軽減します。

  4. 公式ドキュメントへのリンク: #cgo と //export ディレクティブに関する詳細な情報が、cgo の公式ドキュメント（/cmd/cgo/）で確認できることを明示するリンクが追加されました。これにより、ユーザーはさらに深い情報を容易に参照できるようになります。

これらの変更は、cgo の動作原理をより正確に反映し、ユーザーが cgo を利用したGoプログラムを開発する際の理解を深める上で非常に重要です。特に、#cgo ディレクティブがビルドプロセスに与える影響や、//export 使用時の制約は、cgo のデバッグや高度な利用において不可欠な知識となります。

アポストロフィの修正は、技術的な内容には直接関係ありませんが、ドキュメントの品質と一貫性を保つための細かな修正です。

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

--- a/doc/articles/c_go_cgo.html
+++ b/doc/articles/c_go_cgo.html
@@ -18,7 +18,7 @@ and <code>srandom</code> functions.
 {{code "/doc/progs/cgo1.go" `/package rand/` `/END/`}}
 
 <p>
-Let’s look at what\'s happening here, starting with the import statement.
+Let\'s look at what\'s happening here, starting with the import statement.
 </p>
 
 <p>
@@ -45,7 +45,7 @@ package, using an ordinary Go type conversion:
 {{code "/doc/progs/cgo1.go" `/func Random/` `/STOP/`}}
 
 <p>
-Here’s an equivalent function that uses a temporary variable to illustrate
+Here\'s an equivalent function that uses a temporary variable to illustrate
 the type conversion more explicitly:
 </p>
 
@@ -73,11 +73,31 @@ above the <code>import</code> statement.
 {{code "/doc/progs/cgo1.go" `/\\/\\*/` `/STOP/`}}
 
 <p>
-Cgo recognizes this comment and uses it as a header when compiling the C
-parts of the package. In this case it is just a simple include statement,
-but it can be any valid C code. The comment must be immediately before the
-line that imports <code>"C"</code>, without any intervening blank lines,
-just like a documentation comment.
+Cgo recognizes this comment.  Any lines starting
+with <code>#cgo</code>
+followed
+by a space character are removed; these become directives for cgo.
+The remaining lines are used as a header when compiling the C parts of
+the package.  In this case those lines are just a
+single <code>#include</code>
+statement, but they can be almost any C code.  The <code>#cgo</code>
+directives are
+used to provide flags for the compiler and linker when building the C
+parts of the package.
+</p>
+
+<p>
+There is a limitation: if your program uses any <code>//export</code>
+directives, then the C code in the comment may only include declarations
+(<code>extern int f();</code>), not definitions (<code>int f() {\n+return 1; }</code>).  You can use <code>//export</code> directives to
+make Go functions accessible to C code.
+</p>
+
+<p>
+The <code>#cgo</code> and <code>//export</code> directives are
+documented in
+the <a href="/cmd/cgo/">cgo documentation</a>.
 </p>
 
 <p>
@@ -85,7 +105,7 @@ just like a documentation comment.
 </p>
 
 <p>
-Unlike Go, C doesn’t have an explicit string type. Strings in C are
+Unlike Go, C doesn\'t have an explicit string type. Strings in C are
 represented by a zero-terminated array of chars.
 </p>
 
@@ -107,7 +127,7 @@ string to standard output using C\'s <code>fputs</code> function from the
 <p>
 Memory allocations made by C code are not known to Go\'s memory manager.
 When you create a C string with <code>C.CString</code> (or any C memory
-allocation) you must remember to free the memory when you’re done with it
+allocation) you must remember to free the memory when you\'re done with it
 by calling <code>C.free</code>.
 </p>
 
@@ -147,7 +167,7 @@ in the Go tree demonstrate more advanced concepts.\n </p>\n \n <p>\n-For a simple, idiomatic example of a cgo-based package, see Russ Cox’s <a\n+For a simple, idiomatic example of a cgo-based package, see Russ Cox\'s <a\n href=\"http://code.google.com/p/gosqlite/source/browse/sqlite/sqlite.go\">gosqlite</a>.\n Also, the Go Project Dashboard lists <a\n href=\"https://godashboard.appspot.com/project?tag=cgo\">several other\n@@ -155,6 +175,6 @@ cgo packages</a>.\n </p>\n \n <p>\n-Finally, if you’re curious as to how all this works internally, take a look\n-at the introductory comment of the runtime package’s <a href=\"/src/pkg/runtime/cgocall.c\">cgocall.c</a>.\n+Finally, if you\'re curious as to how all this works internally, take a look\n+at the introductory comment of the runtime package\'s <a href=\"/src/pkg/runtime/cgocall.c\">cgocall.c</a>.\n </p>\n```

## コアとなるコードの解説

このコミットの主要な変更は、`doc/articles/c_go_cgo.html` ファイル内の `cgo` のCコメントブロックに関する説明のセクションに集中しています。

1.  **アポストロフィの修正**:
    ファイル全体で、`Let’s` や `Here’s`、`doesn’t`、`you’re` のような箇所で、特殊なアポストロフィ文字 `’` が標準的なアポストロフィ `'` に変更されています。これは、HTMLの表示やテキスト処理における互換性の問題を避けるための、一般的なテキストクリーンアップです。

2.  **Cコメントブロックの解釈に関する詳細な説明の追加**:
    最も重要な変更は、`Cgo recognizes this comment...` で始まる段落の拡張です。
    -   **変更前**: 「Cgoはこのコメントを認識し、パッケージのC部分をコンパイルする際のヘッダとして使用します。この場合、それは単なるシンプルなインクルード文ですが、任意の有効なCコードにすることができます。コメントは、`"C"` をインポートする行の直前になければならず、間に空白行があってはなりません。これはドキュメンテーションコメントと同じです。」
    -   **変更後**:
        -   「Cgoはこのコメントを認識します。`#cgo` で始まる行は削除されます。これらは `cgo` のディレクティブとなります。」という文が追加され、`#cgo` ディレクティブの特別な扱いが明示されました。
        -   「残りの行は、パッケージのC部分をコンパイルする際のヘッダとして使用されます。」と続き、`#cgo` 行が処理された後のCコードの役割が明確化されました。
        -   「`#cgo` ディレクティブは、パッケージのC部分をビルドする際に、コンパイラとリンカにフラグを提供するために使用されます。」と、`#cgo` の具体的な用途が説明されました。

3.  **`//export` ディレクティブに関する制約の追加**:
    新しい段落が追加され、`//export` ディレクティブを使用する場合の重要な制約が説明されています。
    -   「制限があります: プログラムが `//export` ディレクティブを使用する場合、コメント内のCコードは宣言（`extern int f();`）のみを含めることができ、定義（`int f() { return 1; }`）を含めることはできません。」
    -   「`//export` ディレクティブを使用して、Go関数をCコードからアクセス可能にすることができます。」と、`//export` の目的も簡潔に述べられています。

4.  **`cgo` ドキュメントへのリンクの追加**:
    `#cgo` と `//export` ディレクティブに関する詳細な情報が、`/cmd/cgo/` の `cgo` ドキュメントで確認できることを示すリンクが追加されました。

これらの変更により、`cgo` のドキュメントはより正確で包括的になり、ユーザーが `cgo` を使用する際の理解を深め、潜在的な問題を回避するのに役立ちます。

## 関連リンク

*   Go言語公式ドキュメント: [https://golang.org/](https://golang.org/)
*   `cgo` コマンドのドキュメント: [https://golang.org/cmd/cgo/](https://golang.org/cmd/cgo/)
*   Go Wiki - cgo: [https://go.dev/wiki/cgo](https://go.dev/wiki/cgo)

## 参考にした情報源リンク

*   コミットハッシュ: 5ac186975c8a792a4504060001df12fa3ba2ba4e
*   GitHubコミットページ: [https://github.com/golang/go/commit/5ac186975c8a792a4504060001df12fa3ba2ba4e](https://github.com/golang/go/commit/5ac186975c8a792a4504060001df12fa3ba2ba4e)
*   Go言語の `cgo` に関する一般的な知識とドキュメント。
*   `#cgo` および `//export` ディレクティブに関する情報。
*   HTMLにおけるアポストロフィの表現に関する一般的な知識。