[インデックス 19151] ファイルの概要
このコミットは、Go言語の公式ドキュメント doc/asm.html に対する変更です。具体的には、Goアセンブリ言語に関するドキュメントから、古いリンカー 6l の -a フラグに関する記述を削除し、ドキュメントがアセンブリ言語の全機能を網羅しているわけではないことを明確にするための修正が行われました。
コミット
このコミットは、Go言語のツールチェインにおける変更、特に古いリンカー 6l の -a フラグがもはや関連性がなくなったことに伴い、アセンブリ言語のドキュメントを更新するものです。ドキュメントの正確性を向上させ、読者が誤解する可能性のある情報を排除することを目的としています。
GitHub上でのコミットページへのリンク
https://github.com/golang/go/commit/edebe10864982e912e70c7fa1bc56767933f33
元コミット内容
doc/asm.html: remove mention of 6l -a
Also make it clear this is not a complete description of all features.
Fixes #7790.
LGTM=bradfitz
R=golang-codereviews, bradfitz
CC=golang-codereviews
https://golang.org/cl/88300044
変更の背景
この変更の背景には、Go言語のツールチェインの進化があります。コミットが作成された2014年当時、Go 1.5のリリースに向けてツールチェインの大きな変更が進められていました。特に、Go 1.5では、それまでのアーキテクチャ固有のコンパイラ（例: 6g, 8g）やリンカー（例: 6l, 8l）が廃止され、go tool compile や go tool link といった統一されたコマンドに置き換えられました。
6l -a フラグは、この古いリンカー 6l に関連する機能でした。Go 1.5以降、6l コマンド自体が存在しなくなったため、そのフラグに関する記述もドキュメントから削除する必要が生じました。これは、ドキュメントが最新かつ正確な情報を提供し、読者が存在しない機能について混乱するのを避けるための重要なクリーンアップ作業です。
また、コミットメッセージにある Fixes #7790 については、公式のGoイシュートラッカーで直接該当するイシューが見つかりませんでした。これは、内部的なイシュー番号であるか、非常に古い、現在はクローズされたイシューである可能性が考えられます。しかし、文脈から判断すると、このイシューは 6l -a の記述がドキュメントに残っていることの不正確さや、ドキュメントの網羅性に関する誤解を解消するためのものだったと推測されます。
前提知識の解説
- Goアセンブリ言語: Go言語は、パフォーマンスが重要な一部のコードパスでアセンブリ言語を使用する機能を提供しています。Goのアセンブリ言語は、一般的なアセンブリ言語とは異なり、Plan 9アセンブラの構文に基づいています。これは、レジスタの命名規則や命令の記述方法など、独特の記法を持っています。
- Plan 9アセンブラ: Plan 9は、ベル研究所で開発された分散オペレーティングシステムです。Go言語のツールチェインは、その設計思想や一部のツール（アセンブラなど）をPlan 9から継承しています。
doc/asm.htmlは、このPlan 9スタイルのアセンブリ言語の構文とGoにおける使用法を説明するドキュメントです。 6lリンカー: Go 1.5より前のバージョンでは、Goのビルドプロセスにおいて、アーキテクチャごとに異なるコンパイラとリンカーが使用されていました。例えば、6gはAMD64アーキテクチャ用のGoコンパイラ、6lはAMD64アーキテクチャ用のGoリンカーでした。これらのツールは、Goのソースコードを機械語に変換し、実行可能なバイナリを生成する役割を担っていました。doc/asm.html: これはGoプロジェクトの公式ドキュメントの一部であり、Goアセンブリ言語の構文と使用方法について説明しています。Goアセンブリを記述する開発者にとって重要なリソースです。
技術的詳細
このコミットは、doc/asm.html ドキュメントの2つの主要な側面を修正しています。
-
6l -aフラグの記述の削除:- 以前のドキュメントには、リンカー
6lの-aフラグを使用してバイナリの内容を確認する方法が記載されていました。このフラグは、リンク後にバイナリに何が格納されるかを見るためのものでした。 - しかし、Goツールチェインの進化により、
6lコマンド自体が廃止され、go tool linkに置き換えられました。そのため、この-aフラグに関する記述はもはや有効ではなく、読者を誤解させる可能性がありました。 - コミットでは、このセクション全体がHTMLコメントアウトされています。これは、将来的に同様の機能が復活する可能性を考慮し、完全に削除するのではなく、一時的に非表示にするという意図を示唆しています。
- 以前のドキュメントには、リンカー
-
ドキュメントの網羅性に関する明確化:
- ドキュメントの冒頭部分に、「The document is not comprehensive.」（このドキュメントは網羅的ではありません。）という文言が追加されました。
- これは、
doc/asm.htmlがGoアセンブリ言語のすべての側面や機能を詳細に説明しているわけではないことを明確にするためのものです。読者に対して、このドキュメントがクイックアウトラインであり、より深い理解のためにはPlan 9のアセンブリに関するドキュメントなどを参照する必要があることを示唆しています。
これらの変更は、ドキュメントの正確性と有用性を向上させるためのものであり、Goツールチェインの継続的なメンテナンスと改善の一環です。
コアとなるコードの変更箇所
--- a/doc/asm.html
+++ b/doc/asm.html
@@ -8,7 +8,11 @@
<p>
This document is a quick outline of the unusual form of assembly language used by the <code>gc</code>
suite of Go compilers (<code>6g</code>, <code>8g</code>, etc.).
-It is based on the input to the Plan 9 assemblers, which is documented in detail
+The document is not comprehensive.
+</p>
+
+<p>
+The assembler is based on the input to the Plan 9 assemblers, which is documented in detail
<a href="http://plan9.bell-labs.com/sys/doc/asm.html">on the Plan 9 site</a>.
If you plan to write assembly language, you should read that document although much of it is Plan 9-specific.\n This document provides a summary of the syntax and\n@@ -70,6 +74,8 @@ The <code>FUNCDATA</code> and <code>PCDATA</code> directives contain information\n for use by the garbage collector; they are introduced by the compiler.\n </p> \n \n+<!-- Commenting out because the feature is gone but it\'s popular and may come back.\n+\n <p>\n To see what gets put in the binary after linking, add the <code>-a</code> flag to the linker:\n </p>\n@@ -98,6 +104,7 @@ codeblk [0x2000,0x1d059) at offset 0x1000\n ...\n </pre>\n \n+-->\n \n <h3 id=\"symbols\">Symbols</h3>\n \n```
## コアとなるコードの解説
* **行 8-11 の変更**:
* `- It is based on the input to the Plan 9 assemblers, which is documented in detail` が削除され、
* `+ The document is not comprehensive.` と `+ The assembler is based on the input to the Plan 9 assemblers, which is documented in detail` が追加されています。
* これは、ドキュメントの冒頭で、その内容が網羅的ではないことを明確に伝えるための変更です。これにより、読者がこのドキュメントだけでGoアセンブリのすべてを理解できると誤解するのを防ぎます。
* **行 70-104 の変更**:
* `<!-- Commenting out because the feature is gone but it\'s popular and may come back.` と `-->` が追加され、その間に `6l -a` フラグに関する説明と使用例のコードブロックが囲まれています。
* この変更は、`6l -a` フラグがもはや存在しないため、その記述をドキュメントから削除するものです。しかし、完全に削除するのではなく、HTMLコメントとして残すことで、将来的に同様の機能が再導入された場合に備えて、元の情報を保持しています。これは、機能が廃止されたものの、その概念が開発者コミュニティで人気があったり、将来的に再検討される可能性があることを示唆しています。
これらの変更は、Goツールチェインの進化に合わせてドキュメントを最新の状態に保ち、読者にとってより正確で有用な情報を提供することを目的としています。
## 関連リンク
* Go言語公式ドキュメント: [https://golang.org/doc/](https://golang.org/doc/)
* Plan 9アセンブリ言語ドキュメント: [http://plan9.bell-labs.com/sys/doc/asm.html](http://plan9.bell-labs.com/sys/doc/asm.html)
* Go 1.5リリースノート (ツールチェインの変更に関する情報が含まれる可能性があります): [https://golang.org/doc/go1.5](https://golang.org/doc/go1.5) (このコミットの時点ではリリースされていませんが、関連する背景情報として)
## 参考にした情報源リンク
* Go 1.5 Toolchain Changes (Stack Overflow, Goブログなど、`6l` の廃止に関する情報源):
* [https://go.dev/blog/go1.5toolchain](https://go.dev/blog/go1.5toolchain) (Go 1.5のツールチェインに関する公式ブログ記事)
* [https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQGVyN_9JKTZ4dHWS5vJIgKx46RDN8QvwRpVF5Mg7Hn30D1uOLoXb6zmVhPq2dqbING-S2aDdkQavJDdz-shcwFVd_pF4d_0RGQGc20ycNnQ0JjySGrSDbcBvN6gC-xU](https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQGVyN_9JKTZ4dHWS5vJIgKx46RDN8QvwRpVF5Mg7Hn30D1uOLoXb6zmVhPq2dqbING-S2aDdkQavJDdz-shcwFVd_pF4d_0RGQGc20ycNnQ0JjySGrSDbcBvN6gC-xU) (`6l` の廃止に関する検索結果のソース)
* Go Issue Tracker (一般的なGoイシューの検索): [https://github.com/golang/go/issues](https://github.com/golang/go/issues)