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

このコミットは、Go言語のコマンドラインツールgoのドキュメントに関する修正です。具体的には、go buildコマンドがCgoまたはSWIGを使用する際にCコンパイラに渡すファイルの種類に関する説明に、Objective-Cのソースファイルである.m拡張子を追加する変更を再適用しています。以前の変更がドキュメント生成プロセスによって上書きされてしまったため、その原因を修正し、永続的な変更となるようにしています。

コミット

commit 6f2d91a094c78165646ddaa0c139191f6943c7d2
Author: Russ Cox <rsc@golang.org>
Date:   Wed Apr 16 22:30:10 2014 -0400

    cmd/go: reapply doc change from CL 60590044.
    
    https://golang.org/cl/60590044 edited
    doc.go without editing the file it is generated from.
    The edit was lost at the next mkdoc.sh.
    Make the change in help.go and rerun mkdoc.sh.
    
    Pointed out in the review of CL 68580043.
    
    TBR=iant
    CC=golang-codereviews
    https://golang.org/cl/88760043

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

https://github.com/golang/go/commit/6f2d91a094c78165646ddaa0c139191f6943c7d2

元コミット内容

このコミットは、以前の変更リスト（Change List: CL）60590044で導入されたドキュメントの変更を再適用するものです。元の変更は、go buildがCgoまたはSWIGと連携する際にCコンパイラに渡されるファイル拡張子のリストに.m（Objective-Cソースファイル）を追加することでした。しかし、この変更はdoc.goファイルに直接行われたため、mkdoc.shスクリプトによるドキュメント再生成時に、生成元のファイルが更新されていなかったために上書きされ、失われてしまいました。

変更の背景

Goプロジェクトでは、ドキュメントの一部がソースコードから自動生成される仕組みになっています。特に、src/cmd/go/doc.goファイルは、src/cmd/go/help.goなどのソースファイルからmkdoc.shスクリプトによって生成されます。

以前、CL 60590044において、go buildコマンドのヘルプドキュメントに、CgoまたはSWIGを使用する際にCコンパイラに渡されるファイル拡張子として.m（Objective-Cソースファイル）が追加されました。これは、GoがObjective-Cコードと連携する際の正確な情報を提供するための重要な更新でした。

しかし、この変更は生成される側のdoc.goファイルに直接適用されてしまい、生成元のhelp.goファイルには反映されていませんでした。そのため、次にmkdoc.shスクリプトが実行された際に、help.goの内容に基づいてdoc.goが再生成され、手動で追加された.mに関する記述が上書きされて失われてしまいました。

この問題は、CL 68580043のレビュー中に指摘され、ドキュメントの整合性を保つために、生成元のhelp.goを修正し、mkdoc.shを再実行することで、この変更を永続化する必要があるという認識に至りました。本コミットは、この問題を解決し、ドキュメントの正確性を維持することを目的としています。

前提知識の解説

このコミットを理解するためには、以下の技術的な概念とGoのビルドシステムに関する知識が必要です。

Go言語のビルドプロセス

Go言語のビルドは、go buildコマンドによって行われます。このコマンドは、Goのソースコードをコンパイルし、実行可能なバイナリを生成します。Goは、純粋なGoコードだけでなく、C/C++などの他の言語で書かれたコードと連携する機能も持っています。

cgo

cgoは、GoプログラムがC言語のコードを呼び出したり、C言語のコードからGoの関数を呼び出したりするためのメカニズムです。Goのソースファイル内にimport "C"という行があると、cgoが有効になり、GoとCの間のインターフェースが生成されます。cgoを使用すると、Goプログラム内で既存のCライブラリを利用したり、パフォーマンスが重要な部分をCで記述したりすることが可能になります。

SWIG (Simplified Wrapper and Interface Generator)

SWIGは、C/C++で書かれたライブラリを、Python, Java, Ruby, Goなど様々なスクリプト言語やプログラミング言語から利用できるようにするためのツールです。SWIGは、C/C++のヘッダーファイルから、ターゲット言語のラッパーコードを自動生成します。Go言語においても、SWIGはC/C++ライブラリとの連携を容易にするために使用されます。

ファイル拡張子とコンパイラ

Goのビルドプロセスにおいて、cgoやSWIGが使用される場合、Go以外の言語で書かれたソースファイルは適切なコンパイラに渡されます。

.c: C言語のソースファイル。Cコンパイラ（通常はGCCやClang）に渡されます。
.s, .S: アセンブリ言語のソースファイル。アセンブラに渡されます。
.m: Objective-Cのソースファイル。Objective-CはC言語のスーパーセットであり、通常はCコンパイラ（Clangなど）によってコンパイルされます。このコミットの主要な変更点です。
.cc, .cpp, .cxx: C++言語のソースファイル。C++コンパイラに渡されます。

Goのドキュメント生成と`mkdoc.sh`

Goプロジェクトでは、ユーザー向けのドキュメントやヘルプメッセージの一部が、特定のGoソースファイル内のコメントから自動的に抽出・生成されます。mkdoc.shのようなスクリプトは、この自動生成プロセスを実行するために使用されます。

src/cmd/go/help.go: goコマンドのヘルプメッセージの「ソース」となるGoファイルです。このファイル内の特定のコメントブロックが、ユーザーに表示されるドキュメントの元になります。
src/cmd/go/doc.go: help.goから生成されるドキュメントファイルです。このファイルは、go doc cmd/goなどで表示されるドキュメントの内容を含んでいます。

mkdoc.shスクリプトは、help.goのようなソースファイルを読み込み、そこからドキュメントを抽出し、doc.goのような生成されるファイルに書き出します。したがって、ドキュメントの内容を変更する際は、doc.goを直接編集するのではなく、help.goのような生成元のファイルを編集し、その後mkdoc.shを実行してdoc.goを更新するのが正しい手順となります。

Gerrit / Change List (CL)

Goプロジェクトでは、コードレビューにGerritというシステムを使用しています。Gerritでは、各変更提案が「Change List (CL)」として管理され、一意の番号が割り当てられます（例: golang.org/cl/60590044）。開発者はCLを提出し、他の開発者からのレビューを経て、承認されるとメインのコードベースにマージされます。

技術的詳細

このコミットの技術的な核心は、Goのドキュメント生成ワークフローの理解と、Goが外部言語（特にObjective-C）と連携する際のビルドプロセスの正確な記述にあります。

問題は、以前のCL 60590044で、go buildのドキュメントに.mファイルがCコンパイラに渡されるという重要な情報が追加されたにもかかわらず、その変更がsrc/cmd/go/doc.goという「生成された」ファイルに直接行われた点にありました。Goプロジェクトの慣習として、doc.goはmkdoc.shスクリプトによってhelp.goから自動生成されるため、help.goが更新されていなければ、mkdoc.shが実行されるたびにdoc.goへの手動変更は失われてしまいます。

本コミットは、この問題を解決するために、ドキュメントの「真のソース」であるsrc/cmd/go/help.goを修正しています。これにより、mkdoc.shが実行されても、.mファイルに関する記述がdoc.goに正しく反映され、永続化されるようになります。

変更内容自体は非常にシンプルで、ドキュメント内の該当箇所に.m拡張子を追加するだけです。しかし、この小さな変更は、GoがObjective-Cコードと連携できるという重要な機能を示しており、特にmacOSやiOSプラットフォームでGoアプリケーションを開発する際に、Objective-Cの既存ライブラリを利用するcgoやSWIGのユーザーにとって、正確な情報を提供することになります。

この修正は、Goプロジェクトにおけるドキュメント管理のベストプラクティス（生成されるファイルではなく、生成元を編集する）を遵守することの重要性を示しています。

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

--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -511,8 +511,8 @@ http://swig.org/.  When running go build, any file with a .swig
 extension will be passed to SWIG.  Any file with a .swigcxx extension
 will be passed to SWIG with the -c++ option.
 
-When either cgo or SWIG is used, go build will pass any .c, .s, or .S
-files to the C compiler, and any .cc, .cpp, .cxx files to the C++
+When either cgo or SWIG is used, go build will pass any .c, .m, .s,
+or .S files to the C compiler, and any .cc, .cpp, .cxx files to the C++
 compiler.  The CC or CXX environment variables may be set to determine
 the C or C++ compiler, respectively, to use.
 
diff --git a/src/cmd/go/help.go b/src/cmd/go/help.go
index faa4d9af82..0142deee9f 100644
--- a/src/cmd/go/help.go
+++ b/src/cmd/go/help.go
@@ -19,8 +19,8 @@ http://swig.org/.  When running go build, any file with a .swig
 extension will be passed to SWIG.  Any file with a .swigcxx extension
 will be passed to SWIG with the -c++ option.
 
-When either cgo or SWIG is used, go build will pass any .c, .s, or .S
-files to the C compiler, and any .cc, .cpp, .cxx files to the C++
+When either cgo or SWIG is used, go build will pass any .c, .m, .s,
+or .S files to the C compiler, and any .cc, .cpp, .cxx files to the C++
 compiler.  The CC or CXX environment variables may be set to determine
 the C or C++ compiler, respectively, to use.\n\t`,\n

コアとなるコードの解説

このコミットでは、src/cmd/go/doc.goとsrc/cmd/go/help.goの2つのファイルが変更されています。両方のファイルで全く同じ変更が行われているのは、doc.goがhelp.goから生成されるためです。

変更の核心は以下の行にあります。

-When either cgo or SWIG is used, go build will pass any .c, .s, or .S
-files to the C compiler, and any .cc, .cpp, .cxx files to the C++
+When either cgo or SWIG is used, go build will pass any .c, .m, .s,
+or .S files to the C compiler, and any .cc, .cpp, .cxx files to the C++

-で始まる行: 変更前の元の行を示します。ここでは、cgoまたはSWIGが使用される場合に、go buildが.c、.s、または.SファイルをCコンパイラに渡し、.cc、.cpp、.cxxファイルをC++コンパイラに渡す、と記述されています。
+で始まる行: 変更後の新しい行を示します。この行では、Cコンパイラに渡されるファイルのリストに新たに「.m」が追加されています。これにより、go buildがCgoまたはSWIGと連携する際に、Objective-Cのソースファイル（.m）もCコンパイラに渡されることが明示されます。

この変更は、GoのビルドシステムがObjective-Cファイルを適切に処理できることをドキュメントに反映させるものです。特に、help.goへの変更が重要であり、これによりmkdoc.shが実行されてもこの情報が失われることなく、doc.goに常に最新かつ正確な情報が反映されるようになります。

参考にした情報源リンク

Go言語のソースコードとドキュメント生成に関する一般的な知識
CgoおよびSWIGの基本的な機能とGoとの連携に関する情報
ファイル拡張子（.c, .m, .s, .cc, .cpp, .cxx）が示すプログラミング言語に関する一般的な知識
Gerrit (Go Change List) の利用方法に関する一般的な知識
コミットメッセージに記載されたCL番号 (60590044, 68580043, 88760043) は、GoのGerritインスタンスで検索可能ですが、直接的な内容の取得は困難でした。しかし、コミットメッセージ自体が十分なコンテキストを提供しています。
mkdoc.shのようなスクリプトがドキュメントを生成する仕組みは、Goプロジェクトの慣習として理解されています。

comemo