はじめに

Rust へのコントリビューションに関心をお寄せいただき、ありがとうございます！ コントリビュートする方法は数多くあり、私たちはそのすべてに感謝しています。

初めてコントリビュートする場合は、walkthrough の章が、典型的なコントリビューションの流れについての良い例になります。

このドキュメントは、網羅的であることを意図したものではありません。 最も有用な事項のクイックガイドとして作られています。 詳細については、 コンパイラをビルドして実行する方法を参照してください。

質問する

質問がある場合は、Rust Zulip サーバーまたは internals.rust-lang.org に投稿してください。 より多くのリソースについては、公式ウェブサイトのチームとワーキンググループの一覧とコミュニティページを参照してください。

念のためお伝えすると、すべてのコントリビューターは私たちの行動規範に従うことが期待されています。

コンパイラチーム（または t-compiler）は通常、Zulip の #t-compiler チャンネルにいます。 コンパイラがどのように動作するかについての質問は、#t-compiler/help で行えます。

ぜひ質問してください！ 多くの人が「専門家の時間を無駄にしている」と感じると報告していますが、 t-compiler の誰もそのようには感じていません。 コントリビューターは私たちにとって重要です。

また、抵抗がなければ、公開トピックを優先してください。そうすることで他の人も 質問と回答を見ることができ、場合によってはこのガイドへ取り込めるかもしれません :)

ヒント: 英語のネイティブスピーカーではなく、文章を書くことに不安がある場合は、翻訳ツールを使って補助してみてください。 ただし、長く複雑な単語を生成する LLM ツールの使用は避けてください。 日々のチームワークでは、理解しやすくするために シンプルで明確な言葉 が最適です。 小さなタイプミスや文法ミスでさえ、あなたをより人間らしく見せることがあり、人々は人間とのほうがうまくつながれます。

専門家

すべての t-compiler メンバーが rustc のすべての部分の専門家であるわけではありません。 これはかなり大きなプロジェクトです。 コンパイラのさまざまな部分について誰が専門知識を持っていそうかを調べるには、 triagebot の割り当てグループを参照してください。 triagebot.toml ファイル内で [assign* から始まるセクションです。 ただし、誰に ping すればよいか分からない場合でも、遠慮なく質問してください。

コンパイラの特定の部分について専門家を見つけるもう 1 つの方法は、最近コミットした人を確認することです。 たとえば、1.68.2 リリース以降に名前解決に最近取り組んだ人を見つけるには、 git shortlog -n 1.68.2.. compiler/rustc_resolve/ を実行できます。 “Rollup merge” で始まるコミットや @bors によるコミットは無視してください （これらのコミットの詳細については、CI コントリビューション手順を参照してください）。

エチケット

質問には、できるだけ多くの有用な情報を含めるよう配慮していただきたいですが、 Rust へのコントリビュートに慣れていない場合、これが難しいことも理解しています。

何の文脈も提供せずに誰かに ping するだけだと少し迷惑になることがあり、 ノイズを生むだけにもなり得ます。そのため、t-compiler の人たちは 1 日に多くの ping を受け取っているという事実に配慮していただくようお願いします。

何に取り組むべきですか？

Rust プロジェクトはかなり大きく、プロジェクトのどの部分が支援を必要としているのか、 また初心者にとって良い出発点なのかを知るのは難しい場合があります。 以下に、推奨される出発点をいくつか示します。

簡単な issue またはメンター付きの issue

どこから始めればよいかを探している場合は、次の issue 検索を確認してください。 これらのラベルの説明については、Triage を参照してください。 関心のある分野に検索を絞り込むこともできます。 例:

• repo:rust-lang/rust-clippy は clippy の issue のみを表示します
• label:T-compiler はコンパイラに関連する issue のみを表示します
• label:A-diagnostics は診断関連の issue のみを表示します

重要な作業や初心者向けの作業のすべてに issue ラベルが付いているわけではありません。 ラベル付けされていない作業を見つける方法については、以下を参照してください。

繰り返し発生する作業

作業の中には、1 人で行うには大きすぎるものがあります。 この場合、コントリビューター間で作業を調整するために「Tracking issue」を用意するのが一般的です。 大きな時間的コミットメントなしに取り組み始めやすい追跡 issue の例をいくつか示します。

• 繰り返し発生する作業項目をここに追加してください。

繰り返し発生する作業をさらに見つけた場合は、遠慮なくここに追加してください！

Clippy の issue

Clippy プロジェクトは、コントリビューションのプロセスを可能な限り新規参加者にとって親しみやすいものにするため、 長い時間をかけてきました。 プロセスとコンパイラ内部に慣れるために、まずこれに取り組むことを検討してください。

開始方法の手順については、Clippy コントリビューションガイドを参照してください。

診断関連の issue

多くの診断関連の issue は自己完結しており、コンパイラに関する詳細な背景知識を必要としません。 診断関連の issue の一覧はこちらで確認できます。

放棄されたプルリクエストを引き継ぐ

コントリビューターがプルリクエストを送信したものの、後でそれに取り組む十分な時間がないことに気付いたり、 単純にもう関心がなくなったりすることがあります。 そのような PR は最終的にクローズされることが多く、S-inactive ラベルが付けられます。 これらの PR のいくつかを調べて、作業を引き継いでみることができます。 そのような PR の一覧はこちらで確認できます。

その間に PR が別の方法で実装されている場合は、S-inactive ラベルを 削除する必要があります。 そうでなく、変更にまだ関心があるように見える場合は、 最新の main ブランチの上にプルリクエストをリベースし、新しい プルリクエストを送信して、その機能の作業を続けることができます。

テストを書く

解決済みだが回帰テストがない issue には、E-needs-test ラベルが付けられます。 単体テストを書くことは、リスクが低く、 優先度も低めのタスクであり、新しいコントリビューターがテスト基盤と コントリビューションワークフローに慣れるための素晴らしい機会を提供します。 needs test issue の一覧はこちらで確認できます。

std（標準ライブラリ）へコントリビュートする

std-dev-guideを参照してください。

他の Rust プロジェクトにコードで貢献する

rust-lang/rust リポジトリ以外にも、cargo、miri、rustup など、貢献できるプロジェクトは数多くあります。

これらのリポジトリには、それぞれ独自のコントリビューションガイドラインや手順がある場合があります。 その多くはワーキンググループによって管理されています。 詳細については、それらのリポジトリの README にあるドキュメントを参照してください。

その他の貢献方法

他にも貢献できる方法は数多くあります。特に、巨大な rust-lang/rust コードベースにいきなり飛び込むことに不安がある場合に有用です。

以下のタスクは、多くの背景知識がなくても実行でき、しかも非常に役立ちます。

• ドキュメントを書く: 少し勇気を出してみたい場合は、 コードの一部を読んで、その doc コメントを書いてみることができます。 これは、有用な成果物を生み出しながら、コンパイラの一部を学ぶ助けになります！
• issue をトリアージする: issue を分類し、再現し、最小化することは、Rust メンテナーにとって非常に役立ちます。
• 作業領域: Rust 関連の多種多様なものについて、多くの作業領域があります。
• users.rust-lang.org や Stack Overflow で質問に回答する。
• RFC プロセスに参加する。
• 要望されているコミュニティライブラリを見つけ、それを構築し、 Crates.io に公開する。 口で言うほど簡単ではありませんが、非常に、非常に価値があります！

クローンとビルド

“コンパイラをビルドして実行する方法”を参照してください。

コントリビューターの手順

このセクションは “コントリビューションの手順” の章に移動しました。

その他のリソース

このセクションは “このガイドについて” の章に移動しました。

このガイドについて

このガイドは、rustc（Rust コンパイラ）がどのように動作するかを文書化するのに役立てること、 また新しいコントリビューターが rustc 開発に参加しやすくすることを目的としています。

このガイドはいくつかの部で構成されています。

1. rustc のビルドとデバッグ: どのような形でコントリビュートする場合にも役立つはずの情報、 すなわちビルド、デバッグ、プロファイリングなどについての情報が含まれています。
2. Rust へのコントリビュート: どのような形でコントリビュートする場合にも役立つはずの情報、 すなわちコントリビューションの手順、git と GitHub の使用、機能の安定化などについての情報が含まれています。
3. ブートストラップ: Rust コンパイラが以前のバージョンを使って自身をビルドする仕組みについて説明します。これには、 ブートストラッププロセスの概要とデバッグ方法の紹介が含まれます。
4. 高レベルなコンパイラアーキテクチャ: コンパイラの高レベルなアーキテクチャとコンパイルプロセスの各段階について説明します。
5. ソースコード表現: ユーザーから受け取った生のソースコードを、 コンパイラが扱いやすいさまざまな形式へ変換するプロセスについて説明します。
6. 支援インフラストラクチャ: コマンドライン引数の規約、rustc_driver や rustc_interface のようなコンパイラのエントリーポイント、エラーと lint の設計および実装を扱います。
7. 解析: コードのさまざまな性質をチェックし、コンパイルプロセスの後続段階（例: 型チェック）に情報を提供するために コンパイラが使用する解析について説明します。
8. MIR からバイナリへ: リンク済みの実行可能な機械語コードがどのように生成されるか。
9. 末尾に、有用な参考情報を含む付録があります。 用語集を含め、異なる情報を扱うものがいくつかあります。

絶え間ない変化

rustc は実際のプロダクション品質のプロダクトであり、 かなりの数のコントリビューターによって継続的に作業されていることを念頭に置いてください。 そのため、コードベースの変更や技術的負債も相応に存在します。 加えて、このガイド全体で論じられている多くのアイデアは、 まだ完全には実現されていない理想化された設計です。 これらすべてのため、このガイドをあらゆる点で完全に最新の状態に保つことは非常に困難です！

もちろん、このガイド自体もオープンソースであり、 ソースは GitHub リポジトリでホストされています。 ガイドに誤りを見つけた場合は、issue を提出してください。 さらによいのは、修正を含む PR を開くことです！

このガイドにコントリビュートする場合は、 このガイドのドキュメント作成に関する対応する小節を参照してください。

「『すべての条件づけられたものは無常である』―― これを智慧によって見るとき、人は苦しみから離れる。」 ダンマパダ、第277偈

情報を見つけるその他の場所

現在あなたが読んでいるこのガイドには、 コンパイラのさまざまな部分がどのように動作するか、 そしてコンパイラにどのようにコントリビュートするかについての情報が含まれています。

次のサイトも役立つかもしれません。

• rustc API docs – コンパイラ、devtools、内部ツール向けの rustdoc ドキュメント
• Forge – Rust インフラストラクチャ、チーム手順などに関するドキュメントが含まれています
• compiler-team – Rust コンパイラチームの拠点であり、チーム手順、 アクティブなワーキンググループ、チームカレンダーについての説明があります。
• std-dev-guide – 標準ライブラリを開発するための同様のガイド。
• rust-analyzer book – rust-analyzer のドキュメント。
• The t-compiler Zulip
• Rust Internals フォーラム。質問したり、Rust の内部について議論したりする場所です
• Rust リファレンス。Rust の内部について特に述べているわけではありませんが、 それでも非常に優れたリソースです
• 古くなってはいますが、Tom Lee の優れたブログ記事は非常に役立ちます
• Rust Compiler Testing Docs
• @bors については、このチートシートが役立ちます
• プログラミング中、Google はいつでも役に立ちます。 すべての Rust ドキュメントを検索（標準ライブラリ、 コンパイラ、各種書籍、リファレンス、ガイド）して、言語やコンパイラに関する 情報をすばやく見つけることができます。
• また、Rustdoc に組み込まれた検索機能を使用して、見ている crate 内の 型や関数に関するドキュメントを見つけることもできます。 型シグネチャでも検索できます！ たとえば、* -> vec を検索すると、Vec<T> を返す関数がすべて見つかるはずです。 ヒント: Rustdoc の任意のページで ? を入力すると、さらに多くのヒントやキーボードショートカットを確認できます！

コンパイラをビルドして実行する方法

コンパイラは x.py というツールを使用してビルドされます。 これを実行するには Python がインストールされている必要があります。

クイックスタート

コンパイラを実行できるようにするための、より簡潔なクイックスタートについては、クイックスタートを参照してください。

ソースコードを取得する

メインのリポジトリは rust-lang/rust です。 これには、コンパイラ、 標準ライブラリ（core、alloc、test、proc_macro などを含む）、 および多数のツール（例: rustdoc、ブートストラップ基盤など）が含まれています。

rustc に取り組む最初のステップは、リポジトリをクローンすることです。

git clone https://github.com/rust-lang/rust.git
cd rust

リポジトリを部分クローンする

リポジトリのサイズが大きいため、遅いインターネット接続でクローンすると長い時間がかかることがあり、 すべてのファイルとディレクトリの完全な履歴を保存するためのディスク容量も必要です。 代わりに、git に 部分クローン を実行するよう指示できます。これにより、現在のファイル内容のみを完全に取得し、 たとえば履歴をさかのぼるときに、追加のファイル内容を自動的に取得します。 すべての git コマンドは通常どおり動作し続けますが、まだ読み込まれていない履歴上の地点を参照するには インターネット接続が必要になります。

git clone --filter='blob:none' https://github.com/rust-lang/rust.git
cd rust

注: このリンク では、この種のチェックアウトについてより詳しく説明しており、shallow clone などの 他のモードとの比較も行っています。

リポジトリを shallow clone する

部分クローンより古い代替手段として、代わりにリポジトリを shallow clone する方法があります。 そのためには、git clone コマンドで --depth N オプションを使用できます。 これは、git に「shallow clone」を実行するよう指示し、リポジトリをクローンしますが、 最後の N 個のコミットまで履歴を切り詰めます。

--depth 1 を渡すと、git はリポジトリをクローンしますが、履歴を main ブランチ上の最新の コミットまで切り詰めます。これは通常、ソースコードの閲覧やコンパイラのビルドには十分です。

git clone --depth 1 https://github.com/rust-lang/rust.git
cd rust

注: shallow clone では、実行できる git コマンドが制限されます。 コンパイラに取り組み、貢献するつもりであれば、 通常は上記のようにリポジトリを完全にクローンするか、 代わりに部分クローンを実行することが推奨されます。

たとえば、git bisect と git blame にはコミット履歴へのアクセスが必要なため、 リポジトリが --depth 1 でクローンされている場合は動作しません。

x.py とは何か？

x.py は rust リポジトリのビルドツールです。 ドキュメントのビルド、テストの実行、コンパイラと標準ライブラリのビルドを行えます。

この章では、生産的に作業するための基本に焦点を当てていますが、 x.py についてさらに学びたい場合は、この章を読んでください。

また、x.py ではなく x を使用することが推奨されます。その理由は次のとおりです。

./x は、すべてのシステムで動作する可能性が最も高いです（Unix では Python バージョン検出を行うシェルスクリプトを実行し、 Windows ではおそらく powershell スクリプトを実行します。多くの場合単に ファイルをエディタで開いてしまう ./x.py よりも、壊れにくいのは確かです）。¹

（x.ps1 のような、プラットフォーム関連のスクリプトは x.py の周辺にあります）

これは絶対的なものではないことに注意してください。 たとえば、Win10 上の VSCode で Nushell を使用している場合、 x または ./x と入力しても、プログラムが起動されるのではなく、依然として x.py がエディタで開かれます。

このガイドの残りの部分では、x.py を直接ではなく x を使用します。 次のコマンドは、

./x check

次のように置き換えることができます。

./x.py check

x.py を実行する

x.py コマンドは、ほとんどの Unix システムで次の形式で直接実行できます。

./x <subcommand> [flags]

これは、ドキュメントと例が x.py を実行していると想定している方法です。 いくつかの代替方法は次のとおりです。

# 必要な `python3` コマンドがない場合の Unix シェルで
./x <subcommand> [flags]

# Windows Powershell で（powershell がスクリプトを実行するように構成されている場合）
./x <subcommand> [flags]
./x.ps1 <subcommand> [flags]

# Windows コマンド プロンプトで（.py ファイルが Python を実行するように構成されている場合）
x.py <subcommand> [flags]

# Python を自分で実行することもできます。例:
python x.py <subcommand> [flags]

Windows では、Powershell コマンドによって次のようなエラーが表示される場合があります。

PS C:\Users\vboxuser\rust> ./x
./x : File C:\Users\vboxuser\rust\x.ps1 cannot be loaded because running scripts is disabled on this system. For more
information, see about_Execution_Policies at https://go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:1
+ ./x
+ ~~~
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

powershell がローカルスクリプトを実行できるようにすることで、このエラーを回避できます。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

x.py を少し便利に実行する

src/tools/x には、x.py をラップする x というバイナリがあります。 これが行うことは x.py の実行だけですが、システム全体にインストールでき、チェックアウトの任意のサブディレクトリから実行できます。 また、使用する適切なバージョンの python も検索します。

cargo install --path src/tools/x でインストールできます。

これが別のグローバルにインストールされたバイナリユーティリティであることを明確にしておくと、これは x.py とは何か セクションで説明したものに似ていますが、 プラットフォーム関連のスクリプトを実行するためにシェルを呼び出すのではなく、 独立したプロセスとして動作して x.py を実行します。

bootstrap.toml を作成する

まず、./x setup を実行して compiler のデフォルトを選択します。 これにより、いくつかの初期化が行われ、妥当なデフォルトを備えた bootstrap.toml が作成されます。 別のデフォルトを使用する場合（コンパイラ以外の rust の領域、 たとえば rustdoc に貢献したい場合には、おそらくそうすることになるでしょう）、 そのデフォルトに関する情報（src/bootstrap/defaults にあります）を必ず読んでください。 他のデフォルトではビルドプロセスが異なる場合があります。

あるいは、bootstrap.toml を手で書くこともできます。 利用可能なすべての設定とそれらの働きについては、bootstrap.example.toml を参照してください。 変更する一般的な設定については、src/bootstrap/defaults を参照してください。 すでに rustc をビルド済みで、LLVM に関連する設定を変更した場合、その後の設定変更を有効にするには ./x clean --all を実行しなければならないことがあります。 ./x clean では LLVM は再ビルドされないことに注意してください。

一般的な x コマンド

ここでは、rustc、std、rustdoc、およびその他のツールで作業する際に 最もよく使われる x コマンドの基本的な呼び出しを示します。

記載されているとおり、これらのコマンドは妥当な出発点です。 ただし、本格的な開発作業のために学んでおく価値のある追加のオプションや引数が、 それぞれにあります。 特に、./x build と ./x test には、 コードの一部だけをコンパイルまたはテストする方法が多数用意されており、多くの時間を節約できます。

また、x は compiler、library、 および src/tools ディレクトリに対するあらゆる種類のパスサフィックスをサポートしていることにも注意してください。 そのため、x test src/tools/tidy の代わりに単に x test tidy を実行できます。 また、x build library/std の代わりに x build std を実行できます。

詳細については、テスト と rustdoc の章を参照してください。

コンパイラをビルドする

ビルドには比較的大きなストレージ容量が必要になることに注意してください。 コンパイラをビルドするには、10 または 15 ギガバイト以上を利用できるようにしておくとよいでしょう。

bootstrap.toml を作成したら、x を実行する準備が整います。 ここには多くのオプションがありますが、ローカルコンパイラをビルドする際の おそらく最適な「定番」コマンドから始めましょう。

./x build library

このコマンドが行うことは次のとおりです。

• stage0 コンパイラと stage0 std を使用して rustc をビルドします。
• 直前にビルドされた stage1 コンパイラで library（標準ライブラリ）をビルドします。
• stage1 コンパイラと stage1 標準ライブラリを含む、動作する stage1 sysroot を組み立てます。

この最終成果物（stage1 コンパイラ + そのコンパイラを使用してビルドされた libs）が、 他の Rust プログラムをビルドするために必要なものです（#![no_std] または #![no_core] を使用する場合を除きます）。

stage1 std のビルドがボトルネックになることにおそらく気づくでしょうが、 心配はいりません。（ハック的な）回避策があります… std の再ビルドを避けるセクションを参照してください。

完全なビルドが必要ない場合もあります。 メソッド名の変更や、何らかの関数のシグネチャ変更のような、 「型に基づくリファクタリング」を行う場合は、代わりに ./x check を使用すると、はるかに高速にビルドできます。

このコマンド全体で得られるのは、完全な rustc ビルドの一部だけであることに注意してください。 完全な rustc ビルド（./x build --stage 2 rustc で得られるもの）には、さらにかなり多くの手順があります。

• stage1 コンパイラで rustc をビルドします。
  • ここで生成されるコンパイラは「stage2」コンパイラと呼ばれ、前のコマンドで得られた stage1 std を使用します。
• stage2 コンパイラで librustdoc とその他多数のものをビルドします。

これを行う必要はほとんどありません。

特定のコンポーネントをビルドする

標準ライブラリで作業している場合、おそらく他のすべてのデフォルトコンポーネントをビルドする必要はありません。 代わりに、次のように名前を指定して特定のコンポーネントをビルドできます。

./x build --stage 1 library

x setup の実行時に library プロファイルを選択した場合は、--stage 1 を省略できます（これが デフォルトです）。

ツールをビルドしたい場合は、次を使用できます。

./x build src/tools/cargo

ツールのテストに関するセクションも確認できます。

rustup ツールチェーンを作成する

rustc のビルドに成功すると、build ディレクトリ内に多数のファイルが作成されます。 生成された rustc を実際に実行するには、rustup ツールチェーンを作成することを推奨します。 以下に示す最初のコマンドは、上記の手順でビルドされた stage1 ツールチェーンを stage1 という名前で作成します。 2 番目のコマンドは、stage1 コンパイラを使用して stage2 ツールチェーンを作成します。 これは将来、テストスイート全体を実行する場合に必要になりますが、 このページではビルドされません。 stage2 のビルドは stage1 の場合と同じ ./x build コマンドで行いますが、 代わりにステージが 2 であることを指定します。

rustup toolchain link stage1 build/host/stage1
rustup toolchain link stage2 build/host/stage2

これで、ビルドした rustc をツールチェーン経由で実行できます。 -vV を付けて実行すると、ローカル環境からのビルドであることを示す -dev で終わる バージョン番号が表示されるはずです。

$ rustc +stage1 -vV
rustc 1.48.0-dev
binary: rustc
commit-hash: unknown
commit-date: unknown
host: x86_64-unknown-linux-gnu
release: 1.48.0-dev
LLVM version: 11.0

rustup ツールチェーンは、build ディレクトリ内でコンパイルされた指定のツールチェーンを指すため、 そのツールチェーン/ステージに対して x build または x test が実行されるたびに、 rustup ツールチェーンも更新されます。

注意: ビルドしたツールチェーンには cargo が含まれていません。 この場合、rustup は インストール済みの nightly、beta、または stable ツールチェーンの cargo の使用にフォールバックします （この順序で）。 不安定な cargo フラグを使用する必要がある場合は、まだであれば必ず rustup install nightly を実行してください。 カスタムツールチェーンに関する rustup ドキュメントを参照してください。

注意: rust-analyzer と IntelliJ Rust プラグインは、proc macros を扱うために rust-analyzer-proc-macro-srv というコンポーネントを使用します。 プロジェクトでカスタムツールチェーンを使用するつもりがある場合 （例: rustup override set stage1 経由）、このコンポーネントを ビルドするとよいでしょう。

./x build proc-macro-srv-cli

クロスコンパイル用のターゲットをビルドする

他のターゲット向けにクロスコンパイルできるコンパイラを生成するには、 任意の数の target フラグを x build に渡します。 たとえば、ホストプラットフォームが x86_64-unknown-linux-gnu で、 クロスコンパイルターゲットが wasm32-wasip1 の場合は、次のようにビルドできます。

./x build --target x86_64-unknown-linux-gnu,wasm32-wasip1

生成されるコンパイラが proc macros やビルドスクリプトを含む crate をビルドできるようにしたい場合は、 ホストプラットフォーム（この場合は x86_64-unknown-linux-gnu）のターゲットサポートを 明示的にビルドする必要があることに注意してください。

x build にフラグを渡さずに常に他のターゲット向けにビルドしたい場合は、 次のように bootstrap.toml の [build] セクションで設定できます。

build.target = ["x86_64-unknown-linux-gnu", "wasm32-wasip1"]

一部のターゲット向けにビルドするには、外部依存関係がインストールされている必要がある点に注意してください （例: musl ターゲットをビルドするには、musl のローカルコピーが必要です）。 ターゲット固有の設定（例: musl のローカルコピーへのパス）は、 bootstrap.toml で指定する必要があります。 ターゲット固有の設定キーについては、bootstrap.example.toml を参照してください。

ターゲットをビルドするために必要な完全な設定例については、 rustc book にアクセスし、 左側の「Platform Support」見出しの下にある任意のターゲットを選択して、 そのターゲット用のコンパイラをビルドすることに関連するセクションを参照してください。 rustc book に対応するページがないターゲットについては、 Rust インフラストラクチャ自体がクロスコンパイルのセットアップと設定に使用している Dockerfile を調べる と役立つ場合があります。

rustup ツールチェーンを作成する前のセクションの手順に従っている場合、 コンパイラをビルドしたら、次のようにクロスコンパイルに使用できるようになります。

cargo +stage1 build --target wasm32-wasip1

その他の x コマンド

他にも便利な x コマンドがいくつかあります。 それらの一部については、他のセクションで詳しく説明します。

• ビルド関連:
  • ./x build – stage 1 コンパイラを使用してすべてをビルドします。 std までだけではありません
  • ./x build --stage 2 – rustdoc を含め、stage 2 コンパイラですべてをビルドします
• テストの実行（詳細については テストの実行に関するセクション を参照してください）:
  • ./x test library/std – std のユニットテストと統合テストを実行します
  • ./x test tests/ui – ui テストスイートを実行します
  • ./x test tests/ui/const-generics - ui テストスイートの const-generics/ サブディレクトリにあるすべてのテストを実行します
  • ./x test tests/ui/const-generics/const-types.rs - ui テストスイートの 単一のテスト const-types.rs を実行します

ビルドディレクトリのクリーンアップ

場合によっては最初からやり直す必要がありますが、通常はそうではありません。 これを実行する必要がある場合、bootstrap が正常に動作していない可能性が非常に高いため、 何が問題なのかについてバグを報告するべきです。 すべてをクリーンアップする必要がある場合は、1 つのコマンドを実行するだけで済みます！

./x clean

rm -rf build でも機能しますが、その場合は LLVM を再ビルドする必要があり、 高速なコンピューターでも長い時間がかかることがあります。

ディスク容量に関する注意

コンパイラをビルドするには（特に stage 1 を超える場合）、かなりの空きディスク 容量が必要になることがあり、およそ 100GB 程度になる可能性があります。 これは、rust-analyzer 用に別のビルドディレクトリ（例: build-rust-analyzer）がある場合に さらに大きくなります。これは、各ユーザーに 設定されたディスク クォータ がある dev-desktop で発生しやすいですが、ローカル開発にも当てはまります。 場合によっては、次のことが必要になることがあります。

• build/ ディレクトリを削除する。
• build-rust-analyzer/ ディレクトリを削除する（別の rust-analyzer ビルドディレクトリがある場合）。
• cargo-bisect-rustc を使用している場合は、不要なツールチェーンをアンインストールする。 インストールされているツールチェーンは rustup toolchain list で確認できます。

1. issue#1707 ↩

クイックスタート

これは、コンパイラを動作させるためのクイックスタートガイドです。各手順の詳細については、この章の他のページを参照してください。

まず、リポジトリをクローンします。

git clone https://github.com/rust-lang/rust.git
cd rust

コンパイラをビルドするときは、cargo を直接使うのではなく、“x” というラッパーを使います。これは ./x で呼び出します。

ビルド用の設定を作成する必要があります。適切なデフォルト設定を作成するには ./x setup を使用します。

./x setup

次に、コンパイラをビルドできます。コンパイラ、標準ライブラリ、およびいくつかのツールをビルドするには ./x build を使用します。また、単にチェックするだけであれば ./x check も使用できます。これらのコマンドはいずれも、特定のコンポーネントやパスを引数として受け取ることができます。たとえば、コンパイラだけをチェックするには ./x check compiler を使用します。

./x build

標準ライブラリのコンパイル方法に影響しないコンパイラの変更を行う場合（たとえば、エラーメッセージの変更など）は、再コンパイルを避けるために --keep-stage-std 1 を使用してください。

コンパイラと標準ライブラリをビルドすると、動作するコンパイラツールチェーンが手元にできます。リンクすることで、rustup から使用できます。

rustup toolchain link stage1 build/host/stage1

注: ./x setup tools を使用した場合、デフォルトのステージは 1 ではなく 2 に設定されます。コマンドをそれに合わせて調整してください。

rustup toolchain link stage2 build/host/stage2

これで、ビルドにリンクされた stage1 という名前のツールチェーンができました。これを使ってコンパイラをテストできます。

rustc +stage1 testfile.rs

変更を行った後は、./x test でコンパイラのテストスイートを実行できます。

./x test はテストスイート全体を実行しますが、これは遅く、通常は必要なものではありません。通常、コンパイラを変更した後に必要なのは ./x test tests/ui です。これは、特定のテストファイルに対してコンパイラを呼び出し、その出力を確認するすべての UI テストをテストします。

./x test tests/ui

変更を行い、新しい出力で .stderr ファイルを更新したい場合は、--bless を使用してください。

おめでとうございます。これでコンパイラに変更を加える準備ができました！ さらに質問がある場合は、章全体に答えが含まれているかもしれません。含まれていない場合は、Zulip で気軽に助けを求めてください。

VSCode、Vim、Emacs、Helix、または Zed を使用している場合、./x setup はエディター設定をセットアップするかどうかを尋ねます。詳細については、推奨ワークフローを確認してください。

前提条件

依存関係

rust-lang/rust の INSTALL を参照してください。

ハードウェア

ビルドするにはインターネット接続が必要です。 ブートストラップ処理では、 git サブモジュールの更新とベータコンパイラのダウンロードを行います。 非常に高速である必要はありませんが、高速であれば役に立ちます。

厳密なハードウェア要件はありませんが、コンパイラのビルドは 計算負荷が高いため、より高性能なマシンのほうが役に立ちます。また、 Raspberry Pi でビルドしようとすることはお勧めしません！ 以下を推奨します。

• 30GB 以上の空きディスク容量。 そうでない場合は、インクリメンタルキャッシュを継続的に削除する必要があります。 容量は多いほどよいです。コンパイラは少々 容量を消費しがちです。これは私たちも認識している問題です。
• 8GB 以上の RAM
• 2 コア以上。 コア数が多いと非常に役に立ちます。 10 個、20 個、あるいはそれ以上でも多すぎることはありません！

より高性能なマシンでは、ビルドがはるかに速くなります。 マシンの性能があまり高くない場合、 よく使われる戦略は、ローカルマシンでは ./x check のみを使い、 PR ブランチにプッシュしたときに CI ビルドで変更をテストさせることです。

そこそこ高性能なノート PC でも、コンパイラのビルドには 30 分以上かかります。 LLVM をソースからビルドしなくて済むように、 CI からダウンロードすることをお勧めします （こちらを参照）。

cargo と同様に、ビルドシステムは可能な限り多くのコアを使用します。 これにより、メモリ不足になることがあります。 -j を使用して、同時実行ジョブ数を調整できます。 フルビルドに約 45 分から 1 時間を超える時間がかかる場合、 おそらくほとんどの時間をメモリのスワップイン・スワップアウトに費やしています。 -j1 を試してください。

空きディスク容量があまり多くない場合は、 インクリメンタルコンパイルを無効にしたいかもしれません（こちらを参照）。 これによりコンパイルに 時間がかかるようになります（特にリベース後）が、 インクリメンタルキャッシュによる大量の容量消費を抑えられます。

推奨ワークフロー

完全なブートストラップ処理にはかなり時間がかかります。 作業を楽にするための提案をいくつか示します。

pre-push フックのインストール

CI は、コード品質を確保するための内部ツールである tidy に合格しない場合、ビルドを自動的に失敗させます。 必要であれば、各 push 時に ./x test tidy を自動的に実行し、コードが基準を満たしていることを確認する Git hook をインストールできます。 フックが失敗した場合は、./x test tidy --bless を実行して変更をコミットしてください。 後で pre-push の動作が望ましくないと判断した場合は、.git/hooks 内の pre-push ファイルを削除できます。

ビルド済みの git フックは src/etc/pre-push.sh にあります。 これを .git/hooks フォルダーに pre-push としてコピーできます（.sh 拡張子は付けません！）。

./x setup の実行手順の一部としてフックをインストールすることもできます！

設定拡張

異なるタスクに取り組む場合、異なるブートストラップ設定を切り替える必要があるかもしれません。 将来の使用に備えて古い設定を保持しておきたい場合もあります。 しかし、生の設定値を ランダムなファイルに保存して手動でコピー＆ペーストすると、特にさまざまな設定の長い履歴がある場合、すぐに煩雑になります。

複数の設定の管理を簡単にするために、設定拡張を作成できます。

たとえば、cross.toml という名前の単純な設定ファイルを作成できます。

[build]
build = "x86_64-unknown-linux-gnu"
host = ["i686-unknown-linux-gnu"]
target = ["i686-unknown-linux-gnu"]


[llvm]
download-ci-llvm = false

[target.x86_64-unknown-linux-gnu]
llvm-config = "/path/to/llvm-19/bin/llvm-config"

次に、これを bootstrap.toml に含めます。

include = ["cross.toml"]

拡張の中に拡張を再帰的に含めることもできます。

注: include フィールドでは、上書きロジックは右から左の順序に従います。 たとえば、 include = ["a.toml", "b.toml"] では、拡張 b.toml が a.toml を上書きします。 また、親の拡張は常に内側の拡張を上書きします。

rust-analyzer を rustc 用に設定する

“library” ツリーのチェック

“library” ツリーのチェックには stage1 コンパイラが必要であり、コンピューターによっては重い処理になる場合があります。 このため、ブートストラップには --skip-std-check-if-no-download-rustc というフラグがあり、rust.download-rustc が利用できない場合は “library” ツリーのチェックをスキップします。 rust-analyzer によってコンピューターに重い負荷をかけるのを避けたい場合は、rust-analyzer 設定の ./x check コマンドに --skip-std-check-if-no-download-rustc フラグを追加できます。

プロジェクトローカルの rust-analyzer セットアップ

rust-analyzer は、ファイルを保存するたびにコードのチェックとフォーマットを行うのに役立ちます。 デフォルトでは、rust-analyzer は cargo check コマンドと rustfmt コマンドを実行しますが、 rustc に取り組む場合、これらのツールのより適したバージョンを使用するように、これらのコマンドを上書きできます。 カスタムセットアップにより、rust-analyzer はソースのチェックに ./x check を使用し、 フォーマットには stage 0 の rustfmt を使用できます。

デフォルトの rust-analyzer.check.overrideCommand コマンドラインは、リポジトリ内のすべての クレートとツールをチェックします。 特定の部分に取り組んでいる場合は、 チェック時間を節約するために、作業中の部分だけをチェックするようにコマンドを上書きできます。 たとえば、コンパイラに取り組んでいる場合は、 コンパイラ部分だけをチェックするためにコマンドを x check compiler --json-output に上書きできます。 利用可能な部分を確認するには、x check --help --verbose を実行できます。

./x setup editor を実行すると、サポートされているエディターのいずれかについて、プロジェクトローカルの LSP 設定 ファイルを作成するよう求められます。 ./x setup の実行手順の一部として設定ファイルを作成することもできます。

rust-analyzer に別のビルドディレクトリを使用する

デフォルトでは、rust-analyzer がチェックまたはフォーマットコマンドを実行する場合、手動のコマンドラインビルドと 同じビルドディレクトリを共有します。 これは、次の 2 つの理由で不便な場合があります。

• 各ビルドはビルドディレクトリをロックし、もう一方を待機させるため、rust-analyzer がバックグラウンドで コマンドを実行している間は、コマンドラインビルドを実行できなくなります。
• コンパイラフラグやその他の設定の競合により、いずれかのビルドが以前にビルドされた アーティファクトを削除してしまうリスクが高まり、場合によっては追加の再ビルドが必要になります。

これらの問題を回避するには、次のようにします。

• エディターの rust-analyzer 設定内のすべてのカスタム x コマンドに --build-dir=build-rust-analyzer を追加します。 （必要に応じて別のディレクトリ名を選んでもかまいません。）
• rust-analyzer.rustfmt.overrideCommand 設定を変更して、別のビルドディレクトリ内の rustfmt のコピーを指すようにします。
• rust-analyzer.procMacro.server 設定を変更して、別のビルドディレクトリ内の rust-analyzer-proc-macro-srv のコピーを指すようにします。

コマンドラインビルドと rust-analyzer に別々のビルドディレクトリを使用するには、 追加のディスク容量が必要です。

Visual Studio Code

./x setup editor で vscode を選択すると、Visual Studio code を設定する .vscode/settings.json ファイルを作成するよう求められます。 推奨される rust-analyzer 設定は src/etc/rust_analyzer_settings.json にあります。

保存時に ./x check を実行するのが不便な場合、VS Code では代わりに Build Task を使用できます。

// .vscode/tasks.json
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "./x check",
            "command": "./x check",
            "type": "shell",
            "problemMatcher": "$rustc",
            "presentation": { "clear": true },
            "group": { "kind": "build", "isDefault": true }
        }
    ]
}

Neovim

Neovim ユーザーには、いくつかの選択肢があります。

1. 最も簡単な方法は neoconf.nvim を使用することですが、これは 非推奨の require('lspconfig') API を使用しており、neovim 0.11+ で警告が表示されます。
2. coc.nvim を使用することも別の選択肢ですが、node.js がインストールされている必要があります。
3. rust-analyzer 設定を読み込むためのカスタムスクリプトを使用します。

neoconf.nvim

neoconf.nvim により、ネイティブ LSP でプロジェクトローカルの設定 ファイルを使用できます。 使用方法の手順は以下のとおりです。 これらは rust-analyzer がすでに Neovim で設定されていることを必要とする点に注意してください。 その手順は こちら にあります。

1. まずプラグインをインストールします。 これは README の手順に従って行えます。
2. ./x setup editor を実行し、vscode を選択して .vscode/settings.json ファイルを作成します。 このファイルが検出されると、プロジェクトが開かれたときに neoconf は rust-analyzer 設定を自動的に読み取り、更新できます。

coc.nvim

coc.nvim を使用している場合は、./x setup editor を実行して vim を選択し、 .vim/coc-settings.json を作成できます。 設定は :CocLocalConfig で編集できます。 推奨設定は src/etc/rust_analyzer_settings.json にあります。

カスタム LSP 設定

neovim 0.11+ を実行している場合は、 nvim-lspconfig とカスタムスクリプトだけで rust-analyzer を設定できます。

1. rust-analyzer LSP がセットアップされていることを確認します
2. 次の内容で $HOME/.config/nvim/after/plugged/rust_analyzer.lua を作成します。

```lua
-- 上書きする前に、nvim-lspconfig/lsp/rust_analyzer.lua からデフォルト関数を取得します。
-- このファイルは after/plugin にあるため、nvim-lspconfig がすでに初期化済みであることが保証されます。
local default_root_dir = vim.lsp.config["rust_analyzer"].root_dir
local default_before_init = vim.lsp.config["rust_analyzer"].before_init

vim.lsp.config("rust_analyzer", {
    cmd = { "rust-analyzer" },
    filetypes = { "rust" },
    -- rust-lang/rust をサポートするには、rust リポジトリ内にいることを検出し、cargo プロジェクトのルートではなく
    -- git ルートを使用する必要があります。
    root_dir = function(bufnr, on_dir)
        local git_root = vim.fs.root(bufnr, { ".git" })
        if git_root then
            if vim.uv.fs_stat(vim.fs.joinpath(git_root, "src/etc/rust_analyzer_zed.json")) then
                on_dir(git_root)
                return
            end
        end
        -- rust-lang/rust に一致しないものについては、デフォルトの root_dir にフォールバックします
        default_root_dir(bufnr, on_dir)
    end,
    before_init = function(init_params, config)
        -- rust-lang/rust 内にいる場合は、特別な rust-analyzer 設定を使用する必要があります。
        local settings = vim.fs.joinpath(config.root_dir, "src/etc/rust_analyzer_zed.json")
        if vim.uv.fs_stat(settings) then
            local file = io.open(settings)
            -- nvim 0.12+ はコメントをサポートしています。それ以外の場合は content:gsub("//[^\n]*", "") が必要です。
            local json = vim.json.decode(file:read("*a"), { skip_comments = true })
            file:close()
            config.settings["rust-analyzer"] = vim.tbl_deep_extend(
                "force", -- 競合がある場合は特別な設定で上書きします。
                config.settings["rust-analyzer"] or {},
                json.lsp["rust-analyzer"].initialization_options
            )
        end
        default_before_init(init_params, config)
    end,
})

vim.lsp.enable("rust_analyzer")

上述のビルドタスクを使用したい場合は、自分の設定内で独自のコマンドを作成するか、 overseer.nvim のようなプラグインをインストールできます。 これは VSCode の task.json ファイルを読み取る ことができ、上記と同じ手順に従えます。

Emacs

Emacs は、Eglot を通じて プロジェクトローカル設定による rust-analyzer のサポートを提供します。 Eglot を rust-analyzer とともにセットアップする手順は こちらにあります。 Rust 開発全般向けに Emacs と Eglot のセットアップが済んだら、 ./x setup editor を実行して emacs を選択できます。これにより、 Eglot 向けの推奨設定を含む .dir-locals.el を作成するよう促されます。 推奨設定は src/etc/rust_analyzer_eglot.el にあります。 プロジェクト固有の Eglot 設定について詳しくは、 マニュアルを参照してください。

Helix

Helix には LSP と rust-analyzer のサポートが組み込まれています。 こちらで説明されているように、 languages.toml を通じて設定できます。 ./x setup editor を実行して helix を選択できます。これにより、 Helix 向けの推奨設定を含む languages.toml を作成するよう促されます。 推奨設定は src/etc/rust_analyzer_helix.toml にあります。

Zed

Zed には LSP と rust-analyzer のサポートが組み込まれています。 こちらで説明されているように、 .zed/settings.json を通じて設定できます。 ./x setup editor で zed を選択すると、推奨設定で Zed を設定する .zed/settings.json ファイルを作成するよう促されます。 推奨される rust-analyzer 設定は src/etc/rust_analyzer_zed.json にあります。

確認、確認、そして再確認

単純なリファクタリングを行う場合、./x check を継続的に実行すると便利です。 上述のように rust-analyzer をセットアップしていれば、これは ファイルを保存するたびに自動的に行われます。 ここでは、コンパイラがビルドできることを確認しているだけですが、 多くの場合、それだけで十分です（たとえば、メソッド名を変更する場合）。 実際にテストを実行する必要があるときに ./x build を実行できます。

実際には、コードが動作するか 100% 確信できない場合でも、テストを後回しにすると便利なことがあります。 その場合、リファクタリングのコミットを積み重ね続け、後のある時点でテストだけを実行できます。 その後、git bisect を使って、どのコミットが問題を引き起こしたのかを正確に突き止められます。 このスタイルのうれしい副作用は、 最後にはかなり細かい単位のコミットの集合が残り、そのすべてが ビルドでき、テストに合格していることです。 これはレビューに役立つことが多いです。

rustup が nightly を使用するように設定する

ブートストラッププロセスの一部では、rustfmt のようなツールの固定された nightly バージョンを使用します。 リポジトリ内で cargo fmt のようなものが正しく動作するようにするには、 rustup で nightly ツールチェーンをインストール し、次のコマンドを実行します。

cd <path to rustc repo>
rustup override set nightly

これを worktree をセットアップした すべてのディレクトリに対して行うことを忘れないでください。 src/stage0 の固定された nightly バージョンを使用する必要がある場合もありますが、 多くの場合は通常の nightly チャネルで動作します。

注記 実際に x が使用する rustfmt で vscode を設定する方法については VSCode に関するセクションを、ブートストラップされたコンパイラ用に rustup ツールチェーンをセットアップする方法については rustup に関するセクションを参照してください

注記 これで rustc を cargo で直接ビルドできるようになるわけでは_ありません_。 コンパイラまたは標準ライブラリで作業するには、引き続き x を使用する必要があります。これは単に cargo fmt を使えるようにするだけです。

CI-rustc によるより高速なビルド

コンパイラに取り組んでいない場合、多くの場合はコンパイラツリーをビルドする必要はありません。 たとえば、コンパイラのビルドをスキップし、library ツリーまたは src/tools 配下のツールだけをビルドできます。 これを実現するには、設定で download-rustc オプションを設定して有効にする必要があります。 これにより bootstrap は、stage > 0 の ステップに対して最新の nightly コンパイラを使用します。つまり、事前コンパイル済みコンパイラが 2 つ存在することになります: stage0 コンパイラと、stage > 0 のステップ用の download-rustc コンパイラです。 この方法では、ツリー内コンパイラをビルドする必要がまったくなくなります。 その結果、ツリー内コンパイラをビルドしないことで、ビルド時間が大幅に短縮されます。

--keep-stage-std によるより高速な再ビルド

コンパイラがビルドできるかどうかを確認するだけでは不十分な場合があります。 よくある例として、何らかの状態の値を調べたり、問題をよりよく理解したりするために debug! 文を追加する必要がある場合があります。 その場合、実際には完全なビルドは必要ありません。 bootstrap のキャッシュ無効化をバイパスすることで、多くの場合、 これらのビルドを非常に高速に完了できます（たとえば約 30 秒）。唯一の注意点は、 これには多少のごまかしが必要であり、動作しないコンパイラが生成される可能性があることです（ただし、 それは簡単に検出して修正できます）。

使用したいコマンドの流れは次のとおりです。

• 初回ビルド: ./x build library
• 2 回目以降のビルド: ./x build library --keep-stage-std=1
  • ここでは --keep-stage-std=1 フラグを追加していることに注意してください

前述のとおり、--keep-stage-std=1 の効果は、古い標準ライブラリを 再利用できると単に_仮定_することです。 コンパイラを編集している場合、これは 多くの場合正しいです。結局、標準ライブラリは変更していないからです。 しかし、正しくない場合もあります。たとえば、型やその他の状態を rlib ファイルへコンパイラがどのようにエンコードするかを制御する、 コンパイラの「メタデータ」部分を編集している場合や、メタデータに含まれるもの （MIR の定義など）を編集している場合です。

要約すると、--keep-stage-std=1 を使用していると、コンパイル時に奇妙な挙動が 発生する可能性があります – たとえば、奇妙な ICE やその他の panic です。 その場合は、コマンドから --keep-stage-std=1 を単に削除して再ビルドしてください。 それで問題は解決するはずです。

テストを実行するときにも --keep-stage-std=1 を使用できます。 次のようになります。

• 初回テスト実行: ./x test tests/ui
• 2 回目以降のテスト実行: ./x test tests/ui --keep-stage-std=1

インクリメンタルコンパイルの使用

さらに --incremental フラグを有効にして、2 回目以降の再ビルドでさらに時間を節約できます。

./x test tests/ui --incremental --test-args issue-1234

毎回のコマンドにこのフラグを含めたくない場合は、bootstrap.toml で有効にできます。

[rust]
incremental = true

インクリメンタルコンパイルは通常より多くのディスク容量を使用することに注意してください。 ディスク容量が気になる場合は、build ディレクトリのサイズをときどき確認するとよいでしょう。

最適化の微調整

optimize = false を設定すると、コンパイラがテストには遅すぎるようになります。 ただし、テストサイクルを改善するために、再ビルドが必要な crate に対してのみ最適化を選択的に無効化できます (source)。 たとえば、rustc_mir_build に取り組んでいる場合、rustc_mir_build と rustc_driver の crate はインクリメンタル再ビルドに最も時間がかかります。 そのため、ルートの Cargo.toml に次のように設定できます。

[profile.release.package.rustc_mir_build]
opt-level = 0
[profile.release.package.rustc_driver]
opt-level = 0

複数のブランチで同時に作業する

複数のブランチで並行して作業するのは少し面倒な場合があります。というのも、 あるブランチでコンパイラをビルドすると、古いビルドとインクリメンタル コンパイルキャッシュが上書きされるからです。 1 つの解決策は、リポジトリの clone を複数用意することですが、 それは Git メタデータを複数回保存することを意味し、 各 clone を個別に更新しなければなりません。

幸い、Git には worktrees と呼ばれるよりよい解決策があります。 これにより、同じ Git データベースを共有する複数の「working tree」を作成できます。 さらに、 すべての worktree が同じオブジェクトデータベースを共有するため、いずれかで ブランチ（例: main）を更新すれば、どの worktree からでも新しい commit を使用できます。 ただし、1 つ注意点として、submodule は共有されません。 それらは依然として複数回 clone されます。

Rust リポジトリのルートディレクトリ内にいるとして、次のコマンドを実行することで、 新しい “rust2” ディレクトリに「リンクされた working tree」を作成できます。

git worktree add ../rust2

main を基にした新しいブランチ用に新しい worktree を作成する場合は、次のようになります。

git worktree add -b my-feature ../rust2 main

その後、その rust2 フォルダーを rustc の変更とビルドのための独立したワークスペースとして使用できます！

nix での作業

いくつかの nix 設定が src/tools/nix-dev-shell に定義されています。

direnv を使用している場合は、src/tools/nix-dev-shell/envrc-flake または src/tools/nix-dev-shell/envrc-shell へのシンボリックリンクを作成できます

ln -s ./src/tools/nix-dev-shell/envrc-flake ./.envrc # flake を使用

または

ln -s ./src/tools/nix-dev-shell/envrc-shell ./.envrc # nix-shell を使用

flake を使用している場合は、次のコマンドでそれも更新するようにしてください。

nix flake update --flake ./src/tools/nix-dev-shell

この shell は、すべての依存関係が正しく設定された状態で ./x.py スクリプトを実行する x という名前のコマンドを作成します。

注意

NixOS ではないディストリビューションで nix を使用する場合、 bootstrap.toml で build.patch-binaries-for-nix = true を設定する必要がある場合があることに注意してください。Bootstrap は nix 内で実行されているかどうかを検出し、自動的にパッチ適用を有効にしようとしますが、この 検出では false negative が発生する可能性があります。

nix shell を使用して bootstrap.toml を管理することもできます。

let
  config = pkgs.writeText "rustc-config" ''
    # bootstrap.toml の内容をここに記述します
  ''
pkgs.mkShell {
  /* ... */
  # この環境変数は bootstrap に bootstrap.toml の場所を伝えます。
  RUST_BOOTSTRAP_CONFIG = config;
}

Shell 補完

Bash、Zsh、Fish、PowerShell を使用している場合、x.py 用に自動生成された shell 補完スクリプトは src/etc/completions にあります。

source ./src/etc/completions/x.py.<extension> を使用して、選択した shell 用の補完を 読み込むことができます。または、PowerShell の場合は & .\src\etc\completions\x.py.ps1 を使用できます。 これを shell の起動スクリプト（例: .bashrc）に追加すると、この補完が自動的に 読み込まれます。

配布アーティファクトをビルドする

配布用にコンパイラをビルドし、パッケージ化したい場合があります。 そのためには、次のコマンドを実行します。

./x dist

ソースからインストールする

Rust（および設定で構成されたツール）を、ソースからビルドしてインストールしたい場合があります。 その場合は、次のコマンドを実行します。

./x install

注: コンパイラへの変更をテストしている場合は、コンパイラを（./x build で）ビルドしてから、 こちらで説明されているようにツールチェーンを作成するとよいでしょう。

たとえば、作成したツールチェーンの名前が “foo” の場合は、 rustc +foo ... のように呼び出します（ここで … は残りの引数を表します）。

Rust（および設定ファイル内のツール）をグローバルにインストールする代わりに、DESTDIR 環境変数を設定してインストールパスを変更できます。 インストールパスをより動的に設定したい場合は、 設定ファイル内のインストールオプションを使用することを推奨します。

ドキュメントのビルド

この章では、標準ライブラリ（std）やコンパイラ（rustc）など、 ツールチェーンコンポーネントのドキュメントをビルドする方法について説明します。

• すべてをドキュメント化する

  これは beta ツールチェーンの rustdoc を使用するため、 stage 1 rustdoc とは（わずかに）異なる出力が生成されます。 rustdoc は活発に開発されているためです。

  ./x doc
  

  ドキュメントが CI 上と同じように見えることを確実にしたい場合は、次のようにします。

  ./x doc --stage 1
  

  これにより、（現在の）rustdoc がビルドされ、 その後、それを使用してコンポーネントがドキュメント化されます。

• 個別のテストを実行したり、特定のコンポーネントをビルドしたりする場合とほぼ同様に、 必要なドキュメントだけをビルドできます。

  ./x doc src/doc/book
  ./x doc src/doc/nomicon
  ./x doc compiler library
  

  ブックの完全な一覧については、nightly ドキュメントのインデックスページを参照してください。

• rustc の内部項目をドキュメント化する

  コンパイラのドキュメントはデフォルトではビルドされません。 x doc でデフォルトで作成するには、bootstrap.toml を変更します。

  build.compiler-docs = true
  

  有効にすると、内部コンパイラ項目のドキュメントもビルドされることに注意してください。

  注: コンパイラのドキュメントはこちらのリンクにあります。

Rustdoc の概要

rustdoc は、コンパイラおよび標準ライブラリと同じツリー内にあります。 この章では、その仕組みについて説明します。 Rustdoc の機能とその使い方については、 Rustdoc book を参照してください。 rustdoc の仕組みの詳細については、“Rustdoc internals” の章を参照してください。

rustdoc は rustc の内部機構（そして、もちろん標準ライブラリ）を使用するため、 rustdoc をビルドする前に、コンパイラと std を一度ビルドする必要があります。

Rustdoc は、クレート librustdoc 内に完全に実装されています。 これは、クレートの内部表現（HIR）が得られ、アイテムの型に関するいくつかのクエリを実行できるようになる地点までコンパイラを実行します。 HIR と queries については、リンク先の章で説明されています。

その後、librustdoc は一連のドキュメントをレンダリングするために、主に 2 つのステップを実行します。

• AST を、ドキュメントの作成により適した形式へ「クリーン」します（また、 コンパイラ内の変更の影響をやや受けにくくします）。
• このクリーンされた AST を使用して、クレートのドキュメントを 1 ページずつレンダリングします。

当然ながら、実際にはこれ以外にも多くの処理があり、これらの説明では 多くの詳細を簡略化していますが、これが大まかな概要です。

（補足: librustdoc はライブラリクレートです！ rustdoc バイナリは src/tools/rustdoc のプロジェクトを使用して作成されます。 ただし、文字どおりそれが行っていることは、このクレートの lib.rs にある main() を呼び出すことだけです。）

チートシート

• 開始する前に ./x setup tools を実行します。 これにより、rustdoc やその他のツールの開発に適した設定で x が構成されます。これには、 rustc をビルドする代わりにコピーをダウンロードすることも含まれます。
• コンパイルエラーをすばやく確認するには、./x check rustdoc を使用します。
• 他のプロジェクトで実行できる利用可能な rustdoc を作成するには、./x build library rustdoc を使用します。
  • rustdoc --test を使用できるようにするには、library/test を追加します。
  • stage2 という名前のカスタムツールチェーンを rustup 環境に追加するには、 rustup toolchain link stage2 build/host/stage2 を実行します。 それを実行した後は、任意のディレクトリで cargo +stage2 doc を実行すると、 ローカルでコンパイルした rustdoc を使用してビルドされます。
• この rustdoc を使用して標準ライブラリのドキュメントを生成するには、./x doc library を使用します。
  • 完成したドキュメントは build/host/doc（core、alloc、std の下）で利用できます。
  • それらのドキュメントを Web サーバーにコピーしたい場合は、 build/host/doc 全体をコピーしてください。CSS、JS、フォント、ランディングページはそこにあるためです。
  • フロントエンドのデバッグでは、bootstrap.toml の rust.docs-minification オプションを無効にします。
• stage1 rustdoc を使用してテストを実行するには、./x test tests/rustdoc* を使用します。
  • テストの詳細については、Rustdoc internals を参照してください。
• rustdoc の JavaScript チェック（eslint、es-check、tsc）を実行するには、./x test tidy --extra-checks=js を使用します。

注: ./x test tidy は、JS/TS ソースが変更された場合、これらのチェックをすでに自動的に実行します。--extra-checks=js はそれらを明示的に強制します。

JavaScript CI チェック

Rustdoc の JavaScript と TypeScript は、CI 中に eslint、es-check、tsc によってチェックされます（compiletest によってではありません）。 これらは tidy ジョブの一部として実行されます。

./x test tidy --extra-checks=js

--extra-checks=js フラグは、CI で実行されるフロントエンドの lint を有効にします。

コード構造

このセクション内のすべてのパスは、rust-lang/rust リポジトリ内の src/librustdoc/ からの相対パスです。

• HTML 出力コードのほとんどは、html/format.rs と html/render/mod.rs にあります。 それらは、impl std::fmt::Display を返す多数の関数内にあります。
• 上記の関数によってレンダリングされるデータ型は、clean/types.rs で定義されています。 HIR と rustc_middle::ty IR からそれらを作成する役割を持つ関数は、 clean/mod.rs にあります。
• rustdoc をテストハーネスとして使用することに特有の部分は、doctest.rs にあります。
• Markdown レンダラーは html/markdown.rs で読み込まれます。これには、 指定された Markdown ブロックから doctest を抽出する関数も含まれます。
• フロントエンドの CSS と JavaScript は html/static/ に保存されています。
  • JavaScript について。 型注釈は TypeScript-flavored JSDoc コメントと外部の .d.ts ファイルを使用して記述されます。 この方法により、コード自体はプレーンで有効な JavaScript のままになります。 tsc は linter としてのみ使用します。

テスト

rustdoc の統合テストは、複数のテストスイートに分割されています。 詳細については、Rustdoc テストスイートを参照してください。

制約

私たちは、JavaScript が無効な場合やローカルファイルを閲覧している場合でも、rustdoc がある程度適切に動作するように努めています。 [サポート対象ブラウザーの一覧][a list of supported browsers]があります。

ローカルファイル（file:/// URL）のサポートには、いくつかの意外な制約が伴います。 localStorage や Service Workers のように、安全なオリジンを必要とする特定のブラウザー機能は、 信頼性高く動作しません。 そのような機能は引き続き使用できますが、それらがなくてもページが引き続き利用可能であることを確認する必要があります。

Rustdoc は[関数本体の型チェックを行いません][platform-specific docs]。 これは、[typeck の組み込みクエリをオーバーライドすること][override queries]、 [名前解決エラーを抑制すること][silencing name resolution errors]、および[不透明型を解決しないこと][not resolving opaque types]によって機能します。 これにはいくつかの注意点があります。特に、rustdoc は 本体の型チェックを必要とするコンパイラのどの部分も実行できません。 たとえば、.rlib ファイルを生成したり、ほとんどの lint を実行したりすることはできません。 最終的にはこのモデルから移行したいと考えていますが、 [これを使用している人々][async-std]のために、何らかの代替手段が必要です。 [さまざまな][zulip stop accepting broken code] [以前の][rustdoc meeting 2024-07-08] [Zulip][compiler meeting 2023-01-26] [議論][notriddle rfc]を参照してください。 このハックが削除された場合に壊れるコードの例については、 [tests/rustdoc-ui/error-in-impl-trait] を参照してください。 [platform-specific docs]: https://doc.rust-lang.org/rustdoc/advanced-features.html#interactions-between-platform-specific-docs [override queries]: https://github.com/rust-lang/rust/blob/52bf0cf795dfecc8b929ebb1c1e2545c3f41d4c9/src/librustdoc/core.rs#L299-L323 [silencing name resolution errors]: https://github.com/rust-lang/rust/blob/52bf0cf795dfecc8b929ebb1c1e2545c3f41d4c9/compiler/rustc_resolve/src/late.rs#L4517 [not resolving opaque types]: https://github.com/rust-lang/rust/blob/52bf0cf795dfecc8b929ebb1c1e2545c3f41d4c9/compiler/rustc_hir_analysis/src/check/check.rs#L188-L194 [async-std]: https://github.com/rust-lang/rust/issues/75100 [rustdoc meeting 2024-07-08]: https://rust-lang.zulipchat.com/#narrow/channel/393423-t-rustdoc.2Fmeetings/topic/meeting.202024-07-08/near/449969836 [compiler meeting 2023-01-26]: https://rust-lang.zulipchat.com/#narrow/channel/238009-t-compiler.2Fmeetings/topic/.5Bweekly.5D.202023-01-26/near/323755789 [zulip stop accepting broken code]: https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/stop.20accepting.20broken.20code [notriddle rfc]: https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/Pre-RFC.3A.20stop.20accepting.20broken.20code [tests/rustdoc-ui/error-in-impl-trait]: https://github.com/rust-lang/rust/tree/163cb4ea3f0ae3bc7921cc259a08a7bf92e73ee6/tests/rustdoc-ui/error-in-impl-trait [a list of supported browsers]: https://rust-lang.github.io/rfcs/1985-tiered-browser-support.html#supported-browsers

複数回の実行、同じ出力ディレクトリ

Rustdoc は、さまざまな入力に対して複数回実行し、その出力先を同じディレクトリに設定できます。 これは、cargo が現在のクレートの依存関係のドキュメントを生成する方法です。 ユーザーが、自分にとって必要なすべてのドキュメントを含む大きな ドキュメントバンドルを望む場合は、手動で行うこともできます。

HTML は各クレートについて個別に生成されますが、出力ディレクトリにクレートを追加するにつれて 更新する、クレート間にまたがる情報がいくつかあります。

• crates<SUFFIX>.js は、出力ディレクトリ内のすべてのクレートのリストを保持します。
• search-index<SUFFIX>.js は、検索可能なすべての項目のリストを保持します。
• 各トレイトについて、implementors/.../trait.TraitName.js の下にファイルがあり、 そのトレイトの実装者のリストが含まれます。 実装者はそのトレイトとは異なる クレートに存在する場合があり、新しい実装者を見つけるたびに JS ファイルが更新されます。

ユースケース

rustdoc に取り組む際に念頭に置いておくべき、主要なユースケースがいくつかあります。

標準ライブラリドキュメント

これらは Rust のリリースプロセスの一環として https://doc.rust-lang.org/std で公開されます。 Stable リリースは、https://doc.rust-lang.org/1.57.0/std/ のような 特定のバージョン付き URL にもアップロードされます。 Beta と nightly のドキュメントは、 https://doc.rust-lang.org/beta/std/ と https://doc.rust-lang.org/nightly/std/ で公開されます。 ドキュメントは promote-release tool でアップロードされ、S3 から CloudFront で配信されます。

標準ライブラリドキュメントには、alloc、core、proc_macro、std、test の 5 つのクレートが含まれます。

docs.rs

クレートが crates.io に公開されると、docs.rs は自動的にそのドキュメントをビルドして 公開します。たとえば https://docs.rs/serde/latest/serde/ です。 これは常に現在の nightly rustdoc でビルドされるため、rustdoc に取り込まれた変更は、docs.rs に即座に公開される影響を 与えるという意味で「insta-stable」です。 古いドキュメントは再ビルドされる場合もありますが、常にそうとは限らないため、 docs.rs で古いリリースを閲覧していると UI に多少の違いが見られます。 クレート作者は再ビルドをリクエストでき、その場合は最新の rustdoc で実行されます。

docs.rs は、ストレージを節約し、上部にナビゲーションバーを表示するために、 rustdoc の出力にいくつかの変換を行います。 特に、main.js や rustdoc.css のような特定の静的 ファイルは、同じバージョンの rustdoc の複数の呼び出し間で共有される場合があります。 crates.js や sidebar-items.js のような他のファイルは、呼び出しごとに異なります。 フォントのようなさらに別のものは、決して変更されません。 これらのカテゴリは src/librustdoc/html/render/write_shared.rs の SharedResource enum を使用して区別されます

docs.rs 上のドキュメントは常に一度に 1 つのクレートについて生成されるため、 検索機能とサイドバー機能には現在のクレートの依存関係は含まれません。

ローカルで生成されたドキュメント

クレート作者は、ローカルにチェックアウトしたクレートで cargo doc --open を実行してドキュメントを確認できます。 これは、書いているドキュメントが有用で正しく表示されることを確認するのに役立ちます。 また、自分が作者ではないものの利用したいクレートのドキュメントを閲覧する人にとっても有用です。 どちらの場合でも、通常は表示されないプライベートメソッドやフィールドなどを 確認するために、Cargo フラグ --document-private-items を使用できます。

デフォルトでは、cargo doc はクレートとそのすべての依存関係のドキュメントを生成します。 その結果、非常に大きなドキュメントバンドルになり、大きな（そして遅い）検索コーパスになることがあります。 Cargo フラグ --no-deps はこの挙動を抑制し、そのクレートだけのドキュメントを生成します。

セルフホストされたプロジェクトドキュメント

一部のプロジェクトは独自のドキュメントをホストしています。 これは、ローカルでドキュメントを生成し、それを単純に Web サーバーへコピーすることで簡単に行えます。 Rustdoc の HTML 出力は、フラグによって広範にカスタマイズできます。 ユーザーはテーマを追加し、デフォルトテーマを設定し、任意の HTML を注入できます。 詳細は rustdoc --help を参照してください。

新しいターゲットの追加

これは、新しいターゲットのサポートを追加するための一連の手順です。 到達し得る最終状態やそこに至る経路は数多くあるため、すべてのセクションが あなたの目的に関連するとは限りません。

関連するドキュメントについては、ターゲット階層ポリシーも参照してください。

新しい LLVM の指定

非常に新しいターゲットの場合、現在 Rust に同梱されているものとは異なる LLVM のフォークを使用する必要があるかもしれません。 その場合は、src/llvm-project git サブモジュールに移動し（サブモジュールが更新されるように、 少なくとも一度は ./x check を実行する必要があるかもしれません）、 自分のフォークに適したコミットをチェックアウトしてから、その新しいサブモジュール参照を メインの Rust リポジトリにコミットします。

例は次のとおりです。

cd src/llvm-project
git remote add my-target-llvm some-llvm-repository
git checkout my-target-llvm/my-branch
cd ..
git add llvm-project
git commit -m 'Use my custom LLVM'

ビルド済み LLVM の使用

すでにビルド済みのローカル LLVM チェックアウトがある場合、 冗長なビルドを避けるために、そのビルドをシステム LLVM として扱うよう Rust を構成できる場合があります。

bootstrap.toml の target セクションを使用して、ビルド済みバージョンの LLVM を使用するよう Rust に指示できます。

[target.x86_64-unknown-linux-gnu]
llvm-config = "/path/to/llvm/llvm-7.0.1/bin/llvm-config"

システム LLVM を使用しようとしている場合、以前に次のパスが確認されていますが、 あなたのシステムでは異なる可能性があります。

• /usr/bin/llvm-config-8
• /usr/lib/llvm-8/bin/llvm-config

コード生成テストで使用される LLVM の FileCheck ツールをインストールしておく必要があることに注意してください。 このツールは通常 LLVM と一緒にビルドされますが、独自のインストール済み LLVM を使用する場合は、 何らかの別の方法で FileCheck を提供する必要があります。 Debian ベースのシステムでは、llvm-N-tools パッケージをインストールできます（ここで N は LLVM のバージョン番号です。例: llvm-8-tools）。あるいは、bootstrap.toml の llvm-filecheck 設定項目で FileCheck へのパスを指定するか、 bootstrap.toml の rust.codegen-tests 項目でコード生成テストを無効化できます。

ターゲット仕様の作成

まずはターゲット JSON ファイルから始めるべきです。 --print target-spec-json を使用すると、既存のターゲットの仕様を確認できます。

rustc -Z unstable-options --target=wasm32-unknown-unknown --print target-spec-json

その JSON をファイルに保存し、ターゲットに合わせて適切に変更します。

ターゲット仕様の追加

JSON 仕様を記入し、ある程度正常にコンパイルできるようになったら、 その仕様をコンパイラ自体にコピーできます。

rustc_target::spec モジュール内の supported_targets マクロにある 大きなテーブルに行を追加する必要があります。 次に、新しいターゲットに対応する、target 関数を含むファイルを追加します。

例として使用できる既存のターゲットを探してください。

このターゲットをブートストラップで使用するには、src/bootstrap/src/core/sanity.rs の STAGE0_MISSING_TARGETS リストにターゲットトリプルを明示的に追加する必要があります。 これは、デフォルトのブートストラップコンパイラ（通常はベータコンパイラ）が、 追加したばかりの新しいターゲットを認識しないために必要です。 したがって、ブートストラップがこのターゲットはまだ stage0 コンパイラではサポートされていないことを 認識できるように、STAGE0_MISSING_TARGETS に追加する必要があります。

const STAGE0_MISSING_TARGETS: &[&str] = &[
+   "NEW_TARGET_TRIPLE"
];

クレートへのパッチ適用

libc や cc など、コンパイラが依存しているクレートに変更を加える必要があるかもしれません。 その場合は、Cargo の [patch] 機能を使用できます。 たとえば、未リリース版の libc を使用したい場合は、トップレベルの Cargo.toml ファイルに追加できます。

diff --git a/Cargo.toml b/Cargo.toml
index 1e83f05e0ca..4d0172071c1 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -113,6 +113,8 @@ cargo-util = { path = "src/tools/cargo/crates/cargo-util" }
 [patch.crates-io]
+libc = { git = "https://github.com/rust-lang/libc", rev = "0bf7ce340699dcbacabdf5f16a242d2219a49ee0" }

 # 何が起きているのかについては、`src/tools/rustc-workspace-hack/README.md` のコメントを参照してください
 # ここ
 rustc-workspace-hack = { path = 'src/tools/rustc-workspace-hack' }

その後、cargo update -p libc を実行してロックファイルを更新します。

ローカルの path 依存関係にパッチを適用すると、 その依存関係に対する警告が有効になることに注意してください。 一部の依存関係は警告なしではなく、bootstrap.toml の rust.deny-warnings 設定により、 ビルドが突然失敗し始める可能性があります。 警告に対処するには、次のようにするとよいでしょう。

• 依存関係を変更して警告を取り除く
• または、ローカル開発目的で、bootstrap.toml に rust.deny-warnings = false を設定して警告を抑制する。

クロスコンパイル

JSON とコードの両方にターゲット仕様が用意できたら、rustc をクロスコンパイルできます。

DESTDIR=/path/to/install/in \
./x install -i --stage 1 --host aarch64-apple-darwin.json --target aarch64-apple-darwin \
compiler/rustc library/std

ターゲット仕様がすでにブートストラップコンパイラで利用可能な場合は、 両方の引数で JSON ファイルの代わりにそれを使用できます。

ターゲットを tier 2（ターゲット）から tier 2（ホスト）へ昇格する

tier 2 ターゲットには 2 つのレベルがあります。

• クロスコンパイルのみされるターゲット（rustup target add）
• ネイティブツールチェインを持つターゲット（rustup toolchain install）

ターゲットをクロスコンパイルからネイティブへ昇格する例については、 #75914 を参照してください。

コンパイラの最適化ビルド

可能な限り最適化された rustc のビルドをコンパイルするために使用できる、追加のビルド設定オプションやテクニックが複数あります（たとえば Linux ディストリビューション向けに rustc をビルドする場合）。 さまざまな Rust ターゲットに対するこれらの設定オプションの状況は、こちらで追跡されています。 このページでは、自分で rustc をビルドする際に、これらの手法をどのように使用できるかを説明します。

リンク時最適化

リンク時最適化は、プログラムのパフォーマンスを向上させることができる強力なコンパイラ技法です。 rustc をビルドする際に (Thin-)LTO を有効にするには、bootstrap.toml で rust.lto 設定オプションを "thin" に設定します。

rust.lto = "thin"

rustc 向けの LTO は、現在 x86_64-unknown-linux-gnu ターゲットでのみサポートおよびテストされていることに注意してください。他のターゲットでも動作する可能性はありますが、保証はありません。 特に、LTO で最適化された rustc は、現在 Windows で誤ったコンパイルを生成します。

Linux で LTO を有効にすると、最大 10% の高速化が得られています。

メモリアロケータ

rustc に別のメモリアロケータを使用すると、大きなパフォーマンス上の利点が得られる場合があります。 jemalloc アロケータを有効にしたい場合は、bootstrap.toml で rust.jemalloc オプションを true に設定できます。

rust.jemalloc = true

このオプションは現在、Linux および macOS ターゲットでのみサポートされていることに注意してください。

コード生成ユニット

rustc クレートごとのコード生成ユニット数を減らすと、コンパイラのより高速なビルドを生成できます。 bootstrap.toml で以下のオプションを使用すると、rustc と libstd のコード生成ユニット数を変更できます。

rust.codegen-units = 1
rust.codegen-units-std = 1

命令セット

デフォルトでは、rustc は（選択されたターゲットに応じて）汎用的で保守的な命令セットアーキテクチャ向けにコンパイルされ、できるだけ多くの CPU をサポートするようになっています。 特定の命令セットアーキテクチャ向けに rustc をコンパイルしたい場合は、RUSTFLAGS で target_cpu コンパイラオプションを設定できます。

RUSTFLAGS="-C target_cpu=x86-64-v3" ./x build ...

LLVM も特定の命令セット向けにコンパイルしたい場合は、bootstrap.toml で llvm フラグを設定できます。

llvm.cxxflags = "-march=x86-64-v3"
llvm.cflags = "-march=x86-64-v3"

プロファイル誘導最適化

プロファイル誘導最適化（または、より一般的にはフィードバック指向最適化）を適用すると、rustc のパフォーマンスを最大 15% まで大きく向上させることができます（1、2）。 ただし、これらの技法は設定オプションで単純に有効化できるものではなく、rustc を複数回コンパイルし、選択したベンチマークでプロファイルする複雑なビルドワークフローが必要です。

エンドユーザーに配布されるビルド向けに、PGO（プロファイル誘導最適化）と BOLT（リンク後バイナリオプティマイザ）を使用して rustc を最適化するために使われる opt-dist というツールがあります。 src/tools/opt-dist にあるこのツールを調査し、それをベースにカスタム PGO ビルドワークフローを構築することも、直接使用してみることもできます。 このツールは現在、Rust の継続的インテグレーションワークフローでの使い方にかなりハードコードされており、異なる環境で動作させるには、いくつかのカスタム変更が必要になる可能性があることに注意してください。

このツールを使用するには、いくつかの外部依存関係を用意する必要があります。

• Python3 インタープリタ（x.py を実行するため）。
• llvm-profdata バイナリを含む、コンパイル済みの LLVM ツールチェーン。 必要に応じて、BOLT を使用したい場合は、 llvm-bolt と merge-fdata バイナリがツールチェーン内で利用可能でなければなりません。

これらの依存関係は、Environment 構造体の実装によって opt-dist に提供されます。 これは、PGO/BOLT パイプラインが実行されるディレクトリと、Python や LLVM などの外部依存関係も指定します。

以下は、opt-dist をローカルで（CI の外部で）使用する方法の例です。

1. opt-dist はメトリクスが有効になっていることを想定しているため、bootstrap.toml ファイルでメトリクスを有効にします。

   build.metrics = true
   

2. 次のコマンドでツールをビルドします。

   ./x build tools/opt-dist
   

3. local モードでツールを実行し、必要なパラメータを指定します。

   ./build/host/stage1-tools-bin/opt-dist local \
     --target-triple <target> \ # ターゲットを選択します。例: "x86_64-unknown-linux-gnu"
     --checkout-dir <path>    \ # rust チェックアウトへのパス。例: "."
     --llvm-dir <path>        \ # ビルド済み LLVM ツールチェーンへのパス。例: "/foo/bar/llvm/install"
     -- python3 x.py dist       # 実際のビルドコマンドを渡します
   

   変更可能な追加パラメータを確認するには、--help を実行できます。

注: opt-dist をローカルで実行する代わりに、実際の CI パイプラインを実行したい場合は、 cargo run --manifest-path src/ci/citool/Cargo.toml run-local dist-x86_64-linux を実行できます。

コンパイラのテスト

Rust プロジェクトでは、ビルドシステム（./x test）によって統括される、さまざまな種類のテストが実行されます。このセクションでは、各種テストツールの概要を簡単に説明します。以降の章では、テストの実行と新しいテストの追加について詳しく説明します。

テストの種類

Rust ディストリビューション内のものを検証するために、いくつかの種類のテストがあります。ほぼすべては ./x test によって駆動されますが、以下で述べるように例外もあります。

Compiletest

コンパイラ自体をテストするための主要なテストハーネスは、compiletest というツールです。

compiletest は、テストスイートとして整理された、さまざまなスタイルのテストの実行をサポートします。テストモードは、一連のテストスイートに対して共通のプリセット/動作を提供する場合があります。compiletest がサポートするテストは tests ディレクトリにあります。

Compiletest の章では、このツールの使い方について詳しく説明しています。

例: ./x test tests/ui

パッケージテスト

標準ライブラリと多くのコンパイラパッケージには、典型的な Rust の #[test] ユニットテスト、統合テスト、ドキュメンテーションテストが含まれています。library/ または compiler/ ディレクトリ内のほぼ任意のパッケージについて、./x test にパスを渡すことができ、x は基本的にそのパッケージに対して cargo test を実行します。

例:

標準ライブラリは、その機能をカバーするためにドキュメンテーションテストに大きく依存しています。ただし、必要に応じてユニットテストや統合テストも使用できます。ほぼすべてのコンパイラパッケージでは、doctest が無効化されています。

すべての標準ライブラリおよびコンパイラのユニットテストは、別個の tests ファイルに配置されます（これは tidy によって強制されます）。これにより、テストファイルが変更された場合でも、クレートを再コンパイルする必要がなくなります。例:

#[cfg(test)]
mod tests;

この方法で行わず、core のようなものに取り組んでいる場合、標準ライブラリ全体と rustc 全体を再コンパイルする必要があります。

./x test には、これらのパッケージテストの動作を制御するための CLI オプションがいくつか含まれています。

• --doc — パッケージ内のドキュメンテーションテストのみを実行します。
• --all-targets — ドキュメンテーションテストを除くすべてのテストを実行します。
• --tests — ユニットテストと統合テストのみを実行します

Tidy

Tidy は、長い行を拒否するなど、ソースコードのスタイルとフォーマット規約を検証するために使用されるカスタムツールです。詳細については、コーディング規約に関するセクションまたは Tidy Readme を参照してください。

例: ./x test tidy

フォーマット

Rustfmt は、コンパイラ全体で一貫したスタイルを強制するためにビルドシステムに統合されています。フォーマットチェックは、前述の Tidy ツールによって自動的に実行されます。

例:

Book ドキュメントテスト

公開されているすべての book には、それぞれ独自のテストがあり、主に Rust コード例が通ることを検証するためのものです。内部的には、これらは基本的に markdown ファイルに対して rustdoc --test を使用しています。./x test に book へのパスを渡すことで、テストを実行できます。

例: ./x test src/doc/book

ドキュメントリンクチェッカー

すべてのドキュメントにわたるリンクはリンクチェッカーツールで検証され、次のように呼び出すことができます。

./x test linkchecker

これにはすべてのドキュメントをビルドする必要があり、しばらく時間がかかる場合があります。

distcheck

distcheck は、ビルドシステムによって作成されたソースディストリビューション tarball が展開され、ビルドされ、すべてのテストを実行できることを検証します。

./x test distcheck

ツールテスト

Rust に含まれているパッケージについても、すべてのテストが実行されます。これには cargo、clippy、rustfmt、miri、bootstrap（Rust ビルドシステム自体のテスト）などが含まれます。

ほとんどのツールは src/tools ディレクトリにあります。ツールのテストを実行するには、そのパスを ./x test に渡すだけです。

例: ./x test src/tools/cargo

通常、これらのツールでは、ツールのディレクトリ内で cargo test を実行します。

指定した一連のテストのみを実行したい場合は、コマンドに --test-args FILTER_NAME を追加します。

例: ./x test src/tools/miri --test-args padding

CI では、一部のツールは失敗が許容されています。失敗すると対応するチームに通知が送信され、toolstate Web サイトで追跡されます。詳細については、toolstate ドキュメントを参照してください。

エコシステムテスト

Rust は、回帰を検出し、言語の進化について情報に基づいた判断を行うために、実世界のコードとの統合をテストします。エコシステムテストには、Crater を含むいくつかの種類があります。詳細については、エコシステムテストの章を参照してください。

パフォーマンステスト

コンパイラのパフォーマンスのテストと追跡には、別のインフラストラクチャが使用されます。詳細については、パフォーマンステストの章を参照してください。

コード生成バックエンドテスト

コード生成バックエンドテストを参照してください。

その他の情報

その他の有用なテスト関連情報は、その他の情報にあります。

参考資料

次のブログ記事も参考になる場合があります。

• brson の古典的な “How Rust is tested”

テストの実行

x を使用してテストコレクション全体を実行できます。 ただし、ローカル開発中に 全体の テストコレクションを実行したいことはほとんどありません。 非常に長い時間がかかるためです。 ローカル開発については、テストのサブセットを実行する方法に関する後続のサブセクションを参照してください。

./x test

テスト結果はキャッシュされ、以前に成功したテストはテスト中に ignored されます。 各テストの stdout/stderr の内容とタイムスタンプファイルは、指定された <target-tuple> に対して build/<target-tuple>/test/ の下にあります。 テストを強制的に再実行するには（たとえば、テストランナーが変更に気づかない場合）、--force-rerun CLI オプションを使用できます。

外部依存関係の要件に関する注意

一部のテストスイートには外部依存関係が必要な場合があります。これは特に debuginfo テストに当てはまります。一部の debuginfo テストでは、Python が有効な gdb が必要です。 gdb 内から python コマンドを使用することで、インストールされている gdb が Python をサポートしているかをテストできます。 呼び出した後、Python コード（例: print("hi")）を入力し、 return に続いて CTRL+D を押すと実行できます。gdb をソースからビルドしている場合は、 --with-python=<path-to-python-binary> で設定する必要があります。

テストスイートのサブセットを実行する

特定の PR に取り組んでいる場合、通常はより小さいテストの集合を実行したいはずです。 たとえば、rustc を変更した後、物事が概ね正しく動作しているかを確認するために使用できる 良い「スモークテスト」は、ui テストスイート（tests/ui）を実行することです。

./x test tests/ui

もちろん、テストスイートの選択はいくらか任意であり、実行している作業に適していない場合があります。 たとえば、debuginfo をハックしている場合は、debuginfo テストスイートの方が適しているかもしれません。

./x test tests/debuginfo

任意のテストスイートについて、特定のテストのサブディレクトリだけをテストする必要がある場合は、 そのディレクトリをフィルターとして ./x test に渡すことができます。

./x test tests/ui/const-generics

MSYS2 に関する注意

MSYS2 ではパスが奇妙なようで、./x test は tests/ui/const-generics も tests\ui\const-generics も認識しません。その場合は、たとえば ./x test ui --test-args="tests/ui/const-generics" を使用して回避できます。

同様に、パスを渡すことで単一のファイルをテストできます。

./x test tests/ui/const-generics/const-test.rs

x は、まだパスを渡して単一のツールテストを実行することをサポートしていません。 以下で説明するように、--test-args 引数を使用する必要があります。

./x test src/tools/miri --test-args tests/fail/uninit/padding-enum.rs

tidy スクリプトのみを実行する

./x test tidy

標準ライブラリでテストを実行する

./x test --stage 0 library/std

これは std のテストのみを実行することに注意してください。 core やその他のクレートをテストしたい場合は、それらを明示的に指定する必要があります。

tidy スクリプトと標準ライブラリのテストを実行する

./x test --stage 0 tidy library/std

ステージ 1 コンパイラを使用して標準ライブラリでテストを実行する

./x test --stage 1 library/std

実行したいテストスイートを列挙することで、 まったく変更していないコンポーネントのテストを実行せずに済みます。

ステージ 2 コンパイラを使用してすべてのテストを実行する

./x test --stage 2

コンパイラ/ライブラリでユニットテストを実行する

次のようにして、特定のファイルでユニットテストを実行したい場合があります。

./x test compiler/rustc_data_structures/src/thin_vec/tests.rs

しかし残念ながら、それは不可能です。 代わりに次を呼び出す必要があります。

./x test compiler/rustc_data_structures/ --test-args thin_vec

個別のテストを実行する

よく行われるもう 1 つのことは、個別のテストを実行することです。 多くの場合、それは修正しようとしているテストです。 前述のように、これを行うには完全なファイルパスを渡すか、代わりに --test-args オプションを付けて x を呼び出すことができます。

./x test tests/ui --test-args issue-1234

内部では、テストランナーは標準の Rust テストランナー（#[test] で得られるものと同じ）を呼び出すため、 このコマンドは名前に “issue-1234” を含むテストでフィルタリングすることになります。 したがって、--test-args は関連するテストの集合を実行するための良い方法です。

テスト実行時に rustc に引数を渡す

RUSTFLAGS を使用せずに、特定のコンパイラ引数を指定していくつかのテストを実行すると便利な場合があります （たとえば、不安定な機能の開発中に -Z フラグを使用する場合）。

これは、./x test の --compiletest-rustc-args オプションを使用して行うことができ、 テストのビルド時にコンパイラへ追加の引数を渡せます。

参照ファイルの編集と更新

コンパイラの出力を意図的に変更した場合、または新しいテストを作成している場合は、 テストサブコマンドに --bless を渡すことができます。

たとえば、tests/ui のいくつかのテストが失敗している場合、次のコマンドを実行できます。

./x test tests/ui --bless

これにより、すべての test/ui テストの .stderr、.stdout、または .fixed ファイルが自動的に調整されます。 もちろん、--bless フラグなしでテストを実行するときと同じように、 --test-args your_test_name フラグを使用して特定のテストだけを対象にすることもできます。

テスト実行の設定

テストを実行するためのオプションはいくつかあります。

• bootstrap.toml には rust.verbose-tests オプションがあります。false の場合、各テストは 単一のドットを出力します（デフォルト）。 true の場合、すべてのテストの名前が出力されます。 これは Rust test harness の --quiet オプションと同等です。
• 環境変数 RUST_TEST_THREADS には、テストに使用する並行スレッド数を設定できます。

--pass $mode を渡す

pass の UI テストには現在、check-pass、build-pass、run-pass の 3 つのモードがあります。 --pass $mode が渡されると、テストファイルにディレクティブ //@ no-pass-override が存在しない限り、 これらのテストは指定された $mode で強制的に実行されます。 たとえば、tests/ui 内のすべてのテストを check-pass として実行できます。

./x test tests/ui --pass check

--pass $mode を渡すことで、テスト時間を短縮できます。 各モードについては、pass/fail 期待値の制御を参照してください。

異なる「compare modes」でテストを実行する

UI テストでは、コンパイラが特定の「モード」にあるかどうかによって、出力が異なる場合があります。 たとえば、Polonius モードを使用している場合、テスト foo.rs はまず期待される出力を foo.polonius.stderr から探し、見つからなければ通常の foo.stderr にフォールバックします。 以下は、Polonius モードで UI テストスイートを実行します:

./x test tests/ui --compare-mode=polonius

詳細については、比較モードを参照してください。

テストを手動で実行する

単に手作業でテストを実行する方が簡単で速い場合があります。 ほとんどのテストは単なる .rs ファイルなので、rustup ツールチェーンを作成した後、次のようにできます:

rustc +stage1 tests/ui/issue-1234.rs

これははるかに高速ですが、常にうまくいくとは限りません。 たとえば、一部のテストには、特定のコンパイラフラグを指定するディレクティブや、他のクレートに依存するディレクティブが含まれており、それらのオプションがないと同じようには実行されない場合があります。

リモートマシンでテストを実行する

テストはリモートマシン上で実行できます（たとえば、異なるアーキテクチャ向けのビルドをテストする場合）。 これは、ビルドマシン上の remote-test-client を使用して、リモートマシン上で実行されている remote-test-server にテストプログラムを送信することで行います。 remote-test-server はテストプログラムを実行し、結果をビルドマシンに送り返します。 remote-test-server は 認証なしのリモートコード実行 を提供するため、使用場所には注意してください。

これを行うには、まずリモートマシン向けに remote-test-server をビルドします（例として RISC-V を使用します）:

./x build src/tools/remote-test-server --target riscv64gc-unknown-linux-gnu

バイナリは ./build/host/stage2-tools/$TARGET_ARCH/release/remote-test-server に作成されます。 これをリモートマシンにコピーします。

リモートマシン上で、--bind 0.0.0.0:12345 フラグ（必要に応じて --verbose フラグも）を付けて remote-test-server を実行します。 出力は次のようになるはずです:

$ ./remote-test-server --verbose --bind 0.0.0.0:12345
starting test server
listening on 0.0.0.0:12345!

サーバーを 0.0.0.0 にバインドすると、あなたのマシンに到達可能なすべてのホストが、あなたのマシン上で任意のコードを実行できるようになることに注意してください。 ポート 12345 への外部アクセスをブロックするファイアウォールを設定するか、バインド時により制限的な IP アドレスを使用することを強く推奨します。

remote-test-server が動作しているかどうかは、接続して ping\n を送信することでテストできます。 pong が返ってくるはずです:

$ nc $REMOTE_IP 12345
ping
pong

リモートランナーを使用してテストを実行するには、TEST_DEVICE_ADDR 環境変数を設定してから、通常どおり x を使用します。 たとえば、IP アドレス 1.2.3.4 の RISC-V マシン向けに ui テストを実行するには、次のようにします:

export TEST_DEVICE_ADDR="1.2.3.4:12345"
./x test tests/ui --target riscv64gc-unknown-linux-gnu

remote-test-server が verbose フラグ付きで実行されていた場合、テストマシン上の出力はおおよそ次のようになります

[...]
run "/tmp/work/test1007/a"
run "/tmp/work/test1008/a"
run "/tmp/work/test1009/a"
run "/tmp/work/test1010/a"
run "/tmp/work/test1011/a"
run "/tmp/work/test1012/a"
run "/tmp/work/test1013/a"
run "/tmp/work/test1014/a"
run "/tmp/work/test1015/a"
run "/tmp/work/test1016/a"
run "/tmp/work/test1017/a"
run "/tmp/work/test1018/a"
[...]

テストは、リモートマシン上ではなく、x を実行しているマシン上でビルドされます。 予期せずビルドに失敗するテスト（または不正なビルド出力を生成する ui テスト）は、リモートマシン上で一度も実行されないまま失敗する場合があります。

remote-test-server に x コマンドから到達できない場合に備えて、デフォルトのタイムアウトは 30 分です。 このタイムアウトは、TEST_DEVICE_CONNECT_TIMEOUT_SECONDS 環境変数を使用して変更できます。

エミュレータでテストする

一部のプラットフォームは、すぐには利用できないアーキテクチャ向けにエミュレータ経由でテストされます。 標準ライブラリが十分にサポートされており、ホストオペレーティングシステムが TCP/IP ネットワークをサポートしているアーキテクチャについては、リモートマシンでテストするための上記の手順を参照してください（この場合、リモートマシンはエミュレートされています）。

エミュレータ内でのテスト実行をオーケストレーションするためのツール群もあります。 arm-android や arm-unknown-linux-gnueabihf などのプラットフォームは、GitHub Actions 上でエミュレーション下のテストを自動的に実行するように設定されています。 以下では、ターゲットのテストがエミュレーション下でどのように実行されるかを見ていきます。

armhf-gnu 用の Docker イメージには、ARM CPU アーキテクチャをエミュレートするための QEMU が含まれています。 Rust ツリーには、テストプログラムとライブラリをエミュレータに送信し、エミュレータ内でテストを実行し、結果を読み取るためのプログラムである remote-test-client と remote-test-server というツールが含まれています。 Docker イメージは remote-test-server を起動するように設定されており、ビルドツールは remote-test-client を使用してサーバーと通信し、テスト実行を調整します（src/bootstrap/src/core/build_steps/test.rs を参照）。

iOS/tvOS/watchOS/visionOS シミュレータで実行する場合も、同様にそれを “リモート” マシンとして扱えます。 ここで興味深い点は、シミュレータインスタンスとホスト macOS の間でネットワークが共有されているため、ローカルループバックアドレス 127.0.0.1 を使用できることです。 次のような方法で動作するはずです:

# iOS シミュレータ向けにテストサーバーをビルドします:
./x build src/tools/remote-test-server --target aarch64-apple-ios-sim

# 既にシミュレータインスタンスを開いている場合は、以下からデバイス UUID をコピーします:
xcrun simctl list devices booted
UDID=01234567-89AB-CDEF-0123-456789ABCDEF

# または、新しいシミュレータインスタンスを作成して起動します:
xcrun simctl list runtimes
xcrun simctl list devicetypes
UDID=$(xcrun simctl create $CHOSEN_DEVICE_TYPE $CHOSEN_RUNTIME)
xcrun simctl boot $UDID
# 詳細は https://nshipster.com/simctl/ を参照してください。

# ポート 12345 でランナーを起動します:
xcrun simctl spawn $UDID ./build/host/stage2-tools/aarch64-apple-ios-sim/release/remote-test-server -v --bind 127.0.0.1:12345

# 新しいターミナルで、ランナー経由でテストを実行します:
export TEST_DEVICE_ADDR="127.0.0.1:12345"
./x test --host='' --target aarch64-apple-ios-sim --skip tests/debuginfo
# FIXME(madsmtm): debuginfo テストが動作するようにします（`.dSYM` フォルダをターゲットにコピーする必要があるかもしれません）。

wasi (wasm32-wasip1) でテストを実行する

一部のテストは wasm ターゲット固有です。 これらのテストを実行するには、x test に --target wasm32-wasip1 を渡す必要があります。 さらに、wasi sdk が必要です。 コンピュータ上に sysroot を取得するには、wasi sdk repository のインストール手順に従ってください。 wasm32-wasip1 target support page には、sdk がビルドできなければならない最小バージョンが指定されています。 時間がかかり、非常に気になる c++ の警告を大量に出す cmake コマンドがいくつかあります… その後、bootstrap.toml で次のように sysroot を指定します:

[target.wasm32-wasip1]
wasi-root = "<wasi-sdk location>/build/sysroot/install/share/wasi-sysroot"

私の場合は rust フォルダーの隣に git clone したので、../wasi-sdk/build/.... でした。 これで、テストはそのまま実行できるはずで、他に何も設定する必要はありません。

Docker でテストする

src/ci/docker ディレクトリには、GitHub Actions で実行される Linux ベースのジョブ用の Docker イメージ定義が含まれています（Linux 以外のジョブは Docker の外部で実行されます）。 これらのジョブはローカルの開発マシンで実行でき、 ローカルシステムとは異なる環境をテストするのに役立ちます。 Linux、Windows、または macOS システムに Docker をインストールする必要があります（通常、Linux のほうが Windows や macOS よりもはるかに高速です。後者は Linux 環境をエミュレートするために仮想マシンを使用するためです）。

CI で実行されるジョブは一連の bash スクリプトを通じて設定されており、その挙動をローカルで再現するのは必ずしも簡単ではありません。 CI ジョブをできるだけ簡単な方法でローカル実行したい場合は、CI で起きることを可能な限り忠実に再現しようとする、提供されているヘルパー citool を使用できます。

cargo run --manifest-path src/ci/citool/Cargo.toml run-local <job-name>
# 例:
cargo run --manifest-path src/ci/citool/Cargo.toml run-local dist-x86_64-linux-alt

上記のスクリプトがうまく動作しない場合、Docker イメージの実行をより細かく制御したい場合、または Docker ジョブの実行中に正確に何が起きるのかを理解したい場合は、以下を読み進めてください。

run.sh スクリプト

src/ci/docker/run.sh スクリプトは、特定の Docker イメージをビルドして実行し、 そのイメージ内で Rust をビルドし、テストを実行するか、配布用に設計された一連のアーカイブを準備するために使用されます。 このスクリプトは、ローカルの Rust ソースツリーを読み取り専用モードで、obj ディレクトリを読み書き可能モードでマウントします。 コンパイラーの成果物はすべて obj ディレクトリに保存されます。 シェルは obj ディレクトリで開始されます。 そこから、Docker イメージで定義されたビルドを開始する ../src/ci/run.sh を実行します。

src/ci/docker/run.sh <image-name> を直接実行できます。 run.sh スクリプトに関する重要な注意点がいくつかあります。

• CI 上で実行される場合、このスクリプトはすべてのサブモジュールがチェックアウトされていることを期待します。 ジョブからアクセスされるサブモジュールの一部が利用できない場合、ビルドはエラーになります。 したがって、必要なサブモジュールがすべてローカルでチェックアウトされていることを確認する必要があります。 これは git で手動で行うことも、bootstrap.toml で build.submodules = true を設定して x build のようなコマンドを実行し、bootstrap に最も重要なサブモジュールをダウンロードさせることもできます ただし、実行しようとしている特定の CI ジョブに対しては、これだけでは十分でない場合があることに注意してください。
• <image-name> は、src/ci/docker/host-* ディレクトリのいずれかにある単一のディレクトリに対応します。 一部のジョブは同じイメージを実行しますが、異なる環境変数や Docker ビルド引数を使用するため、イメージ名が必ずしもジョブ名に対応するとは限らないことに注意してください これは、CI ジョブをローカルで実行することを難しくしている複雑さの一部です。
• “dist” ジョブ（dist- で始まるジョブ）を実行する場合は、DEPLOY=1 環境変数を設定する必要があります。
• “alternative dist” ジョブ（dist- で始まり -alt で終わるジョブ）を実行する場合は、DEPLOY_ALT=1 環境変数を設定する必要があります。
• 一部の std テストには IPv6 サポートが必要です。 Linux 上の Docker では、デフォルトで無効になっているようです。 コンテナーを作成する前に、IPv6 を有効にするために enable-docker-ipv6.sh のコマンドを実行してください。 これは一度だけ行えば十分です。

対話モード

特定の Docker イメージをビルドしてから、その中でカスタムコマンドを実行し、対象システムの挙動を試せるようにすると便利な場合があります。 これは対話モードを使用して行うことができ、 src/ci/docker/run.sh --dev <image-name> を使用してコンテナー内で bash シェルを開始します。

Docker コンテナー内では、特定のタスクを実行するために個別のコマンドを実行できます。 たとえば、UI テストだけを実行するために ../x test tests/ui を実行できます。

対話モードの使用に関する追加の注意点をいくつか示します。

• シェルを終了するとコンテナーは自動的に削除されますが、 ビルド成果物は obj ディレクトリに残ります。 異なる Docker イメージ間で切り替えている場合、obj ディレクトリに保存された以前の環境の成果物が ビルドシステムを混乱させる可能性があります。 コンテナー内でビルドする前に、obj ディレクトリの一部または全部を削除する必要がある場合があります。
• コンテナーは最小限で、最小限のパッケージセットしか含まれていません。 apt install less vim のように、いくつかのものをインストールしたくなるかもしれません。
• コンテナー内で複数のシェルを開くことができます。 まずコンテナー 名（短いハッシュ）が必要です。これはシェルプロンプトに表示されます。または、コンテナーの外部で docker container ls を実行して、利用可能なコンテナーを一覧表示できます。 コンテナー名がわかったら、docker exec -it <CONTAINER> /bin/bash を実行します。ここで <CONTAINER> は 4ba195e95cef のようなコンテナー名です。

CI によるテスト

私たちの CI システムの主な目的は、テストスイートに合格することによって、 rust-lang/rust の main ブランチが常に有効な状態にあることを保証することです。

大まかに言うと、rust-lang/rust でプルリクエストを開くと、 次のことが起こります。

• PR に push されるたびに、テストとチェックの小さなサブセットが実行されます。 これは一般的なエラーの検出に役立つはずです。
• PR が承認されると、bors bot がその PR を[マージキュー]にエンキューします。
• PR がキューの先頭に到達すると、bors はマージコミットを作成し、 その上で完全なテストスイートを実行します。 マージコミットには特定の PR が 1 つだけ含まれる場合もあれば、CI コストとマージ遅延を削減するために、 複数の PR をまとめた “rollup” である場合もあります。
• テストスイート全体が完了すると、2 つのことが起こり得ます。 CI が失敗して開発者による対処が必要なエラーが発生するか、CI が成功して マージコミットが main ブランチに push されます。

CI で実行される内容を変更したい場合は、CI ジョブの変更を参照してください。

CI ワークフロー

私たちの CI は主に GitHub Actions 上で実行され、.github/workflows/ci.yml で定義された単一のワークフローを使用します。 このワークフローには、実行するすべての CI ジョブに共通化された多数のステップが含まれています。 対応するブランチまたは PR にコミットが push されると、ワークフローは src/ci/citool crate を実行し、実行すべき具体的な CI ジョブを動的に生成します。 このスクリプトは、私たちのすべての CI ジョブの宣言的な設定を含む jobs.yml ファイルを入力として使用します。

ほぼすべてのビルドステップは、個別のスクリプトを shell out します。これにより、CI はかなり プラットフォーム非依存になります（つまり、GitHub Actions に過度に依存していません）。 GitHub Actions に依存しているのは、CI プロセスのブートストラップと、 プロセスを駆動するスクリプトのオーケストレーションだけです。

本質的には、すべての CI ジョブは、さまざまなオペレーティングシステム、ターゲット、プラットフォームにわたって、 異なる設定で ./x test、./x dist、またはその他のコマンドを実行します。 実行されるジョブには、dist ジョブと非 dist ジョブという 2 つの大きなカテゴリがあります。

• Dist ジョブは、特定のプラットフォーム向けにコンパイラの完全なリリースをビルドします。 これには、rustup 経由で配布するすべてのツールが含まれます。 それらのビルドはその後 rust-lang-ci2 S3 バケットにアップロードされ、rustup-toolchain-install-master ツールを使って ローカルにインストールできるようになります。 同じビルドは実際のリリースにも使用されます。私たちのリリースプロセスは基本的に、 これらのアーティファクトを rust-lang-ci2 から本番エンドポイントへコピーし、署名することで構成されています。
• 非 dist ジョブは、そのプラットフォーム上で私たちの完全なテストスイートと、 rustup 経由で配布するすべてのツールのテストスイートを実行します。 テストする内容の量は プラットフォームに依存します（たとえば、一部のテストは Tier 1 プラットフォームでのみ実行されます）。また、 一部のより高速なプラットフォームは、CI リソースの浪費を避けるために同じ builder 上にまとめられます。

入力イベント（通常はブランチへの push）に基づいて、3 種類のビルド（ジョブの集合）のいずれかを実行します。

1. PR ビルド
2. Auto ビルド
3. Try ビルド

Pull Request ビルド

プルリクエストに push されるたびに、一連の pr ジョブが実行されます。 現在、これらは Linux 上で実行される x86_64-gnu-llvm-X、x86_64-gnu-tools、pr-check-1、pr-check-2 および tidy ジョブを実行します。 これらは、一般的な問題を検出するはずの、比較的短時間 （約 40 分）で軽量なテストスイートを実行します。 より具体的には、一連の lint を実行し、Windows mingw 向けのクロスコンパイルチェック ビルド（アーティファクトは生成しない）を試み、LLVM の system バージョンを使って コンパイラをテストします。 残念ながら、すべての PR の各コミットに対して完全なテストスイートを実行するには、 リソースが多すぎます。

doc comment に関する注意

2024 年 10 月時点の PR CI は、デフォルトでは ./x doc xxx を実行しようとしないことに注意してください。これは、./x doc xxx の失敗につながる壊れた intradoc link がある場合、 完全なマージキュー CI パイプラインのかなり遅い段階でそれが発生することを意味します。

そのため、doc comment の変更については、早期に検出できるように ./x doc xxx をローカルで実行することをお勧めします。

PR ジョブは jobs.yml の pr セクションで定義されています。 その結果は、PR ページ下部の “CI checks” セクションで、 PR 上から直接確認できます。

Auto ビルド

コミットを main ブランチにマージできるようにする前に、完全なテストスイートに合格する必要があります。 これを auto ビルドと呼びます。 このビルドは、オペレーティングシステムやターゲットをまたいでさまざまなテストを実行する、数十個の CI ジョブを実行します。 完全なテストスイートはかなり低速です。 すべての auto CI ジョブが完了するまでに数時間かかることがあります。

ほとんどのプラットフォームではビルドステップのみを実行し、一部は制限されたテストセットを実行します。 完全なテストスイートを実行するのは一部のみです（Rust の platform tiers を参照）。

Auto ジョブは jobs.yml の auto セクションで定義されています。 これらは rust-lang/rust リポジトリの automation/bors/auto ブランチ上で実行され、 最終結果は、対応する PR に bors が作成するコメントを通じて報告されます。 ライブ結果は the GitHub Actions workflows page で確認できます。

任意の時点で、実行中の auto ビルドは最大 1 つです。 詳細は bors による PR の逐次マージ を参照してください。

通常、auto ジョブが失敗すると、CI ワークフロー全体が直ちに終了します。 しかし、CI 上で一定期間テストしてからマージをブロックするようにするために、 「非ブロッキング」または任意の auto ジョブを作成すると有用な場合があります。 これは、それらのジョブが flaky になり得る場合に有用です。

そのためには、そのようなジョブに optional- というプレフィックスを付け、jobs.yml で continue_on_error: true を設定します。

Try ビルド

特定の PR について CI 上でテストスイートのサブセットを実行したり、 その PR からコンパイラアーティファクトのセットをビルドしたりしたい場合があります。 これはマージを試みずに行います。 これを “try build” と呼びます。 try build は、適切な権限を持つユーザーが @bors try コマンドを含む PR コメントを投稿した後に開始されます。

try build にはいくつかのユースケースがあります。

• 私たちの rustc-perf ベンチマークスイートを使用して、一連のパフォーマンスベンチマークを実行する。 これには動作するコンパイラビルドが必要であり、Linux 上で最適化された コンパイラのバージョンをビルドする dist-x86_64-linux CI ジョブを実行する try build によって生成できます（このジョブは現在、try build を開始するとデフォルトで実行されます）。 try build を作成して パフォーマンスベンチマークのためにスケジュールするには、@bors try @rust-timer queue コマンドの組み合わせを使用できます。
• Crater run を使用して、Rust エコシステム全体に対する PR の影響を確認する。 この場合も、動作するコンパイラビルドが必要であり、 dist-x86_64-linux CI ジョブによって生成できます。
• 特定の CI ジョブ（例: Windows テスト）を PR 上で実行し、そのジョブによって実行されるテストスイートに 合格するかどうかを素早くテストする。 デフォルトでは、@bors try を含むコメントを送信すると、 jobs.yml の try セクションに定義されているジョブが実行されます。 このモードを「高速 try ビルド」と呼びます。 このような try ビルドではテストは一切実行されず、コンパイル警告も許容されます。 これは、Crater 実行やパフォーマンスベンチマークのために、 完全に正しく動作していない可能性があっても、 できるだけ速く最適化済みツールチェーンを取得したい場合に便利です。

高速 try ビルドで実行される CI ジョブには、デフォルトの try ジョブのフルビルドと区別するために、 特別なサフィックス（-quick）が付きます。 代わりにフルビルドを行いたい場合は、 ジョブパターン（後述）にそのジョブ名を指定してください。

try ビルドでカスタム CI ジョブを実行し、それらがすべてのテストに合格し、 コンパイル警告を一切生成しないことを確認したい場合は、ジョブパターンを指定して実行する CI ジョブを選択できます。 これは次の 2 つの方法のいずれかで使用できます。

• PR の説明に try-job: <job pattern> ディレクティブのセットを追加し（後述）、 単に @bors try を実行できます。 CI はこれらのディレクティブを読み取り、指定したジョブを実行します。 これは、 PR を段階的に変更した後で、同じ try ジョブのセットを複数回再実行したい場合に便利です。
• try コマンドの jobs パラメーターを使用してジョブパターンを指定できます: @bors try jobs=<job pattern>。 これは、特定のジョブを指定した一回限りの try ビルドに便利です。 jobs パラメーターは PR の説明内のディレクティブよりも優先度が高いことに注意してください。
  • たとえば @bors try jobs=job1,job2,job3 のように、複数のパターンを指定することもできます。

各ジョブパターンは、ジョブの正確な名前、または複数のジョブに一致する glob パターンのいずれかにできます。 たとえば *msvc* や *-alt です。 1 回の try ビルドで開始できるジョブは最大 20 個です。 PR の説明で glob パターンを使用する場合、 たとえばアスタリスクが含まれている場合に GitHub がそのパターンを Markdown として描画するのを避けるため、 必要に応じてバッククォート（`）で囲むことができます。このエスケープは、 @bors jobs= パラメーターを使用する場合には機能しないことに注意してください。

ジョブパターンは、jobs.yml の auto または optional セクションに定義されている 1 つ以上のジョブに一致する必要があります。

• auto ジョブは、コミットが main ブランチにマージされる前に実行されます。
• optional ジョブは、try ビルドを通じて明示的に要求された場合にのみ実行されます。 通常、tier 2 および tier 3 ターゲットに使用されます。

try ビルドを行う理由の 1 つは、上記のように @rust-timer queue を使って perf 実行を行うことです。 この perf ビルドは、その後 main 上の何らかのコミットと比較されます。 @bors try parent=<sha> を使用すると、try ビルドとその後の perf 実行を main 上の特定のコミットに基づかせることができ、 perf 比較をできるだけ公平にするのに役立ちます。

try-job PR 説明ディレクティブの使用

1. 実行したい try-job のセットを特定します。CI ジョブの名前は jobs.yml で確認できます。

2. PR の説明を修正して、パターンのセットを含めます（通常は PR の説明の末尾）。 例:

   This PR fixes #123456.
   
   try-job: x86_64-msvc
   try-job: test-various
   try-job: `*-alt`
   

   各 try-job パターンは、それぞれ独立した行に記述する必要があります。

3. @bors try で指定された try ジョブを実行します。前述のとおり、これにはユーザーが (1) try 権限を持っているか、(2) try 権限を持つ誰かによって @bors delegate=try で try 権限を委譲されている必要があります。

通常、これは jobs.yml を手動で編集するよりも簡単です。 ただし、この方法で実行されるテストのセットを調整できないため、 柔軟性は低くなる場合があります。

try ビルドは rust-lang/rust リポジトリ配下の automation/bors/try ブランチで実行され、 その結果は GitHub Actions ワークフローページ で確認できますが、 通常は対応する PR に bors が投稿するコメントによって結果が通知されます。

異なる PR 間では複数の try ビルドを並行して実行できますが、任意の時点で 1 つの PR 上で実行できる try ビルドは最大 1 つです。

CI ジョブの変更

CI で実行される内容を変更したい場合は、jobs.yml ファイルの pr、auto、または try セクションを単に変更できます。

一時的に実行内容を変更することもできます。たとえば、ローカルでのテストが難しい 特定のプラットフォームや構成をテストする場合です（たとえば、Windows ビルドが失敗したが、 Windows マシンにアクセスできない場合など）。 そのような状況では、ためらわずに CI リソースを使用してください。

任意の CI ジョブを実行するには、次の 2 つの方法があります。

• try ビルド機能を使用し、try ビルドで実行したい CI ジョブを PR の説明で指定します。
• jobs.yml の pr セクションを変更して、 PR への各 push 後にどの CI ジョブを実行するかを指定します。 これは、try ビルドを繰り返し開始するよりも速い場合があります。

PR への各 push 後に実行されるジョブを変更するには、auto セクションから ジョブ定義の 1 つを pr セクションへ単にコピーできます。 たとえば、x86_64-msvc ジョブは 64 ビット MSVC テストを実行する役割を担っています。 これを pr セクションにコピーすると、次のように、PR にコミットが push された後に そのジョブが実行されるようになります。

pr:
  ...
  - image: x86_64-gnu-tools
    <<: *job-linux-16c
  # この項目は `auto` セクションからコピーされました
  # vvvvvvvvvvvvvvvvvv
  - image: x86_64-msvc
    env:
      RUST_CONFIGURE_ARGS: --build=x86_64-pc-windows-msvc --enable-profiler
      SCRIPT: make ci-msvc
    <<: *job-windows-8c

その後、ファイルをコミットし、GitHub 上の PR ブランチへ push できます。 すると GitHub Actions は、PR への各 push 後にこの CI ジョブを実行するはずです。

CI を使用することは歓迎されますが、これは並行実行数に限りがある共有リソースであることを意識してください。 一度にあまり多くのジョブを有効にしないようにしてください。 ほとんどの場合、1 つか 2 つで十分なはずです。

bors による PR の直列マージ

CI サービスは通常、ブランチの最後のコミットを main の最後のコミットとマージしたものをテストします。 これは機能が単独で動作するかどうかを確認するには優れていますが、 マージされた後にコードが動作することを保証するものではありません。 このような破損は通常、ビルドの実行後に、互換性のない別の PR がマージされたときに発生します。

常に動作する main ブランチを確保するため、手動マージは禁止しています。 代わりに、すべての PR は私たちのボットである bors を通じて承認されなければなりません。 承認されたすべての PR は マージキュー に入れられ （優先度と作成日時でソートされ）、1 つずつ自動的にテストされます。 すべてのビルダーが green であれば PR はマージされ、そうでなければ失敗が 記録され、PR は再度承認される必要があります。 Bors は CI サービスと直接やり取りするわけではありませんが、テストしたい マージコミットを特定のブランチ（automation/bors/auto や automation/bors/try など）にプッシュすることで動作します。 これらのブランチは CI チェックを実行するように設定されています。 その後、Bors は Commit Statuses または Check Runs のいずれかをリッスンすることでビルド結果を検出します。 マージコミットは最新の main に基づいており、一度にテストできるのは 1 つだけなので、 結果が green であれば、main はそのマージコミットへ fast-forward されます。

残念ながら、1 度に 1 つの PR しかテストできないことに加え、CI が長時間（フル実行で約 2 時間）かかるため、1 日に多くの PR をマージすることはできず、 1 回の失敗がスループットに大きく影響します。 1 日にマージできる PR の最大数はおよそ ~10 です。

CI の実行時間が長く、大規模なビルダープールが必要になる主な理由は、 完全なリリース成果物が dist- ビルダーでビルドされるためです。 これらのリリース成果物には次の利点があるため、その価値があります。

• 後日であっても perf テストを可能にする。
• 後でバグが見つかったときに二分探索を可能にする。
• 常にリリースしている状態であれば問題を早期に発見できるため、リリース品質を確保できる。

ロールアップ

一部の PR では、フルテストスイートを実行する必要はありません。たとえば、 タイポ修正や README の改善のような些細な変更はビルドを壊すべきではなく、それらすべてを 2 時間以上かけてテストするのは無駄です。 これを解決するために、私たちは定期的に「ロールアップ」を作成します。これは、保留中の些細な PR を複数マージして、 まとめてテストできるようにした PR です。 ロールアップは、チームメンバーが merge queue の “create a rollup” ボタンを使って手動で作成します。 チームメンバーは自身の判断で、PR にリスクがあるかどうかを決定します。

Docker

macOS と Windows 上のものを除くすべての CI ジョブは、そのプラットフォーム専用の Docker container 内で実行されます。 これには私たちにとって多くの利点があります。

• 基盤となるイメージの変更に関係なく、ビルド環境が一貫している （trusty イメージから xenial への切り替えは、私たちにとって問題なく行えました）。

• 最大限のバイナリ互換性を確保するために、古いビルド環境を使用できる。 たとえば、Linux ビルダーでは 古い CentOS リリースを使用しています。

• Docker イメージキャッシュのおかげで、ツール（QEMU や Android エミュレーターなど）を毎回再インストールせずに済む。

• ユーザーは次のコマンドを実行するだけで、同じ環境で同じテストをローカルに実行できる。

  cargo run --manifest-path src/ci/citool/Cargo.toml run-local <job-name>
  

  これは失敗のデバッグに役立ちます。 ライセンスやその他の制約により、ローカルで利用できるのは Linux Docker イメージのみであることに注意してください。

dist- という接頭辞が付いた Docker イメージは成果物のビルドに使用され、 その接頭辞がないものはテストやチェックを実行します。

また、CI ではあまり一般的でないアーキテクチャ（主に Tier 2 および Tier 3 プラットフォーム）のテストも実行します。 これらのプラットフォームは x86 ではないため、すべてを QEMU 内で実行するか、 そのプラットフォームのテストを実行したくない場合はクロスコンパイルのみを行います。

これらのビルダーは、GitHub が私たちのためにセットアップし保守している特別なビルダープール上で実行されています。

キャッシュ

私たちの CI ワークフローでは、主に 2 つの用途でさまざまなキャッシュ機構を使用しています。

Docker イメージのキャッシュ

Linux ベースのビルダーの大半を実行するために使用している Docker イメージは、完全にビルドするのに長い時間がかかります。 ビルドを高速化するために、Docker registry caching を使用してこれらをキャッシュし、中間成果物は ghcr.io に保存しています。 また、ビルド済みの Docker イメージも ghcr にプッシュしているため、他のツール （rustup）や、Docker ビルドをローカルで実行している開発者がそれらを再利用できます（ビルドを高速化するため）。

複数の分岐したブランチ（main、beta、stable）をテストしているため、 イメージに対して単一のキャッシュに依存することはできません。そうしないと、あるブランチ上のビルドが 他のブランチのキャッシュを上書きしてしまいます。 代わりに、すべての Dockerfile と関連スクリプトの内容から作成した カスタムハッシュで識別される、異なるタグの下にイメージを保存しています。

CI はハッシュキーを計算し、次のいずれかが変更された場合に Docker イメージのキャッシュが 無効化されるようにしています。

• Dockerfile
• Dockerfile 内で Docker イメージにコピーされるファイル
• GitHub runner のアーキテクチャ（x86 または ARM）

Sccache による LLVM キャッシュ

私たちはさまざまな CI ジョブで C/C++ のものをいくつかビルドしており、中間 LLVM 成果物をキャッシュするために Sccache に依存しています。 Sccache は Mozilla が開発した分散 ccache であり、 オブジェクトストレージバケットをストレージバックエンドとして使用できます。

Sccache では、ハッシュキーを自分たちで計算する必要はありません。 Sccache は、ソースコード、コンパイラーのバージョン、重要な環境変数など、 関連する入力の変更を検出すると、自動的にキャッシュを無効化します。 そのため、私たちは Cargo の上に Sccache ラッパーを渡すだけで、残りは Sccache が処理します。

永続的な成果物は S3 バケット rust-lang-ci-sccache2 に保存しています。 そのため CI が実行されると、Sccache は、LLVM が同じ C/C++ コンパイラーでコンパイルされており、 LLVM ソースコードが同一であることを確認した場合、個々のコンパイル済み翻訳単位を S3 から取得します。

CI 周辺のカスタムツール

長年にわたり、私たちは CI 体験を改善するためのカスタムツールをいくつか開発してきました。

PR にエラーメッセージを表示する Rust Log Analyzer

rust-lang/rust のビルドログは非常に大きく、ログを見て ビルド失敗の原因を見つけるのは現実的ではありません。 そのため、私たちは Rust Log Analyzer（RLA）というボットを開発しました。このボットは 失敗時にビルドログを受け取り、エラーメッセージを自動的に抽出して、 PR スレッドに投稿します。

このボットはエラー文字列を探すようにハードコードされているわけではなく、多数の ビルド失敗を使って、ビルド間で共通している行とそうでない行を認識するように訓練されています。 生成されるスニペットがときどき奇妙になることはありますが、このボットは、 これまで見たことのないエラーであっても、関連する行を特定するのにかなり優れています。

許可された失敗をサポートする Toolstate

rust-lang/rust リポジトリは CI でコンパイラーだけをテストしているわけではなく、 さまざまなツールやドキュメントもテストしています。 一部のドキュメントは git サブモジュール経由で取り込まれます。 ドキュメントが修正されるまで rustc PR のマージをブロックしてしまうと、私たちは 鶏と卵の問題に陥ってしまいます。なぜなら、そのドキュメントの CI は、 テスト対象としてまだマージされていないバージョンの rustc を必要とするため、更新しても通らないからです （そして通常、CI が通っていることを要求しています）。

この問題を避けるため、サブモジュールの失敗は許可され、その状態は rust-toolstate に記録されます。 サブモジュールが壊れると、ボットが自動的に メンテナーに ping して破損を知らせ、その失敗を toolstate リポジトリに記録します。 その後、リリースプロセスは nightly 上の壊れたツールを無視し、 配布される nightly からそれらを削除します。 ツールの失敗はほとんどの場合許容されますが、リリースの 1 週間前には自動的に禁止されます。nightly でツールが壊れているかどうかは問題にしませんが、beta と stable では動作しなければならないため、nightly を beta に昇格させる数日前には nightly でも動作している必要があります。

詳細は toolstate ドキュメントで確認できます。

公開 CI ダッシュボード

Rust CI を監視するには、infra チームが管理している公開ダッシュボードを確認できます。

以下は、ダッシュボード内の便利なパネルです。

• パイプライン所要時間: auto ビルドの実行にどれくらい時間がかかるかを確認します。
• 最も遅いジョブ: 実行に最も時間がかかっているジョブを確認します。
• ジョブ所要時間の中央値の変化: 以前より遅くなっているジョブを確認します。 これはリグレッションの検出に役立ちます。
• 最も失敗しているジョブ: 最も多く失敗しているジョブを確認します。

ダッシュボードの詳細については、Datadog CI ドキュメントを参照してください。

CI 設定の判定

特定のジョブについて、CI でどの bootstrap.toml 設定が使用されているかを判定したい場合は、ビルドログを見るのが最も簡単でしょう。 そのためには、次のようにします。

1. Rust CI の成功したワークフロー実行ページに移動し、 最新のものをクリックします。
2. 左側で、関心のあるジョブを選択します。
3. 歯車アイコンをクリックし、“View raw logs” を選択します。
4. 文字列 “Configure the build” を検索します。
5. すべてのビルド設定は、build.configure-args というテキストがある行に一覧表示されています。

新しいテストの追加

一般に、rustc のバグを修正するすべての PR には、何らかの回帰テストが 付随していることを期待しています。 このテストは main では失敗し、PR 後には 成功する必要があります。 これらのテストは、過去の過ちを繰り返さないようにするために 非常に役立ちます。

最初に決めるべきことは、どの種類のテストを追加するかです。 これは変更の性質と、何を検証したいかによって決まります。 大まかなガイドラインをいくつか示します。

• コンパイラーテストの大半は compiletest で行われます。
  • compiletest テストの大半は、tests/ui ディレクトリにある UI テストです。
• 標準ライブラリへの変更は、通常、標準ライブラリ内でテストされます。
  • 標準ライブラリのテストの大半は、典型的な API の挙動を例示し検証する doctest として書かれます。
  • 追加のユニットテストは library/${crate}/tests に置く必要があります（${crate} は通常 std です）。
  • alloc または core クレートのテストは、それぞれ別のクレート alloctests または coretests に置かなければなりません。
    • NOTE: 不安定な機能のユニットテストを追加する場合、#![feature(...)] 宣言は library/${crate}tests/lib.rs ではなく library/${crate}tests/tests/lib.rs に追加しなければなりません。
• コードが独立したシステムの一部であり、コンパイラー出力をテストしていない場合は、 ユニットテストまたは統合テストの使用を検討してください。
• rustdoc を実行する必要がありますか？ rustdoc または rustdoc-ui テストを優先してください。 場合によっては rustdoc-js も必要になります。
• その他の compiletest テストスイートは、一般に特別な目的で使用されます。
  • gdb または lldb を実行する必要がありますか？ debuginfo テストスイートを使用してください。
  • LLVM IR または MIR IR を調べる必要がありますか？ codegen または mir-opt テストスイートを使用してください。
  • 生成されたバイナリを何らかの方法で調べる必要がありますか？ あるいは他のすべてのテストスイートでは目的に対して制限が強すぎますか？ その場合は run-make を使用してください。
    • ツリー内の rustc と組み合わせてツリー内の cargo を検証する必要がある場合は、 run-make-cargo を使用してください。
  • より専門的なテストスイートについては、compiletest の章を参照してください。

追加するテストの種類を決めたら、長期にわたって扱いやすいテストを作成する方法について、 ベストプラクティスを参照してください （つまり、数年後にテストが失敗したり変更が必要になったりした場合に、 どうすれば作業を容易にできるか、ということです）。

UI テストの手順

以下は、最も一般的なコンパイラーテストの 1 つである UI テストを作成するための基本的なガイドです。 このチュートリアルでは、async のエラーメッセージ用のテストを追加します。

ステップ 1: テストファイルを追加する

最初のステップは、tests/ui ツリー内のどこかに Rust ソースファイルを 作成することです。 テストを作成するときは、適切な場所と名前を見つけるよう最善を尽くしてください （詳細はテストの整理を参照）。 命名は開発で最も難しい部分なので、 ここから先はすべて楽になるはずです！

async テストを tests/ui/async-await/await-without-async.rs に置きましょう。

// ユーザーが非`async`関数内で`await`を書いたときに診断を提供する。
//@ edition:2018

async fn foo() {}

fn bar() {
    foo().await
}

fn main() {}

このテストについて注目すべき点がいくつかあります。

• 先頭は、テストの目的を説明する短いコメントで 始める必要があります。
• //@ edition:2018 コメントはディレクティブと呼ばれ、 テストをどのようにビルドするかについて compiletest に指示を提供します。 ここでは、async が動作するようにエディションを 設定する必要があります（デフォルトは 2015 エディションです）。
• その後にテストのソースが続きます。 簡潔で要点を押さえたものにするようにしてください。 バグ報告から例を最小化しようとしている場合は、 ある程度の労力が必要になることがあります。
• このテストは空の fn main 関数で終えています。 これは、UI テストのデフォルトが bin クレートタイプであり、テストに「main not found」エラーを 出したくないためです。 代わりに、#![crate_type="lib"] を追加することもできます。

ステップ 2: 期待される出力を生成する

次のステップは、コンパイラーから期待される出力スナップショットを作成することです。 これは --bless オプションで行えます。

./x test tests/ui/async-await/await-without-async.rs --bless

これにより、コンパイラーがビルドされ（まだビルドされていない場合）、 テストがコンパイルされ、コンパイラーの出力が tests/ui/async-await/await-without-async.stderr というファイルに配置されます。

しかし、このステップは失敗します！ 次のようなエラーメッセージが表示されるはずです。

error: /rust/tests/ui/async-await/await-without-async.rs:7: unexpected error: ‘7:10: 7:16: await is only allowed inside async functions and blocks E0728’

これは、stderr にソースファイル内のエラーアノテーションと一致しないエラーが 含まれているためです。

ステップ 3: エラーアノテーションを追加する

すべてのエラーには、エラーのテキストを含むコメントでソース内に アノテーションを付ける必要があります。 この場合、次のコメントをテストファイルに追加できます。

fn bar() {
    foo().await
    //~^ ERROR `await`は`async`関数およびブロック内でのみ許可されています
}

//~^ の波線キャレットコメントは、そのエラーが 前の行に属していることを compiletest に伝えます （詳細はエラーアノテーションセクションを参照）。

保存して、もう一度テストを実行します。

./x test tests/ui/async-await/await-without-async.rs

これで成功するはずです。やった！

ステップ 4: 出力を確認する

前のステップとある程度並行して、作成された .stderr ファイルを確認し、 期待どおりに見えるかを調べる必要があります。 新しい診断メッセージを追加している場合は、 メッセージ全体がどれだけ読みやすく見えるか、 特に Rust に慣れていない人にとってどうかも考えるよい機会です。

例の tests/ui/async-await/await-without-async.stderr ファイルは 次のようになります。

error[E0728]: `await` is only allowed inside `async` functions and blocks
  --> $DIR/await-without-async.rs:7:10
   |
LL | fn bar() {
   |    --- this is not `async`
LL |     foo().await
   |          ^^^^^^ only allowed inside `async` functions and blocks

error: aborting due to previous error

For more information about this error, try `rustc --explain E0728`.

通常のコンパイラー出力とは少し異なって見える点があることに 気づくかもしれません。

• $DIR は、システム間で異なるパス情報を取り除きます。
• LL 値は行番号を置き換えます。 これにより、ソース内の小さな変更が大きな差分を引き起こすことを避けられます。 詳細は正規化セクションを参照してください。

この段階では、最後のいくつかのステップを何度か繰り返して、 テストを調整し、テストを再 bless し、出力を再確認する必要があるかもしれません。

ステップ 5: 他のテストを確認する

診断メッセージを追加または変更すると、テストスイート内の他のテストに 影響することがあります。 PR を投稿する前の最後のステップは、他に影響を与えていないかを 確認することです。 通常は UI スイートを実行するのが良い出発点です。

./x test tests/ui

他のテストが失敗し始めた場合、何が変更されたのか、そして 新しい出力が妥当かどうかを調査する必要があるかもしれません。

また、--bless フラグを使って出力を再承認する必要があるかもしれません。

テストの内容を説明するコメント

テストファイルの最初のコメントは、テストの要点を要約し、 そのテストで何が重要なのかを強調するべきです。 そのテストに関連する issue 番号がある場合は、その issue 番号を含めてください。

このコメントは、それほど詳しくする必要はありません。 次のようなものだけでも十分な場合があります: 「#18060 の回帰テスト: match アームが誤った順序でマッチしていた」。

これらのコメントは、後であなたのテストが壊れたときに、他の人にとって非常に役立ちます。なぜなら、 問題が何であるかを強調できることが多いからです。 また、何らかの 理由でテストをリファクタリングする必要がある場合にも役立ちます。なぜなら、そのテストのどの部分が 重要だったのかを他の人に知らせてくれるからです。 多くの場合、テストは本来テストするはずだったことを もはやテストしなくなったために書き直さなければならず、その場合、そのテストが正確に何をテストする はずだったのかを知ることが役立ちます。

テストを書くためのベストプラクティス

この章では、テストの作成と変更に関するベストプラクティスについて説明します。 私たちが作成するテストは、何年も後になっても、元の作成者に確認したり、 大量の git 考古学を行ったりする必要なく、理解しやすく変更しやすいものにしたいと考えています。

自分が作成したテストを、数年後にあまり文脈がない状態で失敗したテストを見ている 別のコントリビューターになったつもりでレビューするのはよい習慣です （これは数日後や数か月後の自分自身にも役立ちます！）。 そして自問してください。どうすれば自分やその人たちの作業を楽にできるだろうか？

これを具体的に捉えやすくするため、まずは、別のコントリビューターの作業を 可能な限り困難にするテストを書く方法についての余談から始めましょう。

余談: シンプルなテスト妨害フィールドマニュアル

別のコントリビューターの作業を可能な限り困難にするには、次のようなことをするとよいでしょう。

• テストに、他の文脈を一切含めず issue 番号だけの名前を付ける。例: issue-123456.rs。
• そのテストが何を検証しようとしているのかについてのコメントや、関連する文脈へのリンクを 一切含めない。
• （本来は最小化できるにもかかわらず）巨大なテストを含め、 そのテストが実際にテストしようとしている核心から注意をそらす、 本質的でない部分を含める。
• テストが確認しようとしている内容にとって重要ではない、無関係な構文エラーやその他のエラーを 大量に含める。
• スニペットを奇妙な形式で整形する。
• 使用されておらず無関係な機能を大量に含める。
• たとえば ignore-windows compiletest directives を含めるが、それらが なぜ 必要なのかについて説明しない。

テストの命名

読者が、issue 番号を入力して github 検索を掘り進め、 そのテストが何を検証しようとしているのかを探さなくても済むように、 テストが何を検証しているのかをすぐに理解できるようにします。 これには、関連するテストの集まりとして --test-args でテストをフィルターできるようになる、 という追加の利点もあります。

• テストが検証しようとしている内容、または回帰を防ごうとしている内容に基づいて名前を付ける。
• 簡潔に保つ。
• issue 番号だけをテスト名として使うのを避ける。
• 自動補完の劣化につながるため、テスト名を issue-xxxxx プレフィックスで始めるのを避ける。

issue 番号だけをテスト名として使うのを避ける

代わりに、テストコメント内のリンクや #123456 として含めることを推奨します。あるいは、 issue 番号を含めることに意味がある場合は、 macro-external-span-ice-123956.rs のような短いキーワードも含めてください。

tests/ui/typeck/issue-123456.rs                              // 悪い
tests/ui/typeck/issue-123456-asm-macro-external-span-ice.rs  // 悪い（タブ補完にとって）
tests/ui/typeck/asm-macro-external-span-ice-123456.rs        // 良い
tests/ui/typeck/asm-macro-external-span-ice.rs               // 良い

issue-123456.rs は、そのテストが実際に何を検証しているのかをすぐには何も教えてくれないため、 追加で検索する必要があります。テスト名のプレフィックスとして issue 番号を含めると、 タブ補完の有用性が下がります （テストディレクトリで ls したときに issue-xxxxx プレフィックスが大量に出てくる場合など）。 issue へのリンクはテストコメント内に置くことができます。

//! 外部クレート由来のネストしたマクロを含む `asm!` マクロが、
//! コードポイント境界アサーション ICE につながらないことを確認する。
//!
//! <https://github.com/rust-lang/rust/issues/123456> の回帰テスト。

このルールの例外の 1 つが crash tests です。そこでは、 テストが issue 番号だけで命名されるのが標準です。というのも、その目的は、 もはや ICE/クラッシュしなくなった issue 由来のスニペットを追跡することであり、 それらは修正 PR で削除されるか、適切な ui/その他のテストへ変換されるためです。

テストの構成

• ほとんどのテストスイートでは、テストを置くための意味的に適切なサブディレクトリを見つけるようにしてください。
  • たとえば、RFC 2093 の実装に特化した場合、 tests/ui/rfc-2093-infer-outlives/ 配下に一連のテストをまとめることができます。 ディレクトリ名には、その RFC が何に関するものかを含めてください。
• run-make/run-make-support テストスイートでは、それぞれの rmake.rs は、 それぞれ tests/run-make/ または tests/run-make-cargo/ の直下のサブディレクトリ内に 含まれていなければなりません。 現時点では、さらに深いネストはサポートされていません。 この場合も、テスト名に issue 番号「だけ」を使うのは避けてください。

テストの説明

変更によってテストが失敗した場合に、他のコントリビューターがそのテストの内容を理解できるように、 テストには、その意図/目的、関連する文脈へのリンク（issue 番号やその他の議論を含む）、 場合によっては関連リソース（たとえば、特定の挙動について Win32 API へリンクすると役立つことがあります） について十分なドキュメントを含めるべきです。

よいコメントを含むテストの概要

//! テストが何を検証しているのかの簡潔な概要。
//! 例: #123456 の回帰テスト: coverage 属性が非 item に適用されたときに
//!     ICE しないことを確認する。
//!
//! 任意: 関連するテスト/issue、外部 API/ツール、クラッシュの
//!     仕組み、どのように修正されたか、FIXME、制限事項などについての備考。
//! 例: このテストは `tests/attrs/linkage.rs` に似ているが、このテストは
//!     異なるコードパスを検証する `#[coverage]` を特に確認している。
//!     ICE は属性検証中に、`def_path_str` を構築しようとしたものの、
//!     プラットフォームが windows の場合にのみ診断を出力したため、
//!     unix で ICE が発生したことで引き起こされた。
//!
//! 関連する issue や議論へのリンク。以下に例を示す:
//! <https://github.com/rust-lang/rust/issues/123456> の回帰テスト。
//! <https://github.com/rust-lang/rust/issues/101345> も参照。
//! <https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler/topic/123456-example-topic> の議論を参照。
//! [`clone(2)`] を参照。
//!
//! [`clone(2)`]: https://man7.org/linux/man-pages/man2/clone.2.html

//@ ignore-windows
// 理由: （なぜこのテストは windows で無視されるのか？なぜ特に
// windows-gnu や windows-msvc ではないのか？）

// 任意: テストケースの概要: どの肯定的ケースが確認されるのか？
// どの否定的ケースが確認されるのか？特有の癖はあるか？

fn main() {
    #[coverage]
    //~^ ERROR coverage attribute can only be applied to function items.
    let _ = {
        // 読者が注意を払うべき点を強調するコメント。
        fn foo() {}
    };
}

どれだけの文脈/説明が必要かは、作成者とレビュー担当者の裁量に委ねられます。 よい経験則として、テストで検証している自明でない事柄には、 他のコントリビューターが理解する助けとなる説明を付けるべきです。 これには、次のような備考が含まれる場合があります。

• ICE が発生する仕組みがかなり複雑な場合、その仕組み。
• 関連する issue やテスト（たとえば、このテストは別のテストに似ているが、 …という理由で分けて維持されている、など）。
• プラットフォーム固有の挙動。
• 外部依存関係や API の挙動: syscall、リンカー、ツール、 環境など。

テスト内容

• テストは可能な限り最小限になるようにしてください。
• 重要でないコードを最小限に抑え、特に stderr スナップショットを乱雑にし得る不要な構文エラーや型エラーを 最小限に抑えてください。
• 関係のない警告を抑制するには、#![allow(...)] または #![expect(...)] を使用してください。
• 可能であれば、意味的に有意義な名前を使用してください（例: fn bare_coverage_attributes() {}）。

不安定なテスト

すべてのテストは、再現可能で信頼できるものになるよう努める必要があります。 不安定なテストは最悪の種類のテストであり、そもそもテストが存在しないことよりも悪いとさえ言えるでしょう。

• 不安定なテストは、まったく関係のない PR で失敗する可能性があり、他の コントリビューターを混乱させ、テストの失敗が関係しているかどうかを調べる時間を浪費させる可能性があります。
• 不安定なテストは、そのテスト結果から有用な情報を何も提供しません。 不安定で信頼できないということ以外は分かりません。テストが成功しても不安定なら、単に運が良かっただけでしょうか？ テストが不安定で失敗したなら、それは単に偶発的なものでしょうか？
• 不安定なテストは、テストスイート全体への信頼を低下させます。 テストスイートが不安定なテストによって ランダムに偶発的に失敗する可能性がある場合、テストスイート全体が成功したのでしょうか、それとも 単に運が良かった／悪かっただけなのでしょうか？
• 不安定なテストはフル CI でランダムに失敗する可能性があり、それまでのフル CI リソースを浪費します。

Compiletest ディレクティブ

ディレクティブの一覧については、compiletest ディレクティブを参照してください。

• ignore-*/needs-*/only-* ディレクティブについては、極めて明白な場合を除き、 そのディレクティブが必要な理由について簡潔な注釈を記載してください。例: "//@ ignore-wasi (wasi codegens the main symbol differently)"。
• //@ ignore-auxiliary を使用する場合は、対応するメインのテストファイルを指定してください。 例: //@ ignore-auxiliary (used by `./foo.rs`)。

FileCheck のベストプラクティス

詳細については、LLVM FileCheck ガイドを参照してください。

• 特定のレジスタ番号や基本ブロック番号がテストにとって特別または重要でない限り、 それらにマッチさせることは避けてください。 適切な場合は、それらにマッチさせるためにパターンを使用することを検討してください。

TODO

具体的な助言は未定です。

Compiletest

はじめに

compiletest は Rust テストスイートの主要なテストハーネスです。 これにより、テスト作成者は大量のテスト（Rust コンパイラには数千ものテストがあります）を整理し、効率的にテストを実行（並列実行がサポートされています）し、個別のテストおよびテストのグループの挙動と期待される結果を設定できます。

macOS ユーザーへの注意

macOS ユーザーの場合、SIP（System Integrity Protection）が Apple にネットワークリクエストを送信して、コンパイル済みバイナリを継続的にチェックする場合があるため、テストの実行時に大幅なパフォーマンス低下が発生することがあります。

次の設定を調整することで解決できます: Privacy & Security -> Developer Tools -> Add Terminal (Or VsCode, etc.)。

compiletest は、テストコードがコンパイル時または実行時に成功/失敗するかをチェックできます。

テストは通常、テストコードの前および/または内部のコメントにアノテーションを付けた Rust ソースファイルとして構成されます。 これらのコメントは、テストを実行するかどうか、どのように実行するか、どのような挙動を期待するかなどを compiletest に指示する役割を果たします。 これらのアノテーションの詳細については、ディレクティブおよび以下のテストスイートのドキュメントを参照してください。

新しいテストを作成するためのチュートリアルや、良いテストを書くための助言については、新しいテストの追加およびベストプラクティスの章を参照してください。また、テストスイートの実行方法については、テストの実行の章を参照してください。

compiletest には --test-args を使用するか、-- の後に配置することで引数を渡せます。例:

• x test --test-args --force-rerun
• x test -- --force-rerun

さらに、bootstrap は一般的な引数をいくつか直接受け付けます。例:

x test --no-capture --force-rerun --run --pass。

Compiletest 自体は、関係するアーティファクト（主にコンパイラ）が変更されていない場合、テストの実行を避けようとします。 入力のいずれも変更されていない場合でもテストを再実行するには、x test --test-args --force-rerun を使用できます。

テストスイート

すべてのテストは tests ディレクトリ内にあります。 テストは「スイート」に整理され、各スイートは個別のサブディレクトリにあります。 各テストスイートは、コンパイラの挙動や正しさのチェック方法が異なり、少しずつ異なる動作をします。 たとえば、tests/incremental ディレクトリにはインクリメンタルコンパイルのテストが含まれています。 各種スイートは、src/tools/compiletest/src/common.rs の pub enum Mode 宣言で定義されています。

詳細情報へのリンク付きで、次のテストスイートを利用できます:

コンパイラ固有のテストスイート

汎用テストスイート

run-make は、Rust プログラムを使用する汎用テストです。

build-std テストスイート

build-std は -Zbuild-std が動作することをテストします。

Rustdoc テストスイート

rustdoc 固有のテストの一部は ui/rustdoc/ にもあります。 これらのテストは、rustdoc の実行の一部として出力される特定の lint が、rustc の実行時にも実行されることを保証します。 rustdoc に関する Run-make テストは通常、run-make/rustdoc-*/ という名前です。

Pretty-printer テスト

tests/pretty 内のテストは、rustc の「pretty-printing」機能を実行します。 rustc の -Z unpretty CLI オプションを使用すると、入力ソースを、マクロ展開後の Rust ソースなど、さまざまな形式に変換します。 プリティプリンターテストには、以下で説明するいくつかのディレクティブがあります。 これらのコマンドはテストの挙動を大きく変更できますが、コマンドがない場合の デフォルトの挙動は次のとおりです。

1. ソースファイルに対して rustc -Zunpretty=normal を実行します。
2. 前のステップの出力に対して rustc -Zunpretty=normal を実行します。
3. 前の 2 つのステップの出力は同じである必要があります。
4. 型チェックできることを確認するために、出力に対して rustc -Zno-codegen を実行します （cargo check と同様）。

上記のコマンドのいずれかが失敗した場合、そのテストは失敗します。

プリティプリントテストのディレクティブは次のとおりです。

• pretty-mode は、プリティプリントテストを実行するモード（つまり、 -Zunpretty への引数）を指定します。 指定されていない場合のデフォルトは normal です。
• pretty-compare-only は、プリティテストでプリティプリントされた 出力のみを比較するようにします（上記のステップ 3 の後で停止します）。 型チェックのために展開された出力をコンパイルしようとはしません。 これは、有効な Rust に展開されない pretty-mode や、 展開された出力をコンパイルできないその他の状況で必要です。
• pp-exact は、プリティプリントテストが特定の出力になることを保証するために使用されます。 値なしで指定された場合、プリティプリント出力は 元のソースと一致する必要があることを意味します。 //@ pp-exact:foo.pp のように値付きで指定された場合、プリティプリントされた出力が 指定されたファイルの内容と一致することを保証します。 それ以外の場合、pp-exact が指定されていなければ、 プリティプリントされた出力はもう一度プリティプリントされ、2 回の プリティプリントの出力が比較されて、プリティプリントされた出力が 定常状態に収束することを確認します。

インクリメンタルテスト

tests/incremental のテストはインクリメンタルコンパイルをテストします。 これらは revisions ディレクティブを使用して、compiletest にコンパイラーを 一連のステップで実行するよう指示します。

Compiletest は -C incremental フラグ付きの空のディレクトリから開始し、 その後、前のステップのインクリメンタル結果を再利用しながら、各リビジョンに対してコンパイラーを実行します。

各リビジョン名は、次のいずれかで始まる必要があります。

• cpass - テストは正常にコンパイルされなければなりません（チェックビルド、コード生成なし）
• bfail — テストはコンパイルに失敗しなければなりません（完全ビルド、コード生成あり）
• bpass — テストは正常にコンパイルされなければなりません（完全ビルド、コード生成あり）
• rpass — テストは正常にコンパイルおよび実行されなければなりません

リビジョンを一意にするには、rpass1 や rpass2 のようなサフィックスを追加する必要があります。

ソースの変更をシミュレートするために、compiletest は現在のリビジョン名を指定した --cfg フラグも渡します。

たとえば、これは関数の変更をシミュレートして 2 回実行されます。

//@ revisions: rpass1 rpass2

#[cfg(rpass1)]
fn foo() {
    println!("one");
}

#[cfg(rpass2)]
fn foo() {
    println!("two");
}

fn main() { foo(); }

インクリメンタルテストは、特定の部分文字列がコンパイラー出力のどこにも 現れてはならないことを指定する forbid-output ディレクティブをサポートしています。 これは、特定のエラーが現れないことを保証するのに有用ですが、エラーメッセージは 時間とともに変わるため壊れやすく、テストがもはや適切な内容をチェックしていなくても合格し続ける可能性があります。

インクリメンタルテストでは #[rustc_clean(...)] 属性を使用できます。 この属性は、現在のコンパイルセッションのフィンガープリントを前回のものと比較します。 最初のリビジョンでは、有効な rustc_clean 属性を決して持つべきではありません。これは常に dirty になるためです。

デフォルトモードでは、フィンガープリントが同じでなければならないことをアサートします。 この属性は次の引数を取ります。

• cfg="<cond>" — cfg 条件 <cond> をチェックし、その cfg 条件が true と評価された場合にのみチェックを実行します。 これは、特定のリビジョンでのみ rustc_clean 属性を実行するために使用できます。
• except="<query1>,<query2>,..." — 列挙されたクエリについて、クエリ結果が同じではなく 異なっていなければならないことをアサートします。
• loaded_from_disk="<query1>,<query2>,..." — 列挙されたクエリについて、クエリ結果が 実際にディスクから読み込まれたことをアサートします（単に green とマークされたのではありません）。 これは、テストが特定のクエリ結果について実際にデシリアライズ ロジックを実行していることを保証するのに有用です。 これは except と組み合わせることができます。

rustc_clean を使用するテストの簡単な例は hello_world test です。

Debuginfo テスト

tests/debuginfo のテストはデバッグ情報の生成をテストします。 これらはプログラムをビルドし、デバッガーを起動し、デバッガーにコマンドを発行します。 1 つのテストは cdb、gdb、lldb で動作できます。

ほとんどのテストには、適切なデバッグ情報を生成するために、 //@ compile-flags: -g ディレクティブまたはそれに類するものを含めるべきです。

行にブレークポイントを設定するには、その行に // #break コメントを追加します。

デバッグ情報テストは、一連のデバッガーコマンドと、 デバッガーから期待される出力を指定する “check” 行で構成されます。

コマンドは // $DEBUGGER-command:$COMMAND という形式のコメントであり、 $DEBUGGER は使用されているデバッガー、$COMMAND は実行するデバッガーコマンドです。

デバッガーの値として使用できるものは次のとおりです。

• cdb
• gdb
• gdbg — Rust サポートなしの GDB（7.11 より古いバージョン）
• gdbr — Rust サポートありの GDB
• lldb
• lldbg — Rust サポートなしの LLDB
• lldbr — Rust サポートありの LLDB（これは現在は存在しません）

出力をチェックするコマンドは // $DEBUGGER-check:$OUTPUT という形式であり、 $OUTPUT は期待される出力です。

たとえば、次はテストをビルドし、デバッガーを開始し、 ブレークポイントを設定し、プログラムを起動し、値を調べ、デバッガーが出力する内容をチェックします。

//@ compile-flags: -g

//@ lldb-command: run
//@ lldb-command: print foo
//@ lldb-check: $0 = 123

fn main() {
    let foo = 123;
    b(); // #break
}

fn b() {}

現在使用されているデバッガーに基づいてテストを無効化するために、次の ディレクティブを使用できます。

• min-cdb-version: 10.0.18317.1001 — cdb のバージョンが指定されたバージョン未満の場合、 テストを無視します
• min-gdb-version: 8.2 — gdb のバージョンが指定されたバージョン未満の場合、テストを無視します
• ignore-gdb-version: 9.2 — gdb のバージョンが指定されたバージョンと等しい場合、 テストを無視します
• ignore-gdb-version: 7.11.90 - 8.0.9 — gdb のバージョンが 範囲内（両端を含む）の場合、テストを無視します
• min-lldb-version: 310 — lldb のバージョンが指定されたバージョン未満の場合、テストを無視します
• rust-lldb — lldb に Rust プラグインが含まれていない場合、テストを無視します。 注: “Rust” 版の LLDB はもう存在しないため、これは常に無視されます。 これはおそらく削除すべきです。

compiletest に --debugger オプションを渡すことで、テストを実行する単一のデバッガーを指定できます。 たとえば、./x test tests/debuginfo -- --debugger gdb は GDB コマンドのみをテストします。

lldb debuginfo テストをローカルで実行する際の注意

lldb debuginfo テストをローカルで実行したい場合、現時点では Windows で 次のことが必要です:

• Python 3.10 がインストールされていること。
• python310.dll が PATH 環境変数で利用可能であること。これは python.org から入手する標準の Python インストーラーでは提供されません。 手動で PATH に追加する必要があります。

そうしないと、lldb debuginfo テストが不可解な形でクラッシュする可能性があります。

Windows 11 で cdb.exe を取得する際の注意

cdb.exe は、Visual Studio インストーラー（例: Visual Studio 2022 インストーラー）の 「Desktop Development with C++」ワークロードプロファイルの一部である、適切な 「Windows 11 SDK」とともに取得されます。

ただし、既定ではこれだけでは十分ではありません。cdb.exe が必要な場合は、 Installed Apps に移動し、最新の「Windows Software Development Kit」を見つける必要があります （そして、OS が Windows 11 と呼ばれているにもかかわらず、これが Windows 10.0.22161.3233 と表示されることもあります）。その後、 cdb.exe を取得するために、「Modify」->「Change」をクリックしてから、 「Debugging Tools for Windows」を選択する必要があります。

コード生成テスト

tests/codegen-llvm のテストは LLVM コード生成をテストします。 これらは、--emit=llvm-ir フラグを指定してテストをコンパイルし、LLVM IR を出力します。 その後、LLVM の FileCheck ツールを実行します。 テストには、生成されたコードをチェックするためにさまざまな // CHECK コメントが注釈として付けられます。 チュートリアルおよび詳細については、FileCheck ドキュメントを参照してください。

同様の一連のテストについては、アセンブリテスト も参照してください。

既定では、コード生成テストには //@ needs-target-std が 暗黙的に 指定されます （ターゲットが std をサポートする必要があることを意味します）。ただし、 テストソースで #![no_std]/#![no_core] 属性が指定されている場合は除きます。 この動作を上書きして、テストが #![no_std]/#![no_core] であっても、 ターゲットが std をサポートする場合にのみテストを実行するように、 明示的に //@ needs-target-std と書くことができます。

#![no_std] のクロスコンパイルテストを扱う必要がある場合は、 minicore テスト補助 の章を参照してください。

アセンブリテスト

tests/assembly-llvm のテストは LLVM アセンブリ出力をテストします。 これらは、--emit=asm フラグを指定してテストをコンパイルし、アセンブリ出力を含む .s ファイルを出力します。 その後、LLVM の FileCheck ツールを実行します。

各テストには、アセンブリ出力の種類を示すために、 emit-asm または ptx-linker のいずれかの値を持つ //@ assembly-output: ディレクティブを注釈として付ける必要があります。

次に、アセンブリ出力をチェックするために、さまざまな // CHECK コメントを注釈として付ける必要があります。 チュートリアルおよび詳細については、FileCheck ドキュメントを参照してください。

同様の一連のテストについては、コード生成テスト も参照してください。

#![no_std] のクロスコンパイルテストを扱う必要がある場合は、 minicore テスト補助 の章を参照してください。

命令サポートに基づく条件付きアセンブリテスト

特定のアセンブリ命令が利用可能であることに依存するテストでは、 //@ needs-asm-mnemonic: <MNEMONIC> ディレクティブを使用できます。 ターゲットバックエンドが指定された命令ニーモニックをサポートしていない場合、このテストはスキップされます。

たとえば、RET 命令を必要とするテストは次のとおりです:

//@ needs-asm-mnemonic: RET

Codegen-units テスト

tests/codegen-units のテストは、 単相化 コレクターと CGU 分割をテストします。

これらのテストは、単相化コレクションパスの結果を出力するフラグ、 すなわち -Zprint-mono-items を指定して rustc を実行し、 その後、ファイル内の特別な注釈を使用してそれと比較することで動作します。

次に、テストには //~ MONO_ITEM name という形式のコメントを注釈として付ける必要があります。 ここで name は、fn <u32 as Trait>::foo のように rustc によって出力される単相化済み文字列です。

CGU 分割をチェックするには、//~ MONO_ITEM name @@ cgu という形式のコメントを使用します。 ここで cgu は、CGU 名と角括弧内のリンケージ情報を空白区切りにしたリストです。 例: //~ MONO_ITEM static function::FOO @@ statics[Internal]

Mir-opt テスト

tests/mir-opt のテストは、生成された MIR の一部をチェックし、 それが正しく生成され、期待される最適化を行っていることを確認します。 詳細については、MIR 最適化 の章を確認してください。

Compiletest は、MIR 出力をダンプして最適化のベースラインを設定するために、 いくつかのフラグを指定してテストをビルドします:

• -Copt-level=1
• -Zdump-mir=all
• -Zmir-opt-level=4
• -Zvalidate-mir
• -Zdump-mir-exclude-pass-number

テストには、期待される MIR 出力を含むファイルを指定する // EMIT_MIR コメントを注釈として付ける必要があります。 初期の期待ファイルを作成するには、x test --bless を使用できます。

EMIT_MIR コメントにはいくつかの形式があります:

• // EMIT_MIR $MIR_PATH.mir — これは、指定されたファイル名が MIR ダンプからの正確な出力と一致することをチェックします。 たとえば、 my_test.main.SimplifyCfg-elaborate-drops.after.mir はそのファイルを テストディレクトリから読み込み、rustc からのダンプと比較します。

  “after” ファイル（最適化後のもの）をチェックすることは、 最適化後の最終状態に関心がある場合に有用です。 完全性のために “before” ファイルを使用したいまれなケースもあります。

• // EMIT_MIR $MIR_PATH.diff — ここで $MIR_PATH は、 my_test_name.my_function.EarlyOtherwiseBranch のような MIR ダンプのファイル名です。 Compiletest は .before.mir ファイルと .after.mir ファイルの差分を取り、その diff 出力を EMIT_MIR コメントの期待される .diff ファイルと比較します。

  これは、最適化によって MIR がどのように変化するかを確認したい場合に有用です。

• // EMIT_MIR $MIR_PATH.dot — 追加の MIR データをダンプする特定のフラグ （例: .dot ファイルを生成する -Z dump-mir-graphviz）を使用している場合、 これは出力が指定されたファイルと一致することをチェックします。

既定では、32 ビットターゲットと 64 ビットターゲットは同じダンプファイルを使用しますが、 定数内のポインターやその他のビット幅に依存するものが存在する場合、これは問題になる可能性があります。 その場合は、テストに // EMIT_MIR_FOR_EACH_BIT_WIDTH を追加することで、 32bit システムと 64bit システム用に別々のファイルが生成されるようにできます。

run-make テスト

tests/run-make および tests/run-make-cargo のテストは、Rust レシピ を使用する汎用 テストです。これは任意の Rust コード（rustc の呼び出しなど）を可能にする小さなプログラム （rmake.rs）であり、run_make_support ライブラリによってサポートされています。 Rust レシピを使用すると、究極の柔軟性が得られます。

run-make テストは、他のどのテストスイートもニーズにより適していない場合に使用する必要があります。 run-make-cargo テストスイートはさらに、ツリー内の cargo をビルドして、 ツリー内の rustc と組み合わせてツリー内の cargo をテストする必要がある ユースケースをサポートします。 run-make テストスイートはツリー内の cargo にアクセスできません（そのため、 反復をより高速に行えるテストスイートにできます）。

build-std テスト

tests/build-std 内のテストは、-Zbuild-std が動作することを確認します。 これは現在、単一のレシピを持つ run-make テストスイートにすぎません。 このレシピはテストケースを生成し、それらを並列に実行します。

Rust レシピの使用

各テストは、rmake.rs Rust プログラムを持つ個別のディレクトリに配置する必要があります。 このプログラムはレシピと呼ばれます。レシピは、run_make_support ライブラリがリンクされた状態で compiletest によってコンパイルされ、実行されます。

新しいユーティリティや機能が必要な場合は、 run_make_support ライブラリを拡張し、改善することを検討してください。

//@ only-<target> や //@ ignore-<target> のような Compiletest ディレクティブは、 UI テストと同様に rmake.rs でサポートされています。 ただし、リビジョンやディレクティブによる補助ファイルのビルドは、現在サポートされていません。

rmake.rs と run-make-support は、nightly/unstable 機能を使用してはなりません。 これらは、beta または stable rustc である可能性のある stage 0 rustc でコンパイルできなければならないためです。

デフォルトでは、run-make テストは各サブプロセスコマンドとその stdout/stderr を出力します。 cg_clif などの panic=abort テストスイートで --no-capture を指定して実行すると、 これにより端末が大量の出力で埋め尽くされる可能性があります。 成功したテストでこの出力を抑制するには、 --verbose-run-make-subprocess-output を省略してください。失敗したテストは常に出力されます。

./x test tests/run-make --no-capture --verbose-run-make-subprocess-output=false

rmake.rs テストがコンパイルできるかを素早く確認する

rmake.rs を stage0 コンパイラでコンパイルするよう強制することで、 stage1 rustc をビルドせずに rmake.rs テストがコンパイルできるかを素早く確認できます。

$ COMPILETEST_FORCE_STAGE0=1 x test --stage 0 tests/run-make/<test-name>

もちろん、一部のテストはこの方法では正常に実行されません。

rmake.rs で rust-analyzer を使用する

他のテストプログラムと同様に、run-make テストで使用される rmake.rs スクリプトには、 デフォルトでは rust-analyzer 連携がありません。

特定のテストで作業しているときにこれを回避するには、 テストのディレクトリに一時的に Cargo.toml ファイルを作成します （例: tests/run-make/sysroot-crates-are-unstable/Cargo.toml）。 内容は次のとおりです。

# これが外側のワークスペースの一部ではないことを cargo に認識させる。
[workspace]

[package]
name = "rmake"
version = "0.1.0"
edition = "2021"

[dependencies]
run_make_support = { path = "../../../src/tools/run-make-support" }

[[bin]]
name = "rmake"
path = "rmake.rs"

次に、対応するエントリを "rust-analyzer.linkedProjects" に追加します （例: .vscode/settings.json）。

"rust-analyzer.linkedProjects": [
  "tests/run-make/sysroot-crates-are-unstable/Cargo.toml"
],

カバレッジテスト

tests/coverage 内のテストは、異なる方法でカバレッジ計測をテストする複数のテストモードで共有されます。 coverage テストスイートを実行すると、 各テストがすべての異なるカバレッジモードで自動的に実行されます。

各モードには、そのモードだけでカバレッジテストを実行するためのエイリアスもあります。

./x test coverage # tests/coverage のすべてをすべてのカバレッジモードで実行する
./x test tests/coverage # 上と同じ

./x test tests/coverage/if.rs # 指定されたテストをすべてのカバレッジモードで実行する

./x test coverage-map # tests/coverage のすべてを "coverage-map" モードのみで実行する
./x test coverage-run # tests/coverage のすべてを "coverage-run" モードのみで実行する

./x test coverage-map -- tests/coverage/if.rs # 指定されたテストを "coverage-map" モードのみで実行する

何らかの理由で、特定のテストをカバレッジテストモードのいずれかで実行すべきでない場合は、 //@ ignore-coverage-map または //@ ignore-coverage-run ディレクティブを使用してください。

coverage-map スイート

coverage-map モードでは、これらのテストは LLVM によって出力される ソースコード領域とカバレッジカウンターの間のマッピングを検証します。 テストを --emit=llvm-ir でコンパイルし、その後カスタムツール（src/tools/coverage-dump）を使用して、 IR に埋め込まれたカバレッジマッピングを抽出し、整形して出力します。 これらのテストはプロファイラーランタイムを必要としないため、PR CI ジョブで実行され、ローカルでの 実行や bless が容易です。

これらのカバレッジマップテストは、MIR lowering や MIR 最適化の変更に影響を受けやすく、 異なるものの同一のカバレッジレポートを生成するマッピングを生じることがあります。

経験則として、カバレッジ固有のコードを変更しない PR では、 coverage-run テストが引き続き成功している限り、実際の変更を気にすることなく、 必要に応じて coverage-map テストを遠慮なく re-bless してください。

coverage-run スイート

coverage-run モードでは、これらのテストはカバレッジレポートのエンドツーエンドテストを実行します。 カバレッジ計測を有効にしてテストプログラムをコンパイルし、そのプログラムを実行して 生のカバレッジデータを生成し、その後 LLVM ツールを使用してそのデータを 人間が読めるコードカバレッジレポートに処理します。

計測されたバイナリは LLVM プロファイラーランタイムにリンクされる必要があるため、 coverage-run テストは、bootstrap.toml でプロファイラーランタイムが有効になっていない限り 自動的にスキップされます。

build.profiler = true

これはまた、これらが通常 PR CI ジョブでは実行されないことを意味します。ただし、マージに使用される CI ジョブ一式の一部としては実行されます。

coverage-run-rustdoc スイート

tests/coverage-run-rustdoc 内のテストは、計測された doctest も実行し、 それらをカバレッジレポートに含めます。 これにより、メインの coverage スイートのみを実行する場合に rustdoc をビルドする必要がなくなります。

クラッシュテスト

tests/crashes は、コンパイラが ICE、panic、またはその他の方法でクラッシュすることが期待される テストのコレクションとして機能し、意図しない修正が追跡されるようにします。 以前は、これは https://github.com/rust-lang/glacier で行われていましたが、 rust-lang/rust testsuite の内部で行う方が便利です。

このスイート内のテストが rustc に ICE、panic、またはその他の方法でクラッシュを引き起こさせることは必須です。 rustc が 1 または 0 以外の終了ステータスで終了した場合、テストは「成功」します。

詳細な stdout/stderr を確認したい場合は、 COMPILETEST_VERBOSE_CRASHES=1 を設定する必要があります。例:

$ COMPILETEST_VERBOSE_CRASHES=1 ./x test tests/crashes/999999.rs --stage 1

誰でも、issue tracker から “untracked” crashes を追加できます。 1 つの PR に複数の issue のテストケースを含めることを強く推奨します。 そうする場合、各 issue 番号をファイル名に記載し（12345.rs で十分です）、 さらにファイル内にも //@ known-bug: #12345 ディレクティブで記載してください。 PR がマージされたら、関連する issue に S-bug-has-test をラベル付けしてください。

クラッシュのいずれかを修正した場合は、それを tests/ui 内の適切な サブディレクトリに移動し、意味のある名前を付けてください。 このテストが存在する理由を説明する doc comment をファイルの先頭に追加してください。 以前はその例によって rustc がどのようにクラッシュしていたのか、 またそれを修正するために何が行われたのかを簡潔に説明できるとなお良いです。

プルリクエストの説明に

Fixes #NNNNN
Fixes #MMMMM

を追加すると、マージ時に対応するチケットが自動的にクローズされます。

修正がまず issue のサブセットだけでなく、根本原因を実際に修正していることを確認してください。 issue 番号は、ファイル名またはテストファイル内の //@ known-bug ディレクティブで確認できます。

補助クレートのビルド

一部のテストでは、追加の補助クレートをコンパイルする必要があることがよくあります。 これを支援する複数のディレクティブがあります。

• aux-build
• aux-crate
• aux-bin
• aux-codegen-backend
• proc-macro

aux-build は、指定されたソースファイルから別のクレートをビルドします。 ソースファイルは、テストファイルの隣にある auxiliary というディレクトリ内に置く必要があります。

//@ aux-build: my-helper.rs

extern crate my_helper;
// ... my_helper を使用できます。

aux クレートは、可能であれば dylib としてビルドされます（それをサポートしていないプラットフォームの場合、 または aux ファイル内で no-prefer-dynamic ヘッダーが指定されている場合を除きます）。 extern クレートを見つけるために -L フラグが使用されます。

aux-crate は aux-build と非常によく似ています。 ただし、extern クレートにリンクするために --extern フラグを使用し、 そのクレートを extern prelude として利用できるようにします。 これにより、依存関係の名前変更など、--extern フラグの追加構文を指定できます。 たとえば、//@ aux-crate:foo=bar.rs は auxiliary/bar.rs をコンパイルし、テスト内で foo という名前で利用できるようにします。 これは Cargo が依存関係の名前変更を行う方法に似ています。 --extern 修飾子を 指定することもできます。 たとえば、//@ aux-crate:noprelude:foo=bar.rs です。

aux-bin は aux-build と似ていますが、ライブラリではなくバイナリをビルドします。 バイナリは、テストの作業ディレクトリを基準とした auxiliary/bin で利用できます。

aux-codegen-backend は aux-build と似ていますが、その後、メインファイルをビルドする際に コンパイル済みの dylib を -Zcodegen-backend に渡します。 これは、コンパイラクレートの使用を必要とするため、tests/ui-fulldeps 内のテストでのみ機能します。

補助 proc-macro

proc-macro 依存関係が必要な場合は、proc-macro ディレクティブを使用できます。このディレクティブは aux-build とまったく同じように動作します。つまり、 proc-macro テスト補助ファイルを、メインテストファイルと同じ親フォルダー配下の auxiliary フォルダーに置く必要があります。 ただし、proc-macro テスト補助については、aux-build と比較して さらに 4 つの追加の既定動作があります。

1. aux テストファイルは --crate-type=proc-macro でビルドされます。
2. aux テストファイルは -C prefer-dynamic なしでビルドされます。つまり、aux クレートの dylib を生成しようとはしません。
3. aux クレートは、--extern <aux_crate_name> により、extern prelude 経由で テストファイルから利用できるようになります。 UI テストはデフォルトで edition 2015 であるため、メインテストファイルが 2018 以降の edition を使用していない限り、 use インポートで aux クレート名を使用したい場合は、引き続き extern <aux_crate_name> を指定する必要があることに注意してください。
4. proc_macro クレートは extern prelude モジュールとして利用できるようになります。 extern proc_macro; についても、同じ edition 2015 とそれ以降の edition の区別が適用されます。

たとえば、テスト tests/ui/cat/meow.rs と proc-macro 補助 tests/ui/cat/auxiliary/whiskers.rs があるとします。

tests/ui/cat/
    meow.rs                 # メインテストファイル
    auxiliary/whiskers.rs   # 補助

// tests/ui/cat/meow.rs

//@ proc-macro: whiskers.rs

extern crate whiskers; // ui テストはデフォルトで edition 2015 のため必要

fn main() {
  whiskers::identity!();
}

// tests/ui/cat/auxiliary/whiskers.rs

extern crate proc_macro;
use proc_macro::*;

#[proc_macro]
pub fn identity(ts: TokenStream) -> TokenStream {
    ts
}

注記: 現在、proc-macro ヘッダーは rustdoc テストの build-aux-doc ヘッダーと併用できません。その場合は、 aux-build ヘッダーを使用し、proc-macro 内で #![crate_type="proc_macro"] と //@ force-host および //@ no-prefer-dynamic ヘッダーを使用する必要があります。

リビジョン

リビジョンを使用すると、1 つのテストファイルを複数のテストに使用できます。 これは、ファイルの先頭に特別なディレクティブを追加することで行います。

//@ revisions: foo bar baz

これにより、テストは 3 回コンパイル（およびテスト）されます。1 回は --cfg foo、1 回は --cfg bar、もう 1 回は --cfg baz です。 したがって、テスト内で #[cfg(foo)] などを使用して、これらの結果をそれぞれ調整できます。

ディレクティブと期待されるエラーメッセージを特定のリビジョンに合わせてカスタマイズすることもできます。 これを行うには、ディレクティブの場合は //@ の後に [revision-name] を追加し、 UI エラー注釈の場合は // の後に追加します。次のようになります。

// cfg `foo` の場合にのみ渡すフラグ:
//@[foo]compile-flags: -Z verbose-internals

#[cfg(foo)]
fn test_foo() {
    let x: usize = 32_u32; //[foo]~ ERROR mismatched types
}

//[foo,bar,baz]~^ のように、複数のリビジョンをカンマ区切りリストで指定できます。

LLVM FileCheck ツールを使用するテストスイートでは、現在のリビジョン名も FileCheck ディレクティブの追加プレフィックスとして登録されます。

//@ revisions: NORMAL COVERAGE
//@[COVERAGE] compile-flags: -Cinstrument-coverage
//@[COVERAGE] needs-profiler-runtime

// COVERAGE:   @__llvm_coverage_mapping
// NORMAL-NOT: @__llvm_coverage_mapping

// CHECK: main
fn main() {}

リビジョンに合わせてカスタマイズした場合に、すべてのディレクティブが意味を持つわけではないことに注意してください。 たとえば、ignore-test ディレクティブ（およびすべての「ignore」ディレクティブ）は現在、 特定のリビジョンではなく、テスト全体にのみ適用されます。 リビジョンに合わせてカスタマイズした場合に実際に機能することを意図しているディレクティブは、 エラーパターンとコンパイラフラグだけです。

これらのテストスイートはリビジョンをサポートしていないことに注意してください。

• codegen-units
• run-make
• rustdoc-html
• rustdoc-json

未使用のリビジョン名を無視する

通常、他のディレクティブやエラーアノテーションで言及されるリビジョン名は、revisions ディレクティブで宣言された実際のリビジョンに対応していなければなりません。 これは ./x test tidy チェックによって強制されます。

何らかの理由でリビジョン名をリビジョンリストから一時的に削除する必要がある場合は、代わりにそのリビジョン名を //@ unused-revision-names: ヘッダーに追加することで、上記のチェックを抑制できます。

未使用名として * を指定すると（つまり //@ unused-revision-names: *）、任意の未使用リビジョン名に言及できるようになります。

比較モード

Compiletest は、比較モード と呼ばれるさまざまなモードで実行できます。比較モードは、異なるコンパイラフラグを有効にした状態で、すべてのテストの動作を比較するために使用できます。 これにより、特定のフラグでどのような違いが現れる可能性があるかを明らかにし、発生し得る問題を確認できます。

別のモードでテストを実行するには、--compare-mode CLI フラグを渡す必要があります。

./x test tests/ui --compare-mode=next-solver

指定できる比較モードは次のとおりです。

• polonius — -Zpolonius=next を指定して Polonius で実行します。
• next-solver — -Znext-solver を指定して次世代 trait solver で実行します。
• next-solver-coherence — -Znext-solver=coherence を指定して次世代 trait solver で coherence を実行します。
• split-dwarf — -Csplit-debuginfo=unpacked を指定して、アンパックされた split-DWARF で実行します。
• split-dwarf-single — -Csplit-debuginfo=packed を指定して、パックされた split-DWARF で実行します。

UI テストが異なるモードに対して異なる出力をどのようにサポートしているかについて詳しくは、UI 比較モードを参照してください。

CI では、比較モードは 1 つの Linux ビルダーでのみ、かつ次の設定でのみ使用されます。

• tests/debuginfo: split-dwarf モードを使用します。 これは、split-DWARF を有効にしたときに debuginfo テストが影響を受けないことを確認するのに役立ちます。

比較モードはリビジョンとは別のものであることに注意してください。 ./x test tests/ui を実行するとすべてのリビジョンがテストされますが、比較モードは --compare-mode フラグを介して個別に手動で実行する必要があります。

並列フロントエンド

Compiletest は、--parallel-frontend-threads フラグを指定して、コンパイラを並列モードで実行できます。 これは、コンパイラが並列モードでも非並列モードと同じ出力を生成することを確認し、並列モードで発生し得る問題を確認するために使用できます。

並列モードでテストを実行するには、--parallel-frontend-threads CLI フラグを渡す必要があります。

./x test tests/ui -- --parallel-frontend-threads=N --iteration-count=M

ここで、N は並列フロントエンドで使用するスレッド数、M は各テストを並列モードで実行する回数です（非決定性を検出できる可能性を高めるため）。

また、--parallel-frontend-threads を指定して実行する場合、並列フロントエンドからの出力は行の順序という点で非決定的になり得るため、すべてのテストに対して compare-output-by-lines ディレクティブが暗黙的に指定されます。

並列フロントエンドは現時点では UI テストでのみ利用可能で、現在は他のテストスイートではサポートされていません。

UIテスト

UIテストは、compiletest の特定のテストスイートです。

はじめに

tests/ui 内のテストは、汎用テストの集合であり、 主にコンパイラのコンソール出力の検証に焦点を当てていますが、 他にも多くの目的に使用できます。 たとえば、テストは、その動作を検証するために 生成されたプログラムを実行するように設定することもできます。

tests/ui 配下の各サブディレクトリの目的の概要については、 README.mdを参照してください。 これは、新しいテストを書き、それを配置するカテゴリを探している場合に役立ちます。

#![no_std] のクロスコンパイルテストを扱う必要がある場合は、 minicore テスト補助の章を参照してください。

テストの一般的な構造

テストは、tests/ui ディレクトリに配置された Rust ソースファイルで構成されます。 テストは、その目的とテストカテゴリに基づいて適切なサブディレクトリに配置しなければなりません。 テストを tests/ui に直接配置することは許可されていません。

Compiletest は rustc を使用してテストをコンパイルし、その出力を、 テストの隣に配置された .stdout または .stderr ファイルに保存されている期待出力と比較します。 詳細については、出力の比較を参照してください。

さらに、エラーと警告はソースファイル内のコメントで注釈付けするべきです。 詳細については、エラー注釈を参照してください。

//@ で始まる特殊なコメント形式の compiletest ディレクティブは、 テストをどのようにコンパイルするか、および期待される動作が何かを制御します。

ほとんどのテストはコンパイラエラーをテストするため、テストはコンパイルに失敗することが期待されます。 その動作はディレクティブで変更できます。pass/fail 期待値の制御を参照してください。

デフォルトでは、テストは実行可能バイナリとしてビルドされます。 異なるクレートタイプが必要な場合は、必要に応じて #![crate_type] 属性を使用して設定できます。

出力の比較

UIテストは、コンパイラからの期待出力を、テストの隣にある .stderr および .stdout スナップショットに保存します。 通常、これらのファイルは --bless CLI オプションで生成し、その後手動で検査して、期待する内容が含まれていることを確認します。

不要な差異を無視するために出力は正規化されます。正規化セクションを参照してください。 ファイルが存在しない場合、compiletest は対応する出力が空であることを期待します。

正規化、リビジョン、および以下の他のツールの大半を使用する一般的な理由は、 プラットフォーム間の差異に対処することです。 これらのツールの代替案も検討してください。 たとえば、テストをクロスコンパイルを使用するように修正して、無効である可能性のあるすべての ABI をテストする代わりに、 すべてのプラットフォームで無効な extern "rust-invalid" ABI を使用するなどです。

stdout/stderr ファイルは複数存在できます。 一般的な形式は次のとおりです。

*test-name*`.`*revision*`.`*compare_mode*`.`*extension*

• test-name にドットを含めることはできません。 これは、テスト出力ファイル名の一般形式を予測可能な形式にして、 迷子のテスト出力ファイルを追跡するためにパターンマッチできるようにするためです。
• revision はリビジョン名です。 リビジョンを使用していない場合は含まれません。
• compare_mode は比較モードです。 これは、指定された比較モードが有効な場合にのみチェックされます。 ファイルが存在しない場合、 compiletest は比較モードなしのファイルをチェックします。
• extension はチェック対象の出力の種類です。
  • stderr — コンパイラの stderr
  • stdout — コンパイラの stdout
  • run.stderr — テスト実行時の stderr
  • run.stdout — テスト実行時の stdout
  • 64bit.stderr — 64ビットターゲットで stderr-per-bitwidth ディレクティブを使用したコンパイラの stderr
  • 32bit.stderr — 32ビットターゲットで stderr-per-bitwidth ディレクティブを使用したコンパイラの stderr

単純な例は、foo.rs テストの隣にある foo.stderr です。 より複雑な例は foo.my-revision.polonius.stderr です。

compiletest が出力ファイルをチェックする方法を変更するディレクティブがいくつかあります。

• stderr-per-bitwidth — ターゲットのポインタ幅に基づいて別々の出力ファイルをチェックします。 代わりに normalize-stderr ディレクティブを使用することを検討してください（正規化を参照）。
• dont-check-compiler-stderr — コンパイラからの stderr を無視します。
• dont-check-compiler-stdout — コンパイラからの stdout を無視します。
• compare-output-by-lines — 一部のテストでは出力の順序が非決定的であるため、行単位で比較する必要があります。

UIテストは -Zdeduplicate-diagnostics=no フラグ付きで実行されます。これは rustc の 組み込みの診断重複排除メカニズムを無効にします。 つまり、出力に重複したメッセージが表示される場合があります。 これは、重複した診断が生成されている状況を明らかにするのに役立ちます。

正規化

コンパイラ出力は、主にファイル名に関するプラットフォーム間の出力差異をなくすために正規化されます。

Compiletest はコンパイラ出力に対して次の置換を行います。

• テストが定義されているディレクトリは $DIR に置換されます。 例: /path/to/rust/tests/ui/error-codes
• 標準ライブラリソースへのディレクトリは $SRC_DIR に置換されます。 例: /path/to/rust/library
• $SRC_DIR 内のパスの行番号と列番号は LL:COL に置換されます。 これは、標準ライブラリのレイアウト変更が .stderr ファイルに広範な変更を 引き起こさないようにするのに役立ちます。 例: $SRC_DIR/alloc/src/sync.rs:53:46
• テストの出力が置かれるベースディレクトリは $TEST_BUILD_DIR に置換されます。 これは、ごくまれな状況でのみ現れます。 例: /path/to/rust/build/x86_64-unknown-linux-gnu/test/ui
• 標準ライブラリソースへの実ディレクトリは $SRC_DIR_REAL に置換されます。
• コンパイラソースへの実ディレクトリは $COMPILER_DIR_REAL に置換されます。
• タブは \t に置換されます。
• パス内のバックスラッシュ（\）は、（ヒューリスティックを使用して）スラッシュ（/）に変換されます。 これは Windows スタイルのパスとの差異を正規化するのに役立ちます。
• CRLF 改行は LF に変換されます。
• //~ ERROR some message のようなエラー行注釈は削除されます。
• さまざまな v0 およびレガシーのシンボルハッシュは、 [HASH] や <SYMBOL_HASH> のようなプレースホルダーに置換されます。

さらに、コンパイラは -Z ui-testing フラグ付きで実行されます。これにより、 コンパイラ自身が診断出力にいくつかの変更を適用し、UIテストにより適したものにします。

たとえば、出力内の行番号を匿名化します（各ソース行の先頭に付く行番号は LL に置換されます）。 極めてまれな状況では、このモードはディレクティブ //@ compile-flags: -Z ui-testing=no で無効化できます。

-Z ui-testing=no を使用する場合、UIテストスイートを実行しているターミナルの幅に応じて テストが失敗または成功しないように、--diagnostic-width 引数も設定するべきです。 注: テストを指す --> 行の行番号と列番号は正規化されず、 そのまま残されます。 これにより、コンパイラが引き続き正しい位置を指し示し、 stderr ファイルの可読性が保たれます。 理想的にはすべての行/列情報が保持されるべきですが、ソースへの小さな変更によって 大きな diff が発生し、マージコンフリクトやテストエラーがより頻繁に発生します。

場合によっては、これらの組み込みの正規化では不十分です。 そのような場合は、 normalize-* ディレクティブを使用してカスタム正規化ルールを指定できます。例:

//@ normalize-stdout: "foo" -> "bar"
//@ normalize-stderr: "foo" -> "bar"
//@ normalize-stderr-32bit: "fn\(\) \(32 bits\)" -> "fn\(\) \($$PTR bits\)"
//@ normalize-stderr-64bit: "fn\(\) \(64 bits\)" -> "fn\(\) \($$PTR bits\)"

これは、32 ビットプラットフォームでは、コンパイラが stderr に fn() (32 bits) を書き込むたびに、代わりに fn() ($PTR bits) と読めるよう正規化する必要があることをテストに伝えます。 64 ビットについても同様です。 置換は、regex クレートが提供するデフォルトの正規表現フレーバーを使用する正規表現によって実行されます。

対応する参照ファイルは、正規化された出力を使用して 32 ビットプラットフォームと 64 ビットプラットフォームの両方をテストします。

...
   |
   = note: source type: fn() ($PTR bits)
   = note: target type: u16 (16 bits)
...

具体的な使用例については、ui/transmute/main.rs と main.stderr を参照してください。

エラーアノテーション

エラーアノテーションは、コンパイラが出力すると期待されるエラーを指定します。 これらは、エラーが位置するソース内の行に「関連付け」られます。

fn main() {
    boom  //~ ERROR このスコープに値 `boom` が見つかりません [E0425]
}

UI テストにはコンパイラ出力全体を含む .stderr ファイルがありますが、 UI テストでは、エラーがソース内にもアノテーションされている必要があります。 この冗長性は、.stderr ファイルが通常 自動生成されるため、ミスを避けるのに役立ちます。 また、.stderr ファイルとソースを比較しなくても、1 つのファイルを見るだけで、 エラーのスパンがどこを指すと期待されるかを直接確認するのにも役立ちます。 最後に、追加の予期しないエラーが生成されないことを保証します。

これらにはいくつかの形式がありますが、一般的には診断レベル （ERROR など）と、期待されるエラー出力の部分文字列を含むコメントです。 メッセージ全体を書き出す必要はありませんが、 自己説明的になるよう、メッセージの重要な部分を必ず含めてください。

ほとんどのエラーアノテーションは、診断の行と一致する必要があります。 メッセージを行と一致させる方法はいくつかあります（以下の例を参照してください）。

• ~: エラーレベルとメッセージを現在の行に関連付けます
• ~^: エラーレベルとメッセージを直前のエラーアノテーション行に関連付けます。 追加するキャレット（^）ごとに 1 行ずつ加算されるため、~^^^ は エラーアノテーション行の 3 行上を意味します。
• ~|: エラーレベルとメッセージを、直前のコメントと 同じ行に関連付けます。これは、同じ行に関連付けられたメッセージが 複数ある場合に、複数のキャレットを使用するより便利です。
• ~v: エラーレベルとメッセージを次のエラーアノテーション行に関連付けます。 追加する記号（v）ごとに 1 行ずつ加算されるため、~vvv は エラーアノテーション行の 3 行下を意味します。

例:

let _ = same_line; //~ ERROR 未宣言の変数
fn meow(_: [u8]) {}
//~^ ERROR サイズ不定
//~| ERROR 無名パラメーター

//~（または他のバリアント）と後続のテキストの間の空白文字は 無視できます（つまり、//~ ERROR と //~ERROR の間に意味上の違いはありませんが、 コードベースでは前者の方が一般的です）。

~? <diagnostic kind>（例: ~? ERROR）は、 行情報がまったくない診断、または行情報がメインのテストファイル¹ の外側にある診断を一致させるために使用されます。 これらのアノテーションは、テストファイル内の任意の行に配置できます。

エラーアノテーションの例

以下は、UI テストソースの異なる行にあるエラーアノテーションの例です。

エラー行に配置

//~ ERROR イディオムを使用します。

fn main() {
    let x = (1, 2, 3);
    match x {
        (_a, _x @ ..) => {} //~ ERROR `_x @` はタプル内では許可されていません
        _ => {}
    }
}

エラー行の下に配置

上の行数を示すために、文字列内のキャレット数を指定して //~^ イディオムを使用します。 以下の例では、エラー行は エラーアノテーション行の 4 行上にあるため、アノテーションには 4 つのキャレットが含まれています。

fn main() {
    let x = (1, 2, 3);
    match x {
        (_a, _x @ ..) => {}  // <- エラーはこの行にあります
        _ => {}
    }
}
//~^^^^ ERROR `_x @` はタプル内では許可されていません

上のエラーアノテーション行で定義されたものと同じエラー行を使用

上のエラーアノテーション行と同じエラー行を定義するには、 //~| イディオムを使用します。

struct Binder(i32, i32, i32);

fn main() {
    let x = Binder(1, 2, 3);
    match x {
        Binder(_a, _x @ ..) => {}  // <- エラーはこの行にあります
        _ => {}
    }
}
//~^^^^ ERROR `_x @` はタプル構造体内では許可されていません
//~| ERROR このパターンには 1 個のフィールドがありますが、対応するタプル構造体には 3 個のフィールドがあります [E0023]

エラー行の上に配置

下の行数を示すために、文字列内の v の数を指定して //~v イディオムを使用します。 これは通常、ファイル末尾で発生する閉じられていない区切り文字や 閉じられていないリテラルのようなエラーに一致する lexer または parser テストで使用されます。

// ignore-tidy-trailing-newlines
//~v ERROR このファイルには閉じられていない区切り文字があります
fn main((ؼ

行情報のないエラー

行情報のないエラーに一致させるには、//~? を使用します。 //~? は精密であり、行情報が利用可能なエラーには一致しません。 コンパイラ診断に対して一致させたいテストでは、 //@ error-pattern は不正確で網羅的ではないため、これよりも //~? を優先すべきです。

//@ compile-flags: --print yyyy

//~? ERROR 不明な print 要求: `yyyy`

error-pattern

error-pattern ディレクティブ は、特定のスパンを持たない実行時メッセージや、 例外的な場合にはコンパイル時メッセージに使用できます。

このテストについて考えてみましょう。

fn main() {
    let a: *const [_] = &[1, 2, 3];
    unsafe {
        let _b = (*a)[3];
    }
}

これが「インデックスが範囲外」を表示することを保証したいものの、実行時エラーにはスパンがないため、 ERROR アノテーションを使用することはできません。 その場合は、error-pattern ディレクティブを使用します。

//@ error-pattern: インデックスが範囲外
fn main() {
    let a: *const [_] = &[1, 2, 3];
    unsafe {
        let _b = (*a)[3];
    }
}

コンパイル時出力を厳密にテストするには、スパンのない診断に対する //~? アノテーションを含め、 可能な限り行アノテーション //~ を使用するようにしてください。 コンパイル時の出力がターゲット依存である、または冗長すぎる場合は、ディレクティブ //@ dont-require-annotations: <diagnostic-kind> を使用して、行アノテーションのチェックを 網羅的でないものにします。 このモードでは、コンパイラーメッセージの一部がアノテーションでカバーされないままでもかまいません。

実行時出力をチェックする場合は、//@ check-run-results の方が望ましい場合があります。

error-pattern は、上記のいずれもうまくいかない場合にのみ使用してください。たとえば、実行時のパニック出力に含まれる 特定の文字列パターンを探す場合などです。

行アノテーション //~ と error-pattern は互換性があり、同じテスト内で使用できます。

診断の種類（エラーレベル）

使用できる診断の種類は次のとおりです。

• ERROR
• WARN（または WARNING）
• NOTE
• HELP
• SUGGESTION
• RAW

SUGGESTION 種類は、診断の提案に対して期待される置換テキストを指定するために使用されます。 RAW 種類は、構造化 JSON の代わりに、またはそれに加えて、コンパイラーによって出力されることがある非構造化出力の行にマッチさせるために使用できます。

ERROR と WARN 種類は、デフォルトで行アノテーション //~ によって網羅的にカバーされている必要があります。

他の種類は、その種類のアノテーションがテストファイル内に少なくとも 1 つ現れる場合にのみ、行アノテーションが必要です。 たとえば、//~ NOTE が 1 つあると、ファイル内の他のすべての //~ NOTE も 明示的に書き出す必要があります。

網羅的なアノテーションを無効にするには、ディレクティブ //@ dont-require-annotations を使用します。 たとえば、ノートを選択的にアノテーションするには //@ dont-require-annotations: NOTE を使用します。 ターゲット依存のコンパイラー出力のような重大な理由がない限り、このディレクティブを ERROR や WARN に使用するのは避けてください。

一部の診断は、その種類やディレクティブに関係なく、行アノテーションが必要になることはありません。 例としては、複数行診断の副次的な行や、 aborting due to N previous errors のような一般的な診断があります。

UI テストは、未使用警告をすべて無視するために、デフォルトで -A unused フラグを使用します。これは、 未使用警告が通常テストの焦点ではないためです。 ただし、単純なコードサンプルでは未使用警告が発生することがよくあります。 テストが特に 未使用警告をテストしている場合は、必要に応じて適切な #![warn(unused)] 属性を追加してください。

cfg リビジョン

リビジョンを使用する場合、現在のリビジョンに基づいて異なるメッセージを 条件付きでチェックできます。 これは、次のようにリビジョンの cfg 名を角括弧内に配置することで行います。

//@ edition:2018
//@ revisions: mir thir
//@[thir] compile-flags: -Z thir-unsafeck

async unsafe fn f() {}

async fn g() {
    f(); //~ ERROR unsafe 関数の呼び出しは unsafe です
}

fn main() {
    f(); //[mir]~ ERROR unsafe 関数の呼び出しは unsafe です
}

この例では、2 番目のエラーメッセージは mir リビジョンでのみ出力されます。 thir リビジョンでは最初のエラーのみが出力されます。

cfg によってコンパイラーが異なる出力を生成する場合、テストは異なる出力に対応する 複数の .stderr ファイルを持つことができます。 上記の例では、異なるリビジョンの異なる出力を含む .mir.stderr ファイルと .thir.stderr ファイルが存在することになります。

注: cfg リビジョンは、ソースコード内の #[cfg] 属性でも機能します。

慣例として、常に偽となる設定を持たせるために FALSE cfg が使用されます。

合格/不合格の期待値を制御する

デフォルトでは、UI テストは コンパイルエラーを生成する ことが期待されます。これは、ほとんどの テストが無効な入力とエラー診断をチェックしているためです。 ただし、コンパイルが成功することを期待する UI テストを作成することもでき、さらに結果のプログラムを 実行することもできます。 次のディレクティブのいずれかを追加してください。

• 合格ディレクティブ:
  • //@ check-pass — コンパイルは成功する必要がありますが、codegen はスキップします （これはコストが高く、ほとんどの場合失敗するはずがないためです）。
  • //@ build-pass — コンパイルとリンクは成功する必要がありますが、 結果のバイナリは実行しません。
  • //@ run-pass — コンパイルは成功する必要があり、結果の バイナリを実行すると、成功を示すコード 0 で終了する必要があります。
• 不合格ディレクティブ:
  • //@ check-fail — コンパイルは失敗する必要があります（codegen フェーズはスキップされます）。 これは UI テストのデフォルトです。
  • //@ build-fail — コンパイルは codegen フェーズ中に失敗する必要があります。 これにより rustc が 2 回実行されます。
    • 1 回目は、codegen フェーズなしでコンパイルが成功することを確認するためです
    • 2 回目は、完全なコンパイルが失敗することを確認するためです
  • //@ run-fail — コンパイルは成功する必要がありますが、結果の バイナリを実行すると、通常の失敗を示す範囲 1..=127 のコードで 終了する必要があります。 unwind サポートのないターゲットでは、クラッシュも受け入れられます。
  • //@ run-crash — コンパイルは成功する必要がありますが、結果の バイナリを実行するとクラッシュして失敗する必要があります。 クラッシュは「範囲 0..=127 のコードで終了しないこと」と定義されます。
    • Linux での例: SIGABRT または SIGSEGV による終了。
    • Windows での例: STATUS_ILLEGAL_INSTRUCTION（0xC000001D）のコードで終了。
  • //@ run-fail-or-crash — コンパイルは成功する必要がありますが、結果の バイナリを実行すると、run-fail または run-crash のいずれかになる必要があります。 一部のターゲットではテストがクラッシュするが、他のターゲットでは単に失敗する場合に便利です。

run-pass、run-fail、run-crash、および run-fail-or-crash テストでは、 プログラム自体の出力はデフォルトではチェックされません。

プログラムの実行出力をチェックしたい場合は、check-run-results ディレクティブを含めてください。 これにより、プログラムの実際の出力と比較するための .run.stderr および .run.stdout ファイルがチェックされます。

*-pass ディレクティブを持つテストは、--pass コマンドラインオプションで上書きできます。

./x test tests/ui --pass check

--pass オプションは UI テストにのみ影響します。 --pass check を使用すると、UI テストスイートをはるかに高速に実行できます（私のシステムではおよそ 2 倍高速です）が、当然ながら それほど多くの部分は実行されません。

その上書きではテストが正しく動作しない場合、--pass CLI フラグを無視するために no-pass-override ディレクティブを使用できます。

既知のバグ

known-bug ディレクティブは、まだ修正されていない既知のバグを示すテストに使用できます。 既知のバグに対するテストを追加することは、次のような複数の理由で有用です。

1. バグが修正されたときに便利に再利用できる機能テストを維持する。
2. バグが偶然修正された場合に失敗する番兵を提供する。 これにより開発者に通知され、関連する issue が修正されたことを把握でき、 場合によってはクローズできます。

このディレクティブは、カンマ区切りの issue 番号を引数として取るか、"unknown" を取ります。

• //@ known-bug: #123, #456（issue が rust-lang/rust 上にある場合）
• //@ known-bug: rust-lang/chalk#123456 （# の前に任意のテキストを許可します。これは issue が別のリポジトリにある場合に便利です）
• //@ known-bug: unknown （既知の issue がまだない場合。存在しない場合は、開くことが望ましいです）

known-bug を含むテストには、エラーアノテーションを含めないでください。 テストには、他の通常のディレクティブと stdout/stderr ファイルは引き続き含める必要があります。

テストの編成

テストファイルを配置する場所を決めるときは、実行しようとしている内容に 最も一致するサブディレクトリを探すようにしてください。 できるだけ整理された状態を保つよう努めてください。 確かに、一部のテストは複数のカテゴリにまたがる場合があり、 既存のレイアウトがうまく合わないこともあるため、難しい場合があります。

テストには、そのテストが何をチェックしているかを簡潔に説明する名前を付けてください。 テスト名に issue 番号を含めることは避けてください。 これについてより詳しい説明は、ベストプラクティスを参照してください。

理想的には、そのテストでどのコードがテストされているかを識別しやすくする ディレクトリにテストを追加するべきです（例: tests/ui/borrowck/reject-move-out-of-borrow-via-pat.rs）

新しい機能を書くときは、テストを保存するサブディレクトリを作成することを検討してもよいでしょう。 たとえば、RFC 1234（“Widgets”）を実装している場合は、 tests/ui/rfc1234-widgets/ のようなディレクトリにテストを配置するのが理にかなっているかもしれません。

別の場合には、すでに適切なディレクトリが存在していることもあります。

時間の経過とともに、tests/ui ディレクトリは非常に速く成長してきました。 tidy には、どのサブディレクトリも 1000 個を超えるエントリを持たないことを 保証するチェックがあります。 ファイルが多すぎると、エディタ/IDE に優しくなく、 GitHub UI も 1000 個を超えるエントリを表示しないため、問題が発生します。 ただし、tests/ui（UI テストのルートディレクトリ）と tests/ui/issues ディレクトリには 1000 個を超えるエントリがあるため、これらのディレクトリには別の上限を設定しています。 そのため、そこに新しいテストを置くことは避け、より関連性の高い場所を探すようにしてください。

たとえば、テストがクロージャに関連している場合は、tests/ui/closures に配置するべきです。 上限に達した場合は、ここを調整することで上限を増やすことができます。

Rustfix テスト

UI テストでは、診断の提案が正しく適用されること、および 結果の変更が正しくコンパイルされることを検証できます。 これは run-rustfix ディレクティブで行えます。

//@ run-rustfix
//@ check-pass
#![crate_type = "lib"]

pub struct not_camel_case {}
//~^ WARN `not_camel_case` はアッパーキャメルケースの名前にするべきです
//~| HELP 識別子をアッパーキャメルケースに変換してください
//~| SUGGESTION NotCamelCase

Rustfix テストには、提案が適用された後のソースファイルを含む .fixed 拡張子のファイルが必要です。

• テストが実行されると、compiletest はまず正しい lint/警告が生成されることをチェックします。
• 次に、提案を適用して .fixed と比較します（一致している必要があります）。
• 最後に、修正済みソースがコンパイルされ、このコンパイルは成功する必要があります。

通常、rustfix テストを作成するときは、x test --bless オプションで .fixed ファイルを自動生成します。

run-rustfix ディレクティブは、たとえそれらが MachineApplicable でなくても、すべての提案を適用します。 これが問題になる場合は、run-rustfix に加えて rustfix-only-machine-applicable ディレクティブを追加できます。 これは、異なる提案レベルが混在しており、 機械的に適用可能ではないものの一部がきれいに適用されない場合に使用するべきです。

比較モード

比較モードは、通常コンパイルされるときとは 異なるフラグで全テストを実行するために使用できます。 場合によっては、これによりコンパイラから異なる出力が生成されることがあります。 これをサポートするために、比較モードに基づく出力を含む 異なる出力ファイルを保存できます。

たとえば、Polonius モードを使用している場合、テスト foo.rs はまず 期待される出力を foo.polonius.stderr で探し、見つからない場合は通常の foo.stderr にフォールバックします。 これは、異なるモードによって異なる診断や動作が生じることがあるため便利です。 これにより、モード間で差分があるテストを追跡し、 それらの診断の違いを視覚的に確認しやすくなります。

まれに、動作が異なるテストに遭遇した場合は、 代替の stderr ファイルを生成するために、次のようなものを実行できます。

./x test tests/ui --compare-mode=polonius --bless

現在、UI テストについては CI でチェックされている比較モードはありません。

rustc_* TEST 属性

コンパイラは、内部機能 rustc_attrs によってゲートされる、 追加のコンパイラ内部情報をダンプする perma-unstable な #[rustc_*] 属性をいくつか定義しています。 詳細については、コンパイラのデバッグの対応するサブセクションを参照してください。

これらは、通常なら「ユーザー向け」の Rust だけで同じことを行うのが非常に難しい場合に、 内部コンパイラ状態をより正確に、読みやすく、簡単にテストするために使用できます。 実際、これは「UI」（ユーザーインターフェイス）という用語をわずかに悪用し、 そのような UI テストをブラックボックステストからホワイトボックステストに変えるものだと言えるでしょう。 慎重かつ控えめに使用してください。

UI テストモードでプリセットされる lint レベル

デフォルトでは、UI テストモード配下のテストスイート（tests/ui、tests/ui-fulldeps、 ただし tests/rustdoc-ui は除く）は、次を指定します。

• -A unused
• -W unused_attributes（これらは ui テストにとって関心の対象になりやすいため）
• -A internal_features
• -A incomplete_features
• -A unused_parens
• -A unused_braces

詳細については、runtestを参照してください。

条件は次のとおりです。

• ui テストの pass モードが run 未満である（つまり check または build）。
• 比較モードが指定されていない。

これは、ui テストでは非常にノイズが多くなる可能性があるためです。

必要に応じて、compile-flags の lint レベルフラグや ソース内の lint レベル属性でこれらを上書きできます。

なお、rustfix バージョンには -A unused が渡されないため、 rustfix 済みファイルで unused lint を抑制するには、#[allow(unused)] が必要になる場合があります （unused lint 自体に対して rustfix をテストしている可能性があるためです）。

1. これは、aux ファイルや、こちらで制御できないソースとは異なる、~? アノテーションを持つファイルです。 ↩

Compiletest ディレクティブ

ディレクティブは、テストをどのようにビルドし解釈するかを compiletest に伝える特別なコメントです。 rmake.rs の run-make テストにも現れることがあります。

通常、ディレクティブはこのテストの要点を説明する短いコメントの後に置かれます。 Compiletest のテストスイートでは、コメントがディレクティブであることを示すために //@ を使用します。 たとえば、このテストでは、テストのコンパイル時に rustc に渡すカスタムフラグを指定するために、//@ compile-flags コマンドを使用しています。

// オーバーフローチェックが無効な場合の `0 - 1` の挙動をテストする。

//@ compile-flags: -C overflow-checks=off

fn main() {
    let x = 0 - 1;
    ...
}

ディレクティブは単独で記述することも（例: //@ run-pass）、値を取ることもできます（例: //@ compile-flags: -C overflow-checks=off）。

ディレクティブは 1 行につき 1 つ記述します。同じ行に複数のディレクティブを書くことはできません。 たとえば、//@ only-x86 only-windows と書いた場合、 only-windows は別個のディレクティブではなく、コメントとして解釈されます。

compiletest ディレクティブの一覧

以下は compiletest ディレクティブの一覧です。 利用可能な場合、ディレクティブはそのコマンドをより詳しく説明するセクションにリンクされています。 この一覧は網羅的ではない可能性があります。 ディレクティブは一般に、compiletest ソースの directives.rs にある TestProps 構造体を参照することで見つけられます。

アセンブリ

補助ビルド

補助クレートのビルドを参照してください

結果の期待値の制御

pass/fail 期待値の制御を参照してください。

出力スナップショットと正規化の制御

詳細については、正規化、出力 比較、および Rustfix テストを参照してください。

テストを実行するタイミングの制御

これらのディレクティブは、状況によってテストを無視するために使用されます。これは、 そのテストがコンパイルも実行もされないことを意味します。

• ignore-X は、X がテストを無視する対象の詳細またはその他の条件である場合に使用します（以下を参照）
• only-X は ignore-X に似ていますが、そのターゲットまたはステージでのみテストを実行します
• ignore-auxiliary は、1つ以上の他のメインテストファイルに関与するものの、 compiletest がそのファイル自体をビルドしようとするべきではないファイルを対象としています。 その補助ファイルを実際に使用しているメインテストへのバックリンクを付けてください。
• ignore-test は常にテストを無視します。 これは、現在動作していないテストを一時的に無効化しつつ、 後で再有効化するためにツリー内に保持したい場合に使用できます。

ignore-X または only-X における X の例をいくつか示します。

• 完全なターゲットトリプル: aarch64-apple-ios
• アーキテクチャ: aarch64, arm, csky, mips, mips64, wasm32, x86_64, x86, …
• OS: android, emscripten, freebsd, ios, linux, macos, windows, …
• 環境（ターゲットトリプルの4番目の単語）: gnu, msvc, musl
• ポインター幅: 32bit, 64bit
• エンディアン: endian-big
• ステージ: stage1, stage2
• バイナリ形式: elf
• チャネル: stable, beta
• クロスコンパイル時: cross-compile
• [remote testing] が使用される場合: remote
• 特定のデバッガーがテストされる場合: cdb, gdb, lldb
• 特定のデバッガーバージョンに一致する場合: ignore-gdb-version
• [parallel frontend] が有効な場合: ignore-parallel-frontend
• 特定の [compare modes]: compare-mode-polonius, compare-mode-next-solver, compare-mode-next-solver-coherence, compare-mode-split-dwarf, compare-mode-split-dwarf-single
• カバレッジテストで使用される2つの異なるテストモード: ignore-coverage-map, ignore-coverage-run
• dist ツールチェーンをテストする場合: dist
  • これは COMPILETEST_ENABLE_DIST_TESTS=1 で有効にする必要があります
• ターゲットの rustc_abi: 例: rustc_abi-x86_64-sse2

以下のディレクティブは rustc のビルド設定とターゲット設定をチェックします。

• needs-asm-support — ホストアーキテクチャが asm! の安定サポートを持たない場合に無視します。 明示的なターゲットへクロスコンパイルするテストでは、 --target を介して、 適切なバックエンドが利用可能であることを保証するために、代わりに needs-llvm-components を使用してください。
• needs-asm-mnemonic: <MNEMONIC> — ターゲットバックエンドが指定されたアセンブリニーモニック（例: RET, NOP）を サポートしていない場合に無視します。 LLVM バックエンドでのみサポートされます。
• needs-profiler-runtime — プロファイラーランタイムがターゲットに対して有効化されていない場合に テストを無視します（bootstrap.toml の build.profiler = true）
• needs-sanitizer-support — サニタイザーサポートがターゲットに対して有効化されていない場合に 無視します（bootstrap.toml の build.sanitizers = true）
• needs-sanitizer-{address,hwaddress,leak,memory,thread} — 対応するサニタイザーが ターゲットに対して有効化されていない場合に無視します（それぞれ AddressSanitizer、 ハードウェア支援 AddressSanitizer、LeakSanitizer、MemorySanitizer または ThreadSanitizer）
• needs-run-enabled — 実行されるテストであり、実行が無効化されている場合に無視します。 テストの実行は、x test --run=never フラグ、または fuchsia 上で実行することによって無効化できます。
• needs-unwind — ターゲットがアンワインドをサポートしていない場合に無視します
• needs-rust-lld — rust lld サポートが有効化されていない場合に無視します（bootstrap.toml の rust.lld = true）
• needs-threads — ターゲットがスレッドサポートを持たない場合に無視します
• needs-subprocess — ターゲットがサブプロセスサポートを持たない場合に無視します
• needs-symlink — ターゲットがシンボリックリンクをサポートしていない場合に無視します。 開発者が特権付きシンボリックリンク権限を有効にしていない場合、Windows ではこれに該当することがあります。
• ignore-std-debug-assertions — std がデバッグアサーション付きでビルドされている場合に無視します。
• needs-std-debug-assertions — std がデバッグアサーション付きでビルドされていない場合に無視します。
• ignore-std-remap-debuginfo — std がそのソースの再マッピング付きでビルドされている場合に無視します。
• needs-std-remap-debugino — std がそのソースの再マッピング付きでビルドされていない場合に無視します。
• ignore-rustc-debug-assertions — rustc がデバッグアサーション付きでビルドされている場合に無視します。
• needs-rustc-debug-assertions — rustc がデバッグアサーション付きでビルドされていない場合に無視します。
• needs-target-has-atomic — ターゲットが指定されたすべての アトミック幅のサポートを持たない場合に無視します。たとえば、//@ needs-target-has-atomic: 8, 16, ptr を持つテストは、カンマ区切りリストのアトミック幅をサポートしている場合にのみ実行されます。
• needs-dynamic-linking — ターゲットが動的リンクをサポートしていない場合に無視します （これは、dylib および cdylib クレートタイプを作成できないこととは直交します）
• needs-crate-type — ターゲットプラットフォームが、指定されたクレートタイプの カンマ区切りリストのうち1つ以上をサポートしていない場合に無視します。 たとえば、 //@ needs-crate-type: cdylib, proc-macro は、 wasm32-unknown-unknown ターゲットではターゲットが proc-macro クレートタイプをサポートしていないため、テストが無視される原因になります。
• needs-target-std — ターゲットプラットフォームが std サポートを持たない場合に無視します。
  • codegen テストにおける #![no_std]/#![no_core] と暗黙の needs-target-std も 参照してください。
• ignore-backends — 空白文字で区切られた、列挙されたバックエンドを無視します。 このディレクティブは --bypass-ignore-backends=[BACKEND] コマンドライン フラグで上書きできることに注意してください。
• needs-backends — 現在の codegen バックエンドが列挙されている場合にのみテストを実行します。
• needs-offload — LLVM バックエンドがオフロードサポート付きでビルドされていない場合に無視します。
• needs-enzyme — Enzyme サブモジュールがビルドされていない場合に無視します。

以下のディレクティブは LLVM サポートをチェックします。

• exact-llvm-major-version: 19 — llvm メジャーバージョンが指定された llvm メジャーバージョンと 一致しない場合に無視します。
• min-llvm-version: 13.0 — LLVM バージョンが指定された値より小さい場合に無視されます
• min-system-llvm-version: 12.0 — システム LLVM を使用していて、その バージョンが指定された値より小さい場合に無視されます
• max-llvm-major-version: 19 — LLVM メジャーバージョンが指定されたメジャーバージョンより高い場合に 無視されます
• ignore-llvm-version: 9.0 — 特定の LLVM バージョンを無視します
• ignore-llvm-version: 7.0 - 9.9.9 — 範囲内の LLVM バージョンを無視します（両端を含む）
• needs-llvm-components: powerpc — 特定の LLVM コンポーネントがビルドされていない場合に無視します。 注: コンポーネントが存在しない場合、CI では（COMPILETEST_REQUIRE_ALL_LLVM_COMPONENTS が設定されていると） テストは失敗します。
• needs-forced-clang-based-tests — 環境変数 RUSTBUILD_FORCE_CLANG_BASED_TESTS が設定されていない限りテストは無視されます。これにより LLVM と並行して clang をビルドできるようになります
  • これは2つの CI ジョブ（[x86_64-gnu-debug] と [aarch64-gnu-debug]）でのみ設定されており、run-make テストのサブセットのみを実行します。 このディレクティブを持つ他のテストはまったく実行されませんが、これは通常望ましいことではありません。

デバッガーを無視するためのディレクティブについては、デバッグ情報テスト も参照してください。 [remote testing]: running.md#running-tests-on-a-remote-machine [parallel frontend]: compiletest.md#parallel-frontend [compare modes]: ui.md#compare-modes [x86_64-gnu-debug]: https://github.com/rust-lang/rust/blob/ab3dba92db355b8d97db915a2dca161a117e959c/src/ci/docker/host-x86_64/x86_64-gnu-debug/Dockerfile#L32 [aarch64-gnu-debug]: https://github.com/rust-lang/rust/blob/20c909ff9cdd88d33768a4ddb8952927a675b0ad/src/ci/docker/host-aarch64/aarch64-gnu-debug/Dockerfile#L32

テストのビルド方法に影響するもの

edition ディレクティブ

//@ edition ディレクティブには、厳密なエディション、エディションの有界範囲、 またはエディションの左有界な半開範囲を指定できます。 これは、./x test がテストを実行するために使用するエディションに影響します。

例:

• //@ edition: 2018 ディレクティブを持つテストは、2018 エディションでのみ実行されます。
• //@ edition: 2015..2021 ディレクティブを持つテストは、2015 エディションと 2018 エディションで実行できます。 したがって、上限は Rust の場合と同様に排他的です （上限を包含する Rust の ..= に相当するものはないことに注意してください）。 ただし、CI は範囲内の最も低いエディション（この例では 2015）でのみテストを実行します。
• //@ edition: 2018.. ディレクティブを持つテストは、2018 エディション以上で実行されます。 ただし、CI は範囲内の最も低いエディション（この例では 2018）でのみテストを実行します。

-- --edition= 引数を渡すことで、./x test に特定のエディションを強制的に使用させることもできます。 ただし、//@ edition ディレクティブを持つテストは、引数に渡された値をクランプします。 たとえば、./x test -- --edition=2015 を実行した場合:

• //@ edition: 2018 を持つテストは、2018 エディションで実行されます。
• //@ edition: 2015..2021 を持つテストは、2015 エディションで実行されます。
• //@ edition: 2018.. を持つテストは、2018 エディションで実行されます。

Rustdoc

テストスイート固有のディレクティブ

テストスイート rustdoc-html、rustdoc-js/rustdoc-js-std、 および rustdoc-json には、それぞれ追加のディレクティブ群があります。その基本的な 構文は compiletest ディレクティブのものに似ていますが、最終的には別個のツールによって読み取られ、チェックされます。 詳細については、上にリンクされているそれぞれの章を参照してください。

プリティプリント

Pretty-printer を参照してください。

その他のディレクティブ

• no-auto-check-cfg — 自動 check-cfg を無効化する（--check-cfg テスト専用）
• revisions — 複数回コンパイルする
• forbid-output — 出力に指定された文字列が含まれていないことをチェックする
• reference — reference 内のルールにリンクする注釈
• disable-gdb-pretty-printers — debuginfo テスト用の gdb pretty printer を無効化する

ツール固有のディレクティブ

以下のディレクティブは、それらのツールを使用するテストスイートにおいて、 特定のコマンドラインツールがどのように呼び出されるかに影響します。

• skip-filecheck は、通常であれば出力をチェックするために LLVM の FileCheck ツールを実行するテストで、その実行を回避します。
  • codegen テスト、assembly テスト、および mir-opt テストで使用されます。
• filecheck-flags は、LLVM の FileCheck ツールの実行時に追加のフラグを追加します。
  • codegen テスト、 assembly テスト、および MIR-opt テストで使用されます。
• llvm-cov-flags は、LLVM の llvm-cov ツールの実行時に追加のフラグを追加します。
  • coverage-run モードの coverage テストで使用されます。

Tidy 固有のディレクティブ

以下のディレクティブは、tidy スクリプトがテストを検証する方法を制御します。

• ignore-tidy-target-specific-tests は、テストが（compile-flag ディレクティブ内の --target フラグによって） 特定のターゲット向けにコンパイルされる場合に、適切な LLVM コンポーネントが（needs-llvm-components ディレクティブによって） 必要とされていることのチェックを無効にします。
• unused-revision-names - 未知のリビジョン名への言及に対する tidy チェックを抑制します。

置換

ディレクティブの値では、対応する値に置き換えられるいくつかの変数を 置換として使用できます。 たとえば、特定のファイルへのパスを含むコンパイラフラグを渡す必要がある場合は、 次のようなものが使用できます。

//@ compile-flags: --remap-path-prefix={{src-base}}=/the/src

ここで、センチネル {{src-base}} は、以下で説明する適切なパスに置き換えられます。

• {{cwd}}: compiletest が実行されるディレクトリ。 これはチェックアウトのルートではない場合があるため、可能な限り使用を避けるべきです。
  • 例: /path/to/rust, /path/to/build/root
• {{src-base}}: テストが定義されているディレクトリ。 これは output normalization における $DIR と同等です。
  • 例: /path/to/rust/tests/ui/error-codes
• {{build-base}}: テストの出力先となるベースディレクトリ。 これは output normalization における $TEST_BUILD_DIR と同等です。
  • 例: /path/to/rust/build/x86_64-unknown-linux-gnu/test/ui
• {{rust-src-base}}: libstd/libcore/… が置かれている sysroot ディレクトリ
• {{sysroot-base}}: テストのビルドに使用される sysroot ディレクトリのパス。
  • 主に、API 経由でコンパイラを実行する ui-fulldeps テストを想定しています。
• {{target-linker}}: このテストで -Clinker に渡されるリンカー。 リンカーのオーバーライドが有効でない場合は空です。
  • 主に、API 経由でコンパイラを実行する ui-fulldeps テストを想定しています。
• {{target}}: テストのコンパイル対象となるターゲット
  • 例: x86_64-unknown-linux-gnu

この置換を使用するテストの例については、 tests/ui/argfile/commandline-argfile.rs を参照してください。

ディレクティブの追加

個々のテストごとに何らかのテストプロパティや振る舞いを定義する必要がある場合、 新しいディレクティブを追加します。 ディレクティブプロパティは、実行時にディレクティブのバッキングストア （コマンドの現在の値を保持するもの）として機能します。

新しいディレクティブプロパティを追加するには、次のようにします。

1. src/tools/compiletest/src/directives.rs で pub struct TestProps 宣言を探し、 新しい public プロパティをその宣言の末尾に追加します。
2. 構造体宣言の直後にある impl TestProps 実装ブロックを探し、 新しいプロパティをデフォルト値で初期化します。

新しいディレクティブパーサーの追加

compiletest がテストファイルに遭遇すると、これも src/tools/compiletest/src/directives.rs にある Config 構造体の実装ブロックで 定義されているすべてのパーサーを呼び出すことで、ファイルを 1 行ずつ解析します （Config 構造体の宣言ブロックは src/tools/compiletest/src/common.rs にあることに注意してください）。 TestProps の load_from() メソッドは、現在のテキスト行を 各パーサーに渡そうとします。各パーサーは通常、その行が //@ must-compile-successfully や //@ failure-status のような 特定のコメント付き（//@）ディレクティブで始まるかどうかをチェックします。 コメントマーカーの後の空白は任意です。

パーサーは、ディレクティブに応じて、テストファイル内でディレクティブとして 指定されているだけで、またはテストファイル内でパラメータ値が指定されていることで、 指定されたディレクティブプロパティのデフォルト値を上書きします。

impl Config で定義されるパーサーは通常、parse_<directive-name> という名前です （kebab-case の <directive-command> が snake-case の <directive_command> に変換されることに注意してください）。 impl Config は、単純な有無（parse_name_directive()）や directive:parameter(s)（parse_name_value_directive()）、 特定の cfg 属性が定義されている場合にのみ任意で解析するもの（has_cfg_prefix()）など、 一般的なパターンを簡単に解析できるいくつかの「低レベル」パーサーも定義しています。 低レベルパーサーは impl Config ブロックの末尾付近にあります。不要な追加の解析コードを書かないように、 それらと、そのすぐ上にある関連パーサーに目を通して、どのように使用されているかを必ず確認してください。

具体例として、src/tools/compiletest/src/directives.rs にある parse_failure_status() パーサーの実装を次に示します。

@@ -232,6 +232,7 @@ pub struct TestProps {
     // カスタマイズされた正規化ルール
     pub normalize_stdout: Vec<(String, String)>,
     pub normalize_stderr: Vec<(String, String)>,
+    pub failure_status: i32,
 }

 impl TestProps {
@@ -260,6 +261,7 @@ impl TestProps {
             run_pass: false,
             normalize_stdout: vec![],
             normalize_stderr: vec![],
+            failure_status: 101,
         }
     }

@@ -383,6 +385,10 @@ impl TestProps {
             if let Some(rule) = config.parse_custom_normalization(ln, "normalize-stderr") {
                 self.normalize_stderr.push(rule);
             }
+
+            if let Some(code) = config.parse_failure_status(ln) {
+                self.failure_status = code;
+            }
         });

         for key in &["RUST_TEST_NOCAPTURE", "RUST_TEST_THREADS"] {
@@ -488,6 +494,13 @@ impl Config {
         self.parse_name_directive(line, "pretty-compare-only")
     }

+    fn parse_failure_status(&self, line: &str) -> Option<i32> {
+        match self.parse_name_value_directive(line, "failure-status") {
+            Some(code) => code.trim().parse::<i32>().ok(),
+            _ => None,
+        }
+    }

振る舞いの変更の実装

テストが特定のディレクティブを呼び出すと、その結果として何らかの振る舞いが 変更されることが期待されます。 どのような振る舞いかは、当然ながらディレクティブの目的によって異なります。 failure-status の場合、変更される振る舞いは、 compiletest がデフォルト値ではなく、テスト内で呼び出されたディレクティブによって 定義された失敗コードを期待するようになることです。

これは failure-status に固有のものですが（振る舞いの変更を呼び出すための実装は ディレクティブごとに異なるため）、単なる例として、1 つのケースにおける 振る舞いの変更の実装を見ると役に立つかもしれません。 failure-status を実装するために、src/tools/compiletest/src/runtest.rs にある TestCx 実装ブロック内の check_correct_failure_status() 関数は、以下のように変更されました。

@@ -295,11 +295,14 @@ impl<'test> TestCx<'test> {
     }

     fn check_correct_failure_status(&self, proc_res: &ProcRes) {
-        // Rustランタイムが失敗時に返す値
-        const RUST_ERR: i32 = 101;
-        if proc_res.status.code() != Some(RUST_ERR) {
+        let expected_status = Some(self.props.failure_status);
+        let received_status = proc_res.status.code();
+
+        if expected_status != received_status {
             self.fatal_proc_rec(
-                &format!("failure produced the wrong error: {}", proc_res.status),
+                &format!("エラー: 期待される失敗ステータス ({:?}) に対して、受け取ったステータスは {:?} でした。",
+                         expected_status,
+                         received_status),
                 proc_res,
             );
         }
@@ -320,7 +323,6 @@ impl<'test> TestCx<'test> {
         );

         let proc_res = self.exec_compiled_test();
-
         if !proc_res.status.success() {
-            self.fatal_proc_rec("test run failed!", &proc_res);
+            self.fatal_proc_rec("テストの実行に失敗しました！", &proc_res);
         }
@@ -499,7 +501,6 @@ impl<'test> TestCx<'test> {
                 expected,
                 actual
             );
-            panic!();
         }
     }

ディレクティブプロパティにアクセスするために self.props.failure_status を使用していることに注目してください。 failure status ディレクティブを指定していないテストでは、 本稿執筆時点で self.props.failure_status はデフォルト値の 101 に評価されます。 しかし、たとえば //@ failure-status: 1 のようなディレクティブを 指定したテストでは、そのテストに限って、parse_failure_status() が TestProps の デフォルト値を上書きするため、self.props.failure_status は 1 に評価されます。

1. 詳細については、compiletest の章の 補助 proc-macro セクションを参照してください。 ↩

2. 現在 これには奇妙な癖があり、 テストバイナリの stdout と stderr が連結されてから、 error-pattern がこの結合された出力に対してマッチされる。これは ??? 控えめに言っても、少し疑問がある。 ↩

minicore テスト補助: core スタブの使用

tests/auxiliary/minicore.rs は、ui/codegen/assembly/mir-opt テストスイート用のテスト補助です。 これは、クロスコンパイルされたターゲット向けにビルドする必要があるものの、 実行する必要がない、または実行したくないテストのために core スタブを提供します。

テストでは、//@ add-minicore ディレクティブを指定することで minicore を使用できます。 次に、そのテストに #![feature(no_core)] + #![no_std] + #![no_core] を付け、 extern crate minicore（edition 2015） または use minicore（edition 2018+）でそのクレートをテストにインポートします。

暗黙的に指定されるコンパイラフラグ

これらのテストは no_std + no_core であるため、//@ add-minicore は そのテストが -C panic=abort でビルドされることを暗黙的に指定し、かつ必須とします。 アンワインドするパニックはサポートされていません。

アセンブリテストで CFI ディレクティブを保持するため、テストは -C force-unwind-tables=yes でもビルドされます。

TL;DR: //@ add-minicore は 2 つのコンパイラフラグを暗黙的に指定します。

1. -C panic=abort
2. -C force-unwind-tables=yes

core スタブをさらに追加する

minicore スタブに core 項目が不足していることに気付いた場合、 それが使用される可能性が高い、または既に複数のテストで必要とされているなら、 テスト補助に追加することを検討してください。

core との同期を保つ

minicore の項目は core に追随して最新の状態に保つ必要があります。 core と minicore の使用時で診断出力の一貫性を保つため、あらゆる diagnostic 属性（例: on_unimplemented）は minicore に正確に複製するべきです。

minicore を使用する codegen テストの例

#![allow(unused)]
fn main() {
//@ add-minicore
//@ revisions: meow bark
//@[meow] compile-flags: --target=x86_64-unknown-linux-gnu
//@[meow] needs-llvm-components: x86
//@[bark] compile-flags: --target=wasm32-unknown-unknown
//@[bark] needs-llvm-components: webassembly

#![crate_type = "lib"]
#![feature(no_core)]
#![no_std]
#![no_core]

extern crate minicore;
use minicore::*;

struct Meow;
impl Copy for Meow {} // ここでの `Copy` は `minicore` によって提供されます

// CHECK-LABEL: meow
#[unsafe(no_mangle)]
fn meow() {}
}

エコシステムテスト

Rust は、リグレッションを検出し、言語の進化について十分な情報に基づいた意思決定を行えるように、エコシステム内の実世界のコードとの統合をテストします。

テスト方法

Crater

Crater は、何千もの公開プロジェクトでテストを実行するツールです。このツールには実行用の独立したインフラストラクチャがあり、CI の一部としては実行されません。詳細については、Crater の章を参照してください。

cargotest

cargotest は、いくつかのサンプルプロジェクト（servo、ripgrep、tokei など）で cargo test を実行する小さなツールです。これは CI の一部として実行され、重大なリグレッションがないことを確認します。

./x test src/tools/cargotest

大規模 OSS プロジェクトビルダー

CI には、CI のリグレッションテストとして使用される大規模なオープンソース Rust プロジェクトをビルドするジョブがあります。統合ジョブは次のプロジェクトをビルドします。

• Fuchsia
• Rust for Linux

Crater

Crater は、crates.io 上の すべての crate（および GitHub 上の一部）をコンパイルし、 テストを実行するためのツールです。 主に、互換性を破壊する可能性のある変更を実装する際に、破壊的影響の範囲を確認したり、 beta と stable のコンパイラバージョンを比較して破壊的影響がないことを確認したりするために使用されます。

Crater を実行するタイミング

PR がコンパイラに大きな変更を加える場合、または破壊的影響を引き起こす可能性がある場合は、 Crater の実行をリクエストする必要があります。 判断に迷う場合は、PR のレビュアーに遠慮なく尋ねてください。

Crater 実行のリクエスト

Rust チームは、PR によって導入された変更に対して Crater を実行するために使用できるマシンをいくつか保守しています。 PR に Crater の実行が必要な場合は、PR スレッドでトリアージチーム宛てにコメントを残してください。 “check-only” Crater 実行、“build only” Crater 実行、または “build-and-test” Crater 実行のどれが必要かをチームに知らせてください。 違いは主に所要時間です。 よくわからない場合は、build-and-test 実行を選択してください。 コンパイル時にのみ影響する変更を行う場合 （例: 新しいトレイトを実装する場合）は、check 実行だけで十分です。

PR はトリアージチームによってキューに追加され、結果が準備でき次第投稿されます。 check 実行にはおよそ 3〜4 日かかり、他の 2 つは平均して 5〜6 日かかります。

Crater は非常に有用ですが、いくつかの注意点を認識しておくことも重要です。

• すべてのコードが crates.io にあるわけではありません！ GitHub やその他の場所にあるリポジトリにも多くのコードがあります。 また、企業は自社のコードを公開したくない場合があります。 したがって、Crater の実行が成功したからといって、 破壊的影響がまったくないという意味にはなりません。引き続き注意が必要です。

• Crater は x86_64 上の Linux ビルドのみを実行します。したがって、他のアーキテクチャやプラットフォームはテストされません。 重要な点として、これには Windows が含まれます。

• 多くの crate はテストされません。 これには多くの理由が考えられます。たとえば、 その crate がすでにコンパイルできない（例: 古い nightly 機能を使用している）、テストが壊れている、または不安定である、 ネットワークアクセスを必要とする、その他の理由がある、といった場合です。

• Crater を実行する前に、@bors try が成果物のビルドに成功している必要があります。 つまり、コードがコンパイルできない場合は Crater を実行できません。

Fuchsia 統合テスト

Fuchsia は、約 200 万行の Rust コードを持つオープンソースのオペレーティングシステムです。¹ 過去に多数の regressions を検出しており、その後 CI に含められました。

Fuchsia ジョブが壊れた場合はどうすればよいですか？

fuchsia ping グループに連絡し、支援を依頼してください。

@rustbot ping fuchsia

CI で Fuchsia をビルドする

Fuchsia は、プルリクエストがマージされる前に実行される bors テストスイートの一部として ビルドされます。

プルリクエストによって Fuchsia ビルダーが壊れる可能性を懸念しており、 bors キューに送信する前にテストしたい場合は、Fuchsia 統合をビルドする try ジョブを実行するよう bors に依頼するだけです: @bors try jobs=x86_64-fuchsia。

Fuchsia をローカルでビルドする

Fuchsia は Rust 以外の言語を使用しているため、ビルドシステムとして Cargo を 使用していません。また、ツールチェーンのビルドが 特定の 方法 で構成されている必要もあります。

Fuchsia をビルドする推奨方法は、Fuchsia のチェックアウトとビルドを代わりに実行する Docker スクリプトを使用することです。以前に Docker テストを実行したことがある場合は、 Rust チェックアウトから次のコマンドを実行するだけで、ローカルの Rust ツールチェーンを使用して Fuchsia をダウンロードしてビルドできます。

src/ci/docker/run.sh x86_64-fuchsia

Docker でジョブを実行およびデバッグする方法の詳細については、 Testing with Docker の章を参照してください。

Fuchsia のチェックアウトは大きいことに注意してください。本稿執筆時点では、チェックアウトと ビルドには 46G の容量が必要であり、想像できるとおり、完了までにしばらく 時間がかかります。

Fuchsia チェックアウトを変更する

Fuchsia をローカルでビルドしたい主な理由は、リグレッションを 調査する必要があるためです。Docker ビルドを実行した後、Rust チェックアウトの obj/fuchsia ディレクトリ内に Fuchsia のチェックアウトがあります。 build-fuchsia.sh スクリプトの KEEP_CHECKOUT 行を KEEP_CHECKOUT=1 に変更すると、 必要に応じてチェックアウトを変更し、上記のビルドコマンドを再実行できます。これにより、 以前のすべてのビルド結果が再利用されます。

Fuchsia チェックアウトをカスタマイズするためのその他のオプションは、 build-fuchsia.sh スクリプトで確認できます。

Fuchsia ビルドをカスタマイズする

Rust CI で Fuchsia をビルドするために使用されるオプションの詳細は、 build-fuchsia.sh によって呼び出される build_fuchsia_from_rust_ci.sh スクリプトで 確認できます。

Fuchsia のビルドシステムは GN を使用します。これは Ninja ファイルを生成し、その後ビルドを実行する作業を Ninja に引き渡すメタビルドシステムです。

Fuchsia 開発者は fx を使用してビルドを実行し、その他の開発タスクを行います。 このツールは Fuchsia チェックアウトの .jiri_root/bin にあります。一部のワークフローでは、 これを $PATH に追加する必要があるかもしれません。

関連する fx サブコマンドがいくつかあります。たとえば次のとおりです。

• fx set はビルド引数を受け取り、それを out/default/args.gn に書き込み、 GN を実行します。
• fx build は Ninja を使用して Fuchsia プロジェクトをビルドします。ビルド引数への 変更を自動的に検出して GN を再実行します。デフォルトではすべてをビルドしますが、 特定のターゲットをビルドするためのターゲットパスも受け付けます（下記参照）。
• fx clippy は特定の Rust ターゲット（またはそのすべて）に対して Clippy を実行します。Rust CI ビルドでは、 ほとんどの Rust ターゲットで codegen を実行しないようにするため、これを使用します。内部では、 fx build と同様に Ninja を呼び出します。clippy の結果は、出力される前にビルド出力ディレクトリ内の json ファイルに保存されます。

ターゲットパス

GN は次のようなパスを使用してビルドターゲットを識別します。

//src/starnix/kernel:starnix_core

先頭の // はチェックアウトのルートを意味し、残りのスラッシュは ディレクトリ名です。: の後の文字列は、そのディレクトリの BUILD.gn ファイルで定義されたターゲットの ターゲット名 です。

ターゲット名がディレクトリ名と同じ場合は省くことができます。言い換えると、 //src/starnix/kernel は //src/starnix/kernel:kernel と同じです。

これらのターゲットパスは、依存関係を参照するために BUILD.gn ファイル内で使用され、 fx build でも使用できます。

コンパイラフラグを変更する

ターゲットに追加される GN config の中にカスタムコンパイラフラグを入れることができます。 簡単な例を示します。

config("everybody_loops") {
    rustflags = [ "-Zeverybody-loops" ]
}

rustc_binary("example") {
    crate_root = "src/bin.rs"
    # ...既存のキーをここに...
    configs += [ ":everybody_loops" ]
}

これにより、example ターゲットをビルドするときに rustc に -Zeverybody-loops フラグが追加されます。あるターゲットに依存するすべてのターゲットに config を追加するために public_configs も使用できることに注意してください。

ビルド内のすべての Rust ターゲットにフラグを追加したい場合は、 rustflags を //build/config:compiler config、またはそのファイルから参照される OS 固有の config に追加できます。Rust ターゲットでは cflags と ldflags は無視されることに注意してください。

ninja と rustc コマンドを直接実行する

1 レイヤー下に進むと、fx build は ninja を呼び出し、さらにそれが最終的に rustc を呼び出します。すべてのビルドアクションは out ディレクトリ内で実行されます。これは通常、 Fuchsia チェックアウト内の out/default です。

ninja が呼び出す実際のコマンドを表示させるには、そのコマンドが失敗するように強制します。 たとえば、ターゲットのソースファイルの 1 つに構文エラーを追加します。 コマンドを取得したら、出力ディレクトリ内からそれを実行できます。

ツールチェーン自体を変更した後は、fx build または ninja がすべての Rust ターゲットを 再ビルドするように、out/default/args.gn 内のビルド設定 rustc_version_string を 変更する必要があります。これはテキストエディターで行うことができ、文字列の内容は、 あるビルドから次のビルドへ変化している限り重要ではありません。 build_fuchsia_from_rust_ci.sh は、ツールチェーンディレクトリをハッシュすることでこれを行います。

Fuchsia のウェブサイトには、build system のより詳細なドキュメントがあります。

その他のヒントとテクニック

build_fuchsia_from_rust_ci.sh を使用するときは、初回実行後に fx set コマンドをコメントアウトして、毎回 GN が再実行されないようにできます。これを行う場合は、 version_string 行もコメントアウトして数秒節約できます。

初回ビルド後の ninja の起動時間を短縮するには、export NINJA_PERSISTENT_MODE=1 を実行します。

Fuchsia ターゲットサポート

Fuchsia ターゲットサポートの詳細については、the rustc book の Fuchsia の章を参照してください。

1. 2024 年 6 月時点で、Fuchsia には約 200 万行のファーストパーティ Rust コードと、ほぼ同量のサードパーティコードがありました。これは tokei によるカウントです （コメントと空行は除外）。 ↩

Rust for Linux 統合テスト

Rust for Linux (RfL) は、Linux カーネルに Rust プログラミング言語のサポートを追加する取り組みです。

Rust for Linux ジョブが壊れた場合はどうすればよいですか？

PR が Rust for Linux CI ジョブを壊した場合は、次のようにします。

• 障害が意図しないもので、一時的なものに見える場合は、RfL に 知らせて再試行します。
  • PR が緊急で、再試行しても修正されない場合は、CI ジョブを 一時的に無効にします（src/ci/github-actions/jobs.yml の image: x86_64-rust-for-linux ジョブをコメントアウトします）。
• 障害が意図しないものだった場合は、その障害を解決するように PR を変更します。
• 障害が意図したものだった場合は、RfL に知らせて、 カーネル側で何を変更する必要があるかを話し合います。
  • PR が緊急の場合は、CI ジョブを一時的に無効にします（ src/ci/github-actions/jobs.yml の image: x86_64-rust-for-linux ジョブをコメントアウトします）。
  • PR が数日待てる場合は、RfL メンテナーが必要な変更を行った 新しい Linux カーネルのコミットハッシュを提供するのを待ち、それを PR に適用します。これにより、変更が機能することを確認できます（ src/ci/docker/scripts/rfl-build.sh の LINUX_VERSION 環境変数を更新します）。

RfL 開発者に連絡する必要がある場合は、Rust for Linux ping グループに ping して助けを求めることができます。

@rustbot ping rfl

CI で Rust for Linux をビルドする

Rust for Linux は、プルリクエストがマージされる前に実行される bors テスト群の一部として ビルドされます。

このワークフローは、Rust コンパイラの stage1 sysroot をビルドし、Linux カーネルをダウンロードして、この sysroot を使用して複数の Rust for Linux ドライバーと サンプルのコンパイルを試みます。RfL は複数の不安定なコンパイラ/言語機能を使用しているため、 このワークフローにより、特定のコンパイラ変更によってそれが壊れる場合に通知されます。

プルリクエストが Rust for Linux ビルダーを壊す可能性を懸念していて、 bors キューに送信する前にテストしたい場合は、bors に Rust for Linux 統合をビルドする try ジョブを実行するよう依頼するだけです。 @bors try jobs=x86_64-rust-for-linux。

コード生成バックエンドのテスト

コード生成の章も参照してください。

主要な LLVM コード生成バックエンドに加えて、rust-lang/rust CI では、特定のテストジョブで cranelift および GCC コード生成バックエンドのテストも実行します。

関連するテストの詳細については、以下を参照してください。

• Cranelift コード生成バックエンドのテスト
• GCC コード生成バックエンドのテスト

Cranelift コード生成バックエンドのテスト

TODO: このページにもう少し情報を追加してください。

GCC コード生成バックエンド

このバックエンドとコンパイラーの統合を壊す可能性のある変更を見つけやすくするため、CI では GCC コード生成バックエンドを使ってコンパイラーのテストスイートの一部を実行しています。

GCC コード生成バックエンド全般についてバグや問題に遭遇した場合は、遠慮なく rustc_codegen_gcc リポジトリで issue を開いてください。

なお、このバックエンドは現在 x86_64-unknown-linux-gnu ターゲットのみをサポートしています。

GCC バックエンドの CI エラーに遭遇した場合

CI の x86_64-gnu-gcc ジョブで GCC コード生成バックエンドを使って実行されたテストに関連するエラーに遭遇した場合は、 次のコマンドを使用して、CI で起きることを再現しながら、GCC バックエンドを使って UI テストをローカルで実行できます。

./x test tests/ui \
  --set 'rust.codegen-backends = ["llvm", "gcc"]' \
  --set 'rust.debug-assertions = false' \
  --test-codegen-backend gcc

CI で別のテストスイートが失敗した場合は、tests/ui の部分を変更する必要があります。

CI ジョブ全体をローカルで再現するには、cargo run --manifest-path src/ci/citool/Cargo.toml run-local x86_64-gnu-gcc を実行できます。 詳細については、Docker によるテストを参照してください。

GCC ジョブが失敗した場合はどうすればよいですか？

GCC ジョブのテストが失敗し、その失敗が GCC バックエンドによって引き起こされた可能性があるように見える場合は、@rust-lang/wg-gcc-backend を使用して cg-gcc ワーキンググループに ping できます。

GCC バックエンドで失敗するコンパイラーテストの修正が自明でない場合は、//@ ignore-backends: gcc compiletest ディレクティブを使用して、cg_gcc で実行されるときにそのテストを無視できます。

ビルドするコード生成バックエンドの選択

rust.codegen-backends = [...] bootstrap オプションは、どのコード生成バックエンドがビルドされ、生成される rustc の sysroot に含まれるかに影響します。 GCC コード生成バックエンドを使用するには、bootstrap.toml のこの配列に "gcc" を含める必要があります。

rust.codegen-backends = ["llvm", "gcc"]

bootstrap.toml ファイルを変更したくない場合は、代わりに x コマンドを --set 'rust.codegen-backends=["llvm", "gcc"]' とともに実行できます。 例:

./x build --set 'rust.codegen-backends=["llvm", "gcc"]'

codegen-backends 配列の最初のバックエンドによって、ビルドされた rustc の デフォルトバックエンドとして使用されるバックエンドが決まります。 これにより、stage 1 標準ライブラリ（または stage 2 以降でビルドされるもの）をコンパイルするために使用されるバックエンドも決まります。 したがって、デフォルトで GCC バックエンドを使用する rustc を生成するには、この配列の最初の要素として "gcc" を置くことができます。

./x build --set 'rust.codegen-backends=["gcc"]' library

テストで使用するコード生成バックエンドの選択

テスト用の Rust プログラムをビルドするために GCC コード生成バックエンドを使用してコンパイラーテストを実行するには、 --test-codegen-backend フラグを使用できます。

./x test tests/ui --test-codegen-backend gcc

これが機能するためには、テスト対象のコンパイラーの sysroot ディレクトリで GCC コード生成バックエンドが利用可能である必要があることに注意してください。

CI から GCC をダウンロードする

gcc.download-ci-gcc bootstrap オプションは、GCC（GCC コード生成バックエンドの依存関係）が CI からダウンロードされるか、ローカルでビルドされるかを制御します。 デフォルト値は true で、GCC ソースにローカルの変更がなく、指定されたホストターゲットが CI で利用可能な場合は、CI から GCC をダウンロードします。

独自の GCC を提供する

独自の libgccjit.so ファイルを提供したい場合があります。 そのような場合の 1 つは、GCC がマルチターゲットコンパイラーではないため、rustc を別のターゲット向けにクロスコンパイルしたい場合です。 このユースケースをサポートするために、gcc.libgccjit-libs-dir bootstrap オプションがあります。 このオプションは gcc.download-ci-gcc を上書きします。つまり、bootstrap によって libgccjit.so がダウンロードされたりローカルでビルドされたりすることはありません。 このディレクトリのディレクトリ構造は <host>/<target>/libgccjit.so です。たとえば、次のようになります。

.
├── m68k-unknown-linux-gnu
│   └── m68k-unknown-linux-gnu
│       └── libgccjit.so
└── x86_64-unknown-linux-gnu
    ├── m68k-unknown-linux-gnu
    │   └── libgccjit.so
    └── x86_64-unknown-linux-gnu
        └── libgccjit.so

バックエンド自体のテストの実行

GCC コード生成バックエンドを使用してコンパイラーのテストスイートを実行することに加えて、バックエンド自体のテストスイートも実行できます。

現在は、次のコマンドを使用して実行できます。

./x test rustc_codegen_gcc

これが機能するためには、バックエンドが有効化されている必要があります。

パフォーマンステスト

rustc-perf

コンパイラのパフォーマンスを改善し、パフォーマンスのリグレッションを防ぐために、 多くの作業が行われています。

rustc-perf プロジェクトは、 パフォーマンスのテストと追跡のための複数のサービスを提供しています。 これは、ベンチマークをサービスとして実行するためのホストされたインフラストラクチャを提供します。 現時点では、x86_64-unknown-linux-gnu ビルドのみが追跡されています。

“perf run” は、多数の人気のあるクレートについて、異なる構成における コンパイラのパフォーマンスを比較するために使用されます。 異なる構成には、“fresh builds”、インクリメンタルコンパイルを用いたビルドなどが含まれます。

perf run の結果は、コンパイラの 2 つのバージョン間の比較 （それぞれのコミットハッシュによるもの）です。

rustc-perf を使用して、コンパイラを ローカルで手動でベンチマークおよびプロファイルすることもできます。

自動 perf run

各 PR がマージされた後、コンパイラに対して一連のベンチマークが実行されます。 結果は https://perf.rust-lang.org/ Web サイトで時系列に追跡されます。 変更はすべて PR 上のコメントに記録されます。

手動 perf run

さらに、必要に応じて、PR がマージされる前にパフォーマンステストを実行できます。 PR がパフォーマンスに影響を与える可能性がある場合、 特に悪影響を与える可能性がある場合は、perf run をリクエストするべきです。

PR のパフォーマンスへの影響を評価するには、PR にこのコメントを書きます。

@bors try @rust-timer queue

注記: perf run の実行を許可されたユーザーのみが、このコメントを投稿できます。 それを使用できるチームは、Teams リポジトリの [permissions] セクションに perf = true の値で記録されています（bors 権限も必要です）。もしあなたが それらのチームのいずれにも属していない場合は、代わりに誰かに投稿してもらうよう 気軽に依頼してください（Zulip 上、または割り当てられたレビュー担当者に依頼してください）。

これにより、まず bors に “try” ビルドを実行するよう指示します。これは x86_64-unknown-linux-gnu 向けの完全なリリースビルドを行います。 ビルドが完了すると、それに対してパフォーマンススイートを実行するためにキューに入れられます。 パフォーマンステストが完了すると、 bot が PR に概要と完全なレポートへのリンクを含むコメントを投稿します。

すでにビルド済みのアーティファクトに対して perf run を実行したい場合 （たとえば、まだベンチマークされていない以前の try ビルドに対して）は、代わりに次を実行できます。

@rust-timer build <commit-sha>

ただし、同じアーティファクトを 2 回ベンチマークすることはできません。

利用可能な perf bot コマンドの詳細については、 こちらを参照してください。

ベンチマークプロセス自体の詳細については、perf collector documentationを参照してください。

テスト関連のその他の情報

RUSTC_BOOTSTRAP と安定性

これはブートストラップ/コンパイラの実装詳細ですが、テストにも役立つことがあります。

• RUSTC_BOOTSTRAP=1 は「不正に」通常の安定性チェックをバイパスし、 安定版 rustc で不安定機能や CLI フラグを使用できるようにします。
• RUSTC_BOOTSTRAP=-1 は、指定した rustc に、実際には nightly rustc であっても 安定版コンパイラであるかのように振る舞わせます。これは、コンパイラの一部の 振る舞い（例: 診断）が、コンパイラが nightly かどうかによって異なることがあるため便利です。

ui テストや //@ rustc-env をサポートするその他のテストスイートでは、次のように指定できます。

// 安定版 rustc で不安定機能を使用できるようにする
//@ rustc-env:RUSTC_BOOTSTRAP=1

// または nightly rustc に安定版 rustc であるかのように振る舞わせる
//@ rustc-env:RUSTC_BOOTSTRAP=-1

run-make/run-make-cargo テストでは、//@ rustc-env はサポートされていません。 個々の rustc 呼び出しについては、次のようなことができます。

use run_make_support::rustc;

fn main() {
    rustc()
        // 自分が非常に安定しているふりをする
        .env("RUSTC_BOOTSTRAP", "-1")
        //...
        .run();
}

コンパイラのデバッグ

この章では、コンパイラをデバッグするためのヒントをいくつか紹介します。 これらのヒントは、何に取り組んでいるかに関係なく役立つことを目指しています。 他の章の中には、 コンパイラの特定の部分に関するアドバイスがあります（例: クエリのデバッグと テストの章や LLVM デバッグの 章）。

コンパイラの設定

デフォルトでは、rustc はほとんどのデバッグ情報なしでビルドされます。 デバッグ情報を有効にするには、 bootstrap.toml で rust.debug = true を設定してください。

rust.debug = true を設定すると、多くの異なるデバッグオプション（例: debug-assertions、 debug-logging など）が有効になります。必要であれば個別に調整できますが、多くの人は 単に rust.debug = true を設定します。

GDB を使用して rustc をデバッグしたい場合は、bootstrap.toml に次のオプションを設定してください。

rust.debug = true
rust.debuginfo-level = 2

注: これは大量のディスク容量を使用します （ 35GB 以上）し、 コンパイル時間も大幅に長くなります。 debuginfo-level = 1（debug = true のときのデフォルト）では、 実行パスを追跡できますが、 デバッグ用のシンボル情報は失われます。

デフォルト設定では、symbol-mangling-version v0 が有効になります。 これには少なくとも GDB v10.2 が必要です。 そうでない場合は、bootstrap.toml で新しい symbol-mangling-version を無効にする必要があります。

rust.new-symbol-mangling = false

詳細については、bootstrap.example.toml のコメントを参照してください。

設定オプションを変更した後は、コンパイラをリビルドする必要があります。

ICE ファイルの抑制

デフォルトでは、rustc が Internal Compiler Error（ICE）に遭遇すると、ICE の内容を rustc-ice-<timestamp>-<pid>.txt という名前の ICE ファイルとして現在の作業ディレクトリにダンプします。 これが望ましくない場合は、RUSTC_ICE=0 を使用して ICE ファイルが作成されないようにできます。

バックトレースの取得

ICE（コンパイラ内の panic）が発生した場合、通常の Rust プログラムと同様に RUST_BACKTRACE=1 を設定して panic! のスタックトレースを取得できます。 記憶が正しければ、MinGW ではバックトレースは 機能しません。申し訳ありません。 問題がある場合やバックトレースが unknown だらけの場合は、 Linux、Mac、または Windows 上の MSVC を使用する方法を探した方がよいかもしれません。

デフォルト設定（debug が true に設定されていない場合）では、行番号が 有効になっていないため、バックトレースは次のようになります。

stack backtrace:
   0: std::sys::imp::backtrace::tracing::imp::unwind_backtrace
   1: std::sys_common::backtrace::_print
   2: std::panicking::default_hook::{{closure}}
   3: std::panicking::default_hook
   4: std::panicking::rust_panic_with_hook
   5: std::panicking::begin_panic
   (~~~~ LINES REMOVED BY ME FOR BREVITY ~~~~)
  32: rustc_typeck::check_crate
  33: <std::thread::local::LocalKey<T>>::with
  34: <std::thread::local::LocalKey<T>>::with
  35: rustc::ty::context::TyCtxt::create_and_enter
  36: rustc_driver::driver::compile_input
  37: rustc_driver::run_compiler

debug = true を設定すると、スタックトレースに行番号が表示されます。 その場合、バックトレースは次のようになります。

stack backtrace:
   (~~~~ LINES REMOVED BY ME FOR BREVITY ~~~~)
             at /home/user/rust/compiler/rustc_typeck/src/check/cast.rs:110
   7: rustc_typeck::check::cast::CastCheck::check
             at /home/user/rust/compiler/rustc_typeck/src/check/cast.rs:572
             at /home/user/rust/compiler/rustc_typeck/src/check/cast.rs:460
             at /home/user/rust/compiler/rustc_typeck/src/check/cast.rs:370
   (~~~~ LINES REMOVED BY ME FOR BREVITY ~~~~)
  33: rustc_driver::driver::compile_input
             at /home/user/rust/compiler/rustc_driver/src/driver.rs:1010
             at /home/user/rust/compiler/rustc_driver/src/driver.rs:212
  34: rustc_driver::run_compiler
             at /home/user/rust/compiler/rustc_driver/src/lib.rs:253

-Z フラグ

コンパイラには多数の -Z * フラグがあります。 これらは nightly でのみ有効になる不安定なフラグです。 その多くはデバッグに役立ちます。 -Z フラグの完全な一覧を取得するには、-Z help を使用してください。

便利なフラグの 1 つに -Z verbose-internals があります。これは一般に、デバッグに役立つ可能性がある 情報をより多く出力できるようにします。

すぐ下に、選択したいくつかのフラグについて詳しい解説があります。

エラーのバックトレースの取得

コンパイラがエラーメッセージを出力する箇所までのバックトレースを取得したい場合は、 -Z treat-err-as-bug=n を渡すことができます。これにより、 コンパイラは n 番目のエラーで panic します。 =n を省略した場合、コンパイラは n として 1 を想定するため、最初に遭遇したエラーで panic します。

例:

cat error.rs

fn main() {
    1 + ();
}

$ rustc +stage1 error.rs
error[E0277]: cannot add `()` to `{integer}`
 --> error.rs:2:7
  |
2 |       1 + ();
  |         ^ no implementation for `{integer} + ()`
  |
  = help: the trait `Add<()>` is not implemented for `{integer}`

error: aborting due to previous error

では、上記のエラーはどこから発生しているのでしょうか？

$ RUST_BACKTRACE=1 rustc +stage1 error.rs -Z treat-err-as-bug
error[E0277]: the trait bound `{integer}: std::ops::Add<()>` is not satisfied
 --> error.rs:2:7
  |
2 |     1 + ();
  |       ^ no implementation for `{integer} + ()`
  |
  = help: the trait `std::ops::Add<()>` is not implemented for `{integer}`

error: internal compiler error: unexpected panic

note: the compiler unexpectedly panicked. this is a bug.

note: we would appreciate a bug report: https://github.com/rust-lang/rust/blob/HEAD/CONTRIBUTING.md#bug-reports

note: rustc 1.24.0-dev running on x86_64-unknown-linux-gnu

note: run with `RUST_BACKTRACE=1` for a backtrace

thread 'rustc' panicked at 'encountered error with `-Z treat_err_as_bug',
/home/user/rust/compiler/rustc_errors/src/lib.rs:411:12
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose
backtrace.
stack backtrace:
  (~~~ IRRELEVANT PART OF BACKTRACE REMOVED BY ME ~~~)
   7: rustc::traits::error_reporting::<impl rustc::infer::InferCtxt<'a, 'tcx>>
             ::report_selection_error
             at /home/user/rust/compiler/rustc_middle/src/traits/error_reporting.rs:823
   8: rustc::traits::error_reporting::<impl rustc::infer::InferCtxt<'a, 'tcx>>
             ::report_fulfillment_errors
             at /home/user/rust/compiler/rustc_middle/src/traits/error_reporting.rs:160
             at /home/user/rust/compiler/rustc_middle/src/traits/error_reporting.rs:112
   9: rustc_typeck::check::FnCtxt::select_obligations_where_possible
             at /home/user/rust/compiler/rustc_typeck/src/check/mod.rs:2192
  (~~~ IRRELEVANT PART OF BACKTRACE REMOVED BY ME ~~~)
  36: rustc_driver::run_compiler
             at /home/user/rust/compiler/rustc_driver/src/lib.rs:253

よし、これでエラーのバックトレースを取得できました！

delayed bug のデバッグ

-Z eagerly-emit-delayed-bugs オプションを使うと、delayed bug を簡単にデバッグできます。 これは delayed bug を通常のエラーに変換します。つまり、可視化します。これは -Z treat-err-as-bug と組み合わせて使用することで、特定の delayed bug で停止し、バックトレースを取得できます。

エラー作成場所を取得する

-Z track-diagnostics は、エラーがどこで出力されたかを特定するのに役立ちます。 これはそのために #[track_caller] を使用し、エラーとともにその場所を出力します。

$ RUST_BACKTRACE=1 rustc +stage1 error.rs -Z track-diagnostics
error[E0277]: cannot add `()` to `{integer}`
 --> src\error.rs:2:7
  |
2 |     1 + ();
  |       ^ no implementation for `{integer} + ()`
-Ztrack-diagnostics: created at compiler/rustc_trait_selection/src/traits/error_reporting/mod.rs:638:39
  |
  = help: the trait `Add<()>` is not implemented for `{integer}`
  = help: the following other types implement trait `Add<Rhs>`:
            <&'a f32 as Add<f32>>
            <&'a f64 as Add<f64>>
            <&'a i128 as Add<i128>>
            <&'a i16 as Add<i16>>
            <&'a i32 as Add<i32>>
            <&'a i64 as Add<i64>>
            <&'a i8 as Add<i8>>
            <&'a isize as Add<isize>>
          and 48 others

For more information about this error, try `rustc --explain E0277`.

これは -Z treat-err-as-bug と似ていますが、異なります。

• 出力されたすべてのエラーについて場所を出力します
• デバッグシンボル付きでビルドされたコンパイラを必要としません
• 大きなスタックトレースを読み解く必要がありません。

ロギング出力を取得する

コンパイラはロギングに tracing クレートを使用します。

詳細については、tracing に関するガイドのセクションを参照してください

リグレッションの絞り込み（二分探索）

cargo-bisect-rustc ツールは、rustc の挙動の変化を引き起こした PR を正確に見つけるための、手早く簡単な方法として使用できます。 これは rustc の PR アーティファクトを自動的にダウンロードし、リグレッションが見つかるまで、あなたが提供したプロジェクトに対してそれらをテストします。 その後、その PR を確認して、なぜ 変更されたのかについてより多くの文脈を得ることができます。 使用方法については、このチュートリアルを参照してください。

Rust の CI からアーティファクトをダウンロードする

kennytm による rustup-toolchain-install-master ツールは、特定の SHA1 に対して Rust の CI によって生成されたアーティファクトをダウンロードするために使用できます。これは基本的には、ある PR が正常にマージされたことに対応します。そして、それらをローカルで使用できるようにセットアップします。 これは @bors try によって生成されたアーティファクトに対しても機能します。 これは、自分でビルドせずに PR の結果として生成されたビルドを調べたい場合に便利です。

#[rustc_*] TEST 属性

コンパイラは、大量の内部（永続的に unstable な）属性を定義しており、その一部はコンパイラ内部の追加情報をダンプすることでデバッグに役立ちます。 これらには rustc_ というプレフィックスが付けられており、内部 feature である rustc_attrs によってゲートされています（例: #![feature(rustc_attrs)] で有効化）。

完全かつ最新の一覧については、builtin_attrs を参照してください。 より具体的には、TEST とマークされているものです。 注目すべきものをいくつか示します。

すぐ下に、選択したいくつかについての詳しい解説があります。

Graphviz 出力（.dot ファイル）の整形

特定の機能をデバッグするためのコンパイラオプションの中には、graphviz グラフを生成するものがあります。たとえば、関数に付与された #[rustc_mir(borrowck_graphviz_postflow="suffix.dot")] 属性は、-Zdump-mir-dataflow と組み合わせることで、さまざまな borrow-checker のデータフローグラフをダンプします。

これらはすべて .dot ファイルを生成します。これらのファイルを表示するには、graphviz をインストールし（例: apt-get install graphviz）、次のコマンドを実行します。

dot -T pdf maybe_init_suffix.dot > maybe_init_suffix.pdf
firefox maybe_init_suffix.pdf # またはお好みの pdf ビューアー

型レイアウトのデバッグ

内部属性 #[rustc_dump_layout(...)] は、それが付与された型の Layout をダンプするために使用できます。 例:

#![allow(unused)]
#![feature(rustc_attrs)]

fn main() {
#[rustc_dump_layout(debug)]
type T<'a> = &'a u32;
}

次の内容が出力されます。

error: layout_of(&u32) = Layout {
           size: Size(8 bytes),
           align: AbiAlign {
               abi: Align(8 bytes),
           },
           backend_repr: Scalar(
               Initialized {
                   value: Pointer(
                       AddressSpace(
                           0,
                       ),
                   ),
                   valid_range: 1..=18446744073709551615,
               },
           ),
           fields: Primitive,
           largest_niche: Some(
               Niche {
                   offset: Size(0 bytes),
                   value: Pointer(
                       AddressSpace(
                           0,
                       ),
                   ),
                   valid_range: 1..=18446744073709551615,
               },
           ),
           uninhabited: false,
           variants: Single {
               index: 0,
           },
           max_repr_align: None,
           unadjusted_abi_align: Align(8 bytes),
           randomization_seed: 281492156579847,
       }
 --> src/lib.rs:4:1
  |
4 | type T<'a> = &'a u32;
  | ^^^^^^^^^^^^^^^^^^^^^

error: aborting due to previous error

rustc をデバッグするための CodeLLDB の設定

VSCode を使用しており、関心のあるコード部分についてデバッグレベル 1 または 2 を要求するように bootstrap.toml を編集している場合は、VSCode の CodeLLDB 拡張機能を使ってデバッグできるはずです。

以下は、stage 1 コンパイラをビルドされたディレクトリから直接実行するために使用している launch.json ファイルのサンプルです（“インストール“されている必要はありません）。

// .vscode/launch.json
{
    "version": "0.2.0",
    "configurations": [
      {
        "type": "lldb",
        "request": "launch",
        "name": "Launch",
        "args": [],  // コンパイラに渡す文字列のコマンドライン引数の配列
        "program": "${workspaceFolder}/build/host/stage1/bin/rustc",
        "windows": {  // windows を使用している場合に適用可能
            "program": "${workspaceFolder}/build/host/stage1/bin/rustc.exe"
        },
        "cwd": "${workspaceFolder}",  // プログラム開始時の現在の作業ディレクトリ
        "stopOnEntry": false,
        "sourceLanguages": ["rust"]
      }
    ]
  }

tracing を使ってコンパイラをデバッグする

コンパイラには多数の debug!（または trace!）呼び出しがあり、多くの箇所でログ情報を出力します。 これらは、バグを完全に見つけるまでには至らなくても少なくとも場所を絞り込むのに非常に役立ちます。また、コンパイラが特定の処理を行っている理由を把握するのにも役立ちます。

ログを見るには、RUSTC_LOG 環境変数をログフィルターに設定する必要があります。 ログフィルターの完全な構文は、tracing-subscriber の rustdocにあります。

環境変数

これは、rustc が tracing 出力をカスタマイズするために受け付ける環境変数の概要です。 これらの定義は、ほとんど compiler/rustc_log/src/lib.rs にあります。

関数レベルのフィルター

rustc の多くの関数には、次のような注釈が付けられています。

#[instrument(level = "debug", skip(self))]
fn foo(&self, bar: Type) {}

これにより、次のように使用できます。

RUSTC_LOG=[foo]

これにより、次のことをすべて一度に行えます。

• foo へのすべての関数呼び出しをログに記録する
• 引数をログに記録する（skip リスト内のものを除く）
• 関数が戻るまで、（コンパイラ内の他の場所からのものを含めて）すべてをログに記録する

すべては不要な場合

関数のスコープによっては、その本体内のすべてをログに記録したくない場合があります。 例として、do_mir_borrowck 関数は、借用チェックされる些細なコードに対しても数百行をダンプします。

すべてのフィルターを組み合わせることができるため、たとえば次のように crate/module パスを追加できます。

RUSTC_LOG=rustc_borrowck[do_mir_borrowck]

すべての呼び出しは不要な場合

libcore をコンパイルしている場合、すべての borrowck ダンプはおそらく不要で、特定の関数に対するものだけが必要でしょう。 関数呼び出しは、引数を正規表現で指定することでフィルタリングできます。

RUSTC_LOG=[do_mir_borrowck{id=\.\*from_utf8_unchecked\.\*}]

これにより、from_utf8_unchecked を借用チェックするログだけが得られます。 無視された do_mir_borrowck ごとに短いメッセージは引き続き表示されますが、それらの呼び出し内の内容は表示されないことに注意してください。 これは、発生している呼び出しを調べるのに役立ち、正規表現を入力し間違えた場合に調整する助けになります。

クエリレベルのフィルター

すべてのクエリには、自動的にロギングスパンがタグ付けされるため、 クエリの実行中のすべてのログメッセージを表示できます。 たとえば、型チェック中のすべてをログに記録したい場合は、次のようにします。

RUSTC_LOG=[typeck]

クエリ引数は tracing フィールドとして含まれます。つまり、引数のデバッグ表示に対してフィルタリングできます。 たとえば、typeck クエリには、何がチェックされているかを示す引数 key: LocalDefId があります。 その LocalDefId に一致する正規表現を使うことで、特定の関数に対する型チェックをログに記録できます。

RUSTC_LOG=[typeck{key=.*name_of_item.*}]

クエリによって引数は異なります。 クエリとその引数の一覧は、rustc_middle/src/queries.rs にあります。

広範なモジュールレベルのフィルター

log crate のフィルターに似たフィルターを使うこともでき、特定のモジュール内のすべてを有効化できます。 これはしばしば冗長すぎ、構造化も不十分になるため、関数レベルのフィルターを使うことを推奨します。

ログフィルターは、すべての debug! 出力以上（たとえば info! も含まれます）を得るために単に debug とすることもできますし、特定のモジュールからのすべての出力（trace! も含まれます）を得るために path::to::module とすることもできます。また、特定のモジュールからの debug! 出力以上を得るために path::to::module=debug とすることもできます。

たとえば、特定のモジュールについて debug! 出力以上を得るには、RUSTC_LOG=path::to::module=debug rustc my-file.rs でコンパイラを実行できます。 すると、すべての debug! 出力が標準エラー出力に表示されます。

部分的なパスを使ってもフィルターは機能することに注意してください。 たとえば、rustdoc::passes::collect_intra_doc_links からの info! 出力だけを見たい場合は、 RUSTDOC_LOG=rustdoc::passes::collect_intra_doc_links=info を使うことも、RUSTDOC_LOG=rustdoc::passes::collect_intra=info を使うこともできます。

rustdoc を開発している場合は、代わりに RUSTDOC_LOG を使ってください。 Miri を開発している場合は、代わりに MIRI_LOG を使ってください。 要領はお分かりでしょう :)

使用できる完全な構文については、tracing crate のドキュメント、特に debug! のドキュメントを参照してください。 （注: コンパイラとは異なり、tracing crate とその例では RUSTC_LOG 環境変数を使用します。 rustc、rustdoc、およびその他のツールはカスタム環境変数を設定します。）

非常に厳密なフィルターを使わない限り、ロガーは大量の出力を生成するため、可能な限り最も具体的なモジュール（複数ある場合はカンマ区切り）を使用してください。 通常は、標準エラー出力をファイルにパイプし、テキストエディターでログ出力を見るのがよいでしょう。

では、まとめると次のようになります。

# これは `rustc_middle/src/traits` 内のすべての debug 呼び出しの出力を
# 標準エラーに送ります。コンソールのスクロールバックを埋め尽くす可能性があります。
$ RUSTC_LOG=rustc_middle::traits=debug rustc +stage1 my-file.rs

# これは `rustc_middle/src/traits` 内のすべての debug 呼び出しの出力を
# `traits-log` に送るので、あとでテキストエディターで確認できます。
$ RUSTC_LOG=rustc_middle::traits=debug rustc +stage1 my-file.rs 2>traits-log

# 推奨しません！これは Rust コンパイラ内のすべての `debug!` 呼び出しの
# 出力を表示します。その数は*非常に多い*ため、何かを見つけるのは
# 難しくなります。
$ RUSTC_LOG=debug rustc +stage1 my-file.rs 2>all-log

# これは `rustc_codegen_ssa` 内のすべての `info!` 呼び出しの出力を表示します。
#
# `codegen_instance` には、codegen されたすべての関数を出力する
# `info!` 文があります。これは、どの関数が LLVM アサーションを
# 引き起こすかを調べるのに役立ちます。また、これは `debug!` ログではなく
# `info!` ログなので、公式コンパイラでも動作します。
$ RUSTC_LOG=rustc_codegen_ssa=info rustc +stage1 my-file.rs

# これは `rustc_codegen_ssa` と `rustc_resolve` 内のすべてのログを表示します。
$ RUSTC_LOG=rustc_codegen_ssa,rustc_resolve rustc +stage1 my-file.rs

# これは rustdoc またはそれが呼び出すすべての rustc ライブラリによる
# すべての `info!` 呼び出しの出力を表示します。
$ RUSTDOC_LOG=info rustdoc +stage1 my-file.rs

# これは rustdoc が直接行った `debug!` 呼び出しのみを表示し、
# `rustc*` クレートによるものは表示しません。
$ RUSTDOC_LOG=rustdoc=debug rustdoc +stage1 my-file.rs

ログの色

デフォルトでは、rustc（および rustdoc や Miri などの他のツール）は、ログ出力で ANSI カラーをいつ使うべきかを賢く判断します。 端末に出力している場合は色を使い、ファイルに出力している場合やどこか別の場所へパイプしている場合は色を使いません。 しかし、非常に厳密なフィルターを設定していない限り、端末でログ出力を読むのは難しいため、less のようなページャーに出力をパイプしたくなることがあります。 しかし、そうすると色がなくなってしまい、探しているものを見つけにくくなります！

ログ出力で色を使うかどうかは、RUSTC_LOG_COLOR 環境変数（rustdoc の場合は RUSTDOC_LOG_COLOR、Miri の場合は MIRI_LOG_COLOR など）で上書きできます。選択肢は 3 つあります: auto（デフォルト）、always、never です。 したがって、less にパイプするときに色を有効にしたい場合は、次のようなコマンドを使います:

# `-R` スイッチは、ANSI カラーをエスケープせずに表示するよう less に指示します。
$ RUSTC_LOG=debug RUSTC_LOG_COLOR=always rustc +stage1 ... | less -R

MIRI_LOG_COLOR は Miri から来るログにのみ色を付け、Miri が呼び出す rustc 関数からのログには色を付けないことに注意してください。 rustc からのログに色を付けるには RUSTC_LOG_COLOR を使ってください。

生成されるバイナリから debug! と trace! の呼び出しを保持または削除する方法

error!、warn!、info! の呼び出しはコンパイラのすべてのビルドに含まれますが、 debug! と trace! の呼び出しは、bootstrap.toml で rust.debug-logging=true が有効になっている場合にのみプログラムに含まれます（デフォルトでは無効です）。そのため、DEBUG ログが表示されない場合、特に RUSTC_LOG=rustc rustc some.rs でコンパイラを実行して INFO ログしか表示されない場合は、bootstrap.toml で rust.debug-logging=true が有効になっていることを確認してください。

ロギングのエチケットと慣習

debug! の呼び出しはデフォルトで削除されるため、ほとんどの場合、「不要な」debug! 呼び出しを追加してコミットするコードに残しておくことによる性能への影響を心配する必要はありません。それらが出荷するものの性能を低下させることはありません。

とはいえ、特に近くにある他の呼び出しやここから呼ばれる関数内の呼び出しと重複している場合は、トレース呼び出しが過剰になることもあります。 ここで達成すべき完璧なバランスはなく、debug! 文を残すことを許可するか、マージ前に削除するよう求めるかは、レビュアーの裁量に委ねられます。

非常に冗長なログには、debug! よりも trace! を使う方が望ましい場合があります。

大まかに守られている慣習として、関数 foo の先頭では debug!("foo(...)") よりも #[instrument(level = "debug")] （属性のドキュメントも参照） を使います。 関数内では、debug!("xyz = {:?}", variable.field) よりも debug!(?variable.field) を、debug!("bar = {:?}", var.method(arg)) よりも debug!(bar = ?var.method(arg)) を好んで使ってください。 この構文のドキュメントはこちらにあります。

注意すべきことの 1 つは、ログ内のコストの高い操作です。

モジュール rustc::foo 内に次の文があるとします。

debug!(x = ?random_operation(tcx));

この場合、誰かが RUSTC_LOG=rustc::foo でデバッグ版の rustc を実行すると、 random_operation() が実行されます。 この debug 文を有効にしない RUSTC_LOG フィルターでは、random_operation は実行されません。

つまり、コストが高すぎるものやクラッシュしそうなものをそこに置くべきではありません。それは、そのモジュールのロギングを使いたい人を困らせることになります。 誰かが別のバグを見つけるためにロギングを使おうとするまで、誰にも分かりません。

コンパイラのプロファイリング

このセクションでは、コンパイラをプロファイルし、どこで時間を費やしているかを調べる方法について説明します。

何を計測したいかに応じて、いくつかの異なるアプローチがあります。

• PR がコンパイラのパフォーマンスを改善するか、低下させるかを確認したい場合は、 ベンチマーク実行を依頼する方法について rustc-perf の章を参照してください。

• rustc がどこで時間を費やしているかについて中〜高レベルの概要を把握したい場合:

  • -Z self-profile フラグと measureme ツールは、プロファイリングへのクエリベースのアプローチを提供します。 詳細については、それらのドキュメントを参照してください。

• 関数レベルのパフォーマンスデータ、または単に上記のアプローチよりも詳しい情報が欲しい場合:

  • perf のようなネイティブコードプロファイラの使用を検討してください
  • または、ナノ秒精度でフル機能のグラフィカルインターフェイスを備えた tracy を使用してください。

• クレートグラフのコンパイル時間を見やすく視覚的に表示したい場合は、 cargo の --timings フラグを使用できます。 例: cargo build --timings。 CARGOFLAGS="--timings" ./x build を使って、このフラグをコンパイラ自体に対して使用できます

• メモリ使用量をプロファイルしたい場合は、使用しているオペレーティングシステムに応じて さまざまなツールを使用できます。

  • Windows の場合は、WPA ガイドを読んでください。

cargo-llvm-lines による rustc のブートストラップ時間の最適化

cargo-llvm-lines を使用すると、ジェネリック関数の すべてのインスタンス化にわたる LLVM IR の行数を数えることができます。 rustc のコンパイル時間の大部分は LLVM で費やされるため、LLVM に渡すコード量を 減らすことで rustc のコンパイルが速くなる、という考え方です。

やや独自の rustc ビルドプロセスと一緒に cargo-llvm-lines を使用するには、必要な LLVM IR を取得するために -C save-temps を使用できます。 このオプションは、コンパイル中に作成された一時的な作業生成物を保持します。 その中には、最適化パイプラインへの入力を表す LLVM IR が含まれており、 私たちの目的に理想的です。 これは LLVM ビットコード形式で *.no-opt.bc 拡張子のファイルに保存されます。

使用例:

cargo install cargo-llvm-lines
# 通常のクレートではここで `cargo llvm-lines` を実行できますが、`x` は普通ではありません :P

# 前回の実行結果が混ざらないように、毎回実行前にクリーンします。
./x clean
env RUSTFLAGS=-Csave-temps ./x build --stage 0 compiler/rustc

# 単一クレート、例: rustc_middle。（シェルの glob サポートに依存します。）
# 未最適化の LLVM ビットコードを、cargo-llvm-lines が受け付ける人間が読める LLVM アセンブリに変換します。
for f in build/x86_64-unknown-linux-gnu/stage0-rustc/x86_64-unknown-linux-gnu/release/deps/rustc_middle-*.no-opt.bc; do
  ./build/x86_64-unknown-linux-gnu/llvm/bin/llvm-dis "$f"
done
cargo llvm-lines --files ./build/x86_64-unknown-linux-gnu/stage0-rustc/x86_64-unknown-linux-gnu/release/deps/rustc_middle-*.ll > llvm-lines-middle.txt

# コンパイラのすべてのクレートを指定します。
for f in build/x86_64-unknown-linux-gnu/stage0-rustc/x86_64-unknown-linux-gnu/release/deps/*.no-opt.bc; do
  ./build/x86_64-unknown-linux-gnu/llvm/bin/llvm-dis "$f"
done
cargo llvm-lines --files ./build/x86_64-unknown-linux-gnu/stage0-rustc/x86_64-unknown-linux-gnu/release/deps/*.ll > llvm-lines.txt

コンパイラでの出力例:

  Lines            Copies          Function name
  -----            ------          -------------
  45207720 (100%)  1583774 (100%)  (TOTAL)
   2102350 (4.7%)   146650 (9.3%)  core::ptr::drop_in_place
    615080 (1.4%)     8392 (0.5%)  std::thread::local::LocalKey<T>::try_with
    594296 (1.3%)     1780 (0.1%)  hashbrown::raw::RawTable<T>::rehash_in_place
    592071 (1.3%)     9691 (0.6%)  core::option::Option<T>::map
    528172 (1.2%)     5741 (0.4%)  core::alloc::layout::Layout::array
    466854 (1.0%)     8863 (0.6%)  core::ptr::swap_nonoverlapping_one
    412736 (0.9%)     1780 (0.1%)  hashbrown::raw::RawTable<T>::resize
    367776 (0.8%)     2554 (0.2%)  alloc::raw_vec::RawVec<T,A>::grow_amortized
    367507 (0.8%)      643 (0.0%)  rustc_query_system::dep_graph::graph::DepGraph<K>::with_task_impl
    355882 (0.8%)     6332 (0.4%)  alloc::alloc::box_free
    354556 (0.8%)    14213 (0.9%)  core::ptr::write
    354361 (0.8%)     3590 (0.2%)  core::iter::traits::iterator::Iterator::fold
    347761 (0.8%)     3873 (0.2%)  rustc_middle::ty::context::tls::set_tlv
    337534 (0.7%)     2377 (0.2%)  alloc::raw_vec::RawVec<T,A>::allocate_in
    331690 (0.7%)     3192 (0.2%)  hashbrown::raw::RawTable<T>::find
    328756 (0.7%)     3978 (0.3%)  rustc_middle::ty::context::tls::with_context_opt
    326903 (0.7%)      642 (0.0%)  rustc_query_system::query::plumbing::try_execute_query

これはインクリメンタルコンパイルや ./x check では動作しないようなので、 rustc を 何度も コンパイルすることになります。 耐えられるようにするため、bootstrap.toml でいくつかの設定を変更することをお勧めします:

# 私のマシンではデバッグビルドの時間は _3 分の 1_ ですが、
# stage0 rustc より先をコンパイルすると耐えがたいほど遅くなります。
rust.optimize = false

# どうせ incremental は使えないので、少し速度を上げるために無効化します。
rust.incremental = false
# 実行はしないので、デバッグチェックをコンパイルしても意味がありません。
rust.debug = false

# 単一の codegen unit を使用すると出力は少なくなりますが、コンパイルは遅くなります。
rust.codegen-units = 0  # num_cpus

llvm-lines の出力はいくつかのオプションの影響を受けます。 rust.optimize = false にすると 2.1GB から 3.5GB に増え、codegen-units = 0 にすると 4.1GB になります。

MIR 最適化の影響は小さいです。 デフォルトの RUSTFLAGS="-Z mir-opt-level=1" と比較すると、レベル 0 では 0.3GB 増え、レベル 2 では 0.2GB 減ります。

インライン化は LLVM と GCC のコード生成バックエンドで行われており、 Cranelift のものだけが欠けています。

perf を使ったプロファイリング

これは、perf を使って rustc をプロファイリングする方法のガイドです。

初期手順

• rust-lang/rust のクリーンなチェックアウトを取得する
• bootstrap.toml に次の設定を行う:
  • rust.debuginfo-level = 1 - 行デバッグ情報を有効にする
  • rust.jemalloc = false - valgrind を使ったメモリ使用量のプロファイリングを可能にする
  • それ以外はすべてデフォルトのままにする
• ./x build を実行して完全なビルドを取得する
• その結果を指す rustup ツールチェーンを作成する
  • 手順については「ビルドして実行」セクションを参照してください

perf プロファイルの収集

perf は Linux 上の優れたツールであり、あらゆる種類の情報を収集して 分析するために使用できます。主に、プログラムがどこで時間を費やしているかを 把握するために使われます。ただし、キャッシュミスなど、他の種類のイベントにも 使用できます。

基本

基本的な perf コマンドは次のとおりです:

perf record -F99 --call-graph dwarf XXX

-F99 は、perf に 99 Hz でサンプリングするよう指示します。これにより、 長い実行で大量のデータが生成されるのを避けられます（なぜ 99 Hz なのか、ですか？ 他の周期的な活動と同期しにくいため、よく選ばれます）。--call-graph dwarf は、 正確なデバッグ情報からコールグラフ情報を取得するよう perf に指示します。XXX は プロファイリングしたいコマンドです。したがって、たとえば次のようにできます:

perf record -F99 --call-graph dwarf cargo +<toolchain> rustc

これは cargo を実行します – ここで <toolchain> は、最初に作成したツールチェーンの 名前である必要があります。ただし、注意すべき点がいくつかあります:

• 依存関係のビルドに費やされる時間は、おそらくプロファイリングしたくないでしょう。 そのため、cargo build; cargo clean -p $C のようなものが役立つ場合があります （ここで $C は crate 名です）
  • ただし、通常は代わりに touch src/lib.rs して再ビルドするだけです。=)
• インクリメンタルビルドがプロファイルに干渉するのは、おそらく望ましくないでしょう。 そのため、CARGO_INCREMENTAL=0 のようなものが役立ちます。

cargo から収集したデータを読み取るときに addr2line xxx/elf: could not read first record の問題を回避するには、 最新版の addr2line を使用する必要があるかもしれません:

cargo install addr2line --features="bin"

perf.rust-lang.org のテストから perf プロファイルを収集する

多くの場合、perf.rust-lang.org の特定のテストを分析したいことがあります。 それを行う最も簡単な方法は、rustc-perf ベンチマークスイートを 使用することです。この方法はこちらで説明されています。

ベンチマークスイートの CLI を使用する代わりに、ベンチマークを手動でプロファイリングすることもできます。まず、 rustc-perf リポジトリをクローンする必要があります:

$ git clone https://github.com/rust-lang/rustc-perf

次に、プロファイリングしたいテストのソースコードを見つけます。テストのソースは collector/compile-benchmarks ディレクトリと collector/runtime-benchmarks ディレクトリにあります。それでは、 特定のテストのディレクトリに移動しましょう。ここでは clap-rs を例として使用します:

cd collector/compile-benchmarks/clap-3.1.6

この場合、cargo check のパフォーマンスをプロファイリングしたいとします。 その場合、私はまず依存関係をビルドするためにいくつかの基本的なコマンドを実行します:

# セットアップ: まず古い結果をすべて削除し、依存関係をビルドします:
cargo +<toolchain> clean
CARGO_INCREMENTAL=0 cargo +<toolchain> check

（繰り返しになりますが、<toolchain> は最初の手順で作成したツールチェーンの名前に 置き換える必要があります。）

次に、cargo check を実行して、ちょうど clap-rs crate の実行時間を記録したいとします。 私はこれに cargo rustc を使うことが多いです。後で行うように、明示的なフラグを追加することも できるためです。

touch src/lib.rs
CARGO_INCREMENTAL=0 perf record -F99 --call-graph dwarf cargo rustc --profile check --lib

最後のコマンドに注意してください。これはかなり大がかりです！これは cargo rustc コマンドを使用しており、追加のオプションを付けて（可能性として）rustc を実行します。 --profile check と --lib オプションは、cargo check の実行を行っていること、 そしてこれがライブラリ（バイナリではない）であることを指定します。

この時点で、perf ツールを使用して結果を分析できます。たとえば:

perf report

これは対話型の TUI プログラムを開きます。単純なケースでは、これが役立つことがあります。 より詳細な調査には、perf-focus ツールが役立つ場合があります。これについては後述します。

注意事項。 rustc-perf の各テストは、それぞれ独自の特殊ケースです。 特に、その一部はライブラリではありません。その場合は touch src/main.rs を行い、 --lib を渡さないようにする必要があります。正直なところ、どのテストがどちらなのかを 見分ける最善の方法はよく分かりません。

NLL データの収集

NLL の実行をプロファイリングしたい場合は、次のように cargo rustc コマンドに 追加のオプションを渡すだけです:

touch src/lib.rs
CARGO_INCREMENTAL=0 perf record -F99 --call-graph dwarf cargo rustc --profile check --lib -- -Z borrowck=mir

perf focus による perf プロファイルの分析

perf プロファイルを収集したら、それに関する情報を取得したいところです。 このために、私は個人的に perf focus を使用しています。これはシンプルながら便利な ツールの一種で、次のようなクエリに答えることができます:

• 「関数 F でどれだけの時間が費やされたか」（どこから呼び出されたかに関係なく）
• 「関数 G から呼び出されたとき、関数 F でどれだけの時間が費やされたか」
• 「関数 G で費やされた時間を除外して、関数 F でどれだけの時間が費やされたか」
• 「F はどの関数を呼び出し、それらでどれだけの時間を費やしているか」

これがどのように機能するかを理解するには、perf について少しだけ知っておく必要があります。 基本的に、perf は定期的に（または何らかのイベントが発生したときに）プロセスを サンプリングすることで動作します。各サンプルについて、perf はバックトレースを収集します。 perf focus を使うと、そのバックトレースにどの関数が現れるかをテストする正規表現を 書くことができ、その正規表現に一致するバックトレースを持つサンプルが何パーセントあったかを 教えてくれます。おそらく、私が NLL パフォーマンスをどのように分析するかを順を追って説明するのが 最も分かりやすいでしょう。

perf-focus のインストール

cargo install を使って perf-focus をインストールできます:

cargo install perf-focus

例: MIR borrowck ではどれだけの時間が費やされているか？

あるテストについて NLL データを収集したとします。MIR 借用チェッカーで どれだけの時間が費やされているかを知りたいとします。MIR borrowck の「メイン」 関数は do_mir_borrowck と呼ばれているため、次のコマンドを実行できます:

$ perf focus '{do_mir_borrowck}'
Matcher    : {do_mir_borrowck}
Matches    : 228
Not Matches: 542
Percentage : 29%

'{do_mir_borrowck}' 引数は matcher と呼ばれます。これは、バックトレースに適用されるテストを指定します。この場合、{X} は、正規表現 X を満たす関数がバックトレース上に 何らか 存在しなければならないことを示します。この場合、その正規表現は、欲しい関数の名前そのものです（実際には、名前の一部です。完全な名前には、モジュールパスなど、ほかにも多くのものが含まれます）。このモードでは、perf-focus は、do_mir_borrowck がスタック上にあったサンプルの割合だけを出力します。この場合は 29% です。

c++filt に関する注意。 perf からデータを取得するために、perf focus は現在 perf script を実行しています（もっと良い方法があるかもしれません…）。ときどき、perf script が C++ のマングルされた名前を出力することがあります。これは厄介です。自分で perf script | head を実行すれば分かります。rustc::middle ではなく 5rustc6middle のような名前が見える場合、同じ問題が起きています。これは次のようにして解決できます。

perf script | c++filt | perf focus --from-stdin ...

これにより、perf script からの出力が c++filt にパイプされ、それらの名前の大半がより扱いやすい形式に変換されるはずです。perf focus の --from-stdin フラグは、perf focus を実行するのではなく、stdin からデータを取得するように指示します。これはもっと便利にすべきです（最悪の場合でも、perf focus に c++filt オプションを追加するか、単に常にそれを使うようにするかもしれません。かなり無害です）。

例: MIR borrowck は trait の解決にどれくらいの時間を費やしているか？

MIR borrowck が trait checker でどれくらいの時間を費やしているかを知りたいかもしれません。より複雑な正規表現を使って、これを問い合わせることができます。

$ perf focus '{do_mir_borrowck}..{^rustc::traits}'
Matcher    : {do_mir_borrowck},..{^rustc::traits}
Matches    : 12
Not Matches: 1311
Percentage : 0%

ここでは、.. 演算子を使って「スタック上に do_mir_borrowck があり、その後ろに、名前が rustc::traits で始まる何らかの関数がある頻度はどれくらいか？」を尋ねています（基本的には、そのモジュール内のコードです）。結果として、答えは「ほとんどない」です。その記述に当てはまるサンプルは 12 個だけです（サンプルが まったく 見つからない場合、多くの場合、クエリがおかしくなっていることを示します）。

興味があれば、--print-match オプションを使うことで、どのサンプルなのかを正確に調べることができます。これにより、各サンプルの完全なバックトレースが出力されます。行の先頭にある | は、正規表現がマッチした部分を示します。

例: MIR borrowck はどこで時間を費やしているか？

多くの場合、より「探索的」なクエリを実行したくなります。たとえば、MIR borrowck が時間の 29% を占めていることは分かっていますが、その時間はどこで費やされているのでしょうか？そのためには、--tree-callees オプションが最適なツールであることが多いです。通常は --tree-min-percent または --tree-max-depth も指定したくなります。結果は次のようになります。

$ perf focus '{do_mir_borrowck}' --tree-callees --tree-min-percent 3
Matcher    : {do_mir_borrowck}
Matches    : 577
Not Matches: 746
Percentage : 43%

Tree
| matched `{do_mir_borrowck}` (43% total, 0% self)
: | rustc_borrowck::nll::compute_regions (20% total, 0% self)
: : | rustc_borrowck::nll::type_check::type_check_internal (13% total, 0% self)
: : : | core::ops::function::FnOnce::call_once (5% total, 0% self)
: : : : | rustc_borrowck::nll::type_check::liveness::generate (5% total, 3% self)
: : : | <rustc_borrowck::nll::type_check::TypeVerifier<'a, 'b, 'tcx> as rustc::mir::visit::Visitor<'tcx>>::visit_mir (3% total, 0% self)
: | rustc::mir::visit::Visitor::visit_mir (8% total, 6% self)
: | <rustc_borrowck::MirBorrowckCtxt<'cx, 'tcx> as rustc_mir_dataflow::DataflowResultsConsumer<'cx, 'tcx>>::visit_statement_entry (5% total, 0% self)
: | rustc_mir_dataflow::do_dataflow (3% total, 0% self)

--tree-callees で起きることは次のとおりです。

• 正規表現にマッチする各サンプルを見つける
• 正規表現のマッチの 後 に現れるコードを見て、コールツリーを構築しようとする

--tree-min-percent 3 オプションは、「時間の 3% より多くを占めるものだけを表示してほしい」という意味です。これがないと、ツリーはしばしば非常にノイズが多くなり、malloc の内部のようなランダムなものが含まれます。--tree-max-depth も便利な場合があります。これは、出力する階層数を制限するだけです。

各行について、その関数全体での時間の割合（“total”）と、その関数だけに費やされ、その関数の何らかの callee には費やされていない時間の割合（self）を表示します。通常は “total” のほうが興味深い数値ですが、常にそうとは限りません。

相対的な割合

デフォルトでは、perf-focus におけるすべての割合は プログラム全体の実行 に対する相対値です。これは視点を保つのに役立ちます。多くの場合、ホットスポットを見つけるために掘り下げていくと、プログラム全体の実行という観点では、この「ホットスポット」は実際には重要ではないという事実を見失うことがあります。また、異なるクエリ間の割合を互いに簡単に比較できることも保証されます。

とはいえ、相対的な割合を取得すると便利な場合もあるため、perf focus は --relative オプションを提供しています。この場合、割合は、すべてのサンプルではなく、マッチしたサンプルだけについて表示されます。したがって、たとえば次のようにして、borrowck 自体に対する相対的な割合を取得できます。

$ perf focus '{do_mir_borrowck}' --tree-callees --relative --tree-max-depth 1 --tree-min-percent 5
Matcher    : {do_mir_borrowck}
Matches    : 577
Not Matches: 746
Percentage : 100%

Tree
| matched `{do_mir_borrowck}` (100% total, 0% self)
: | rustc_borrowck::nll::compute_regions (47% total, 0% self) [...]
: | rustc::mir::visit::Visitor::visit_mir (19% total, 15% self) [...]
: | <rustc_borrowck::MirBorrowckCtxt<'cx, 'tcx> as rustc_mir_dataflow::DataflowResultsConsumer<'cx, 'tcx>>::visit_statement_entry (13% total, 0% self) [...]
: | rustc_mir_dataflow::do_dataflow (8% total, 1% self) [...]

ここでは、compute_regions が “47% total” として現れていることが分かります。これは、do_mir_borrowck の 47% がその関数で費やされていることを意味します。以前は 20% でした。これは、do_mir_borrowck 自体が合計時間の 43% にすぎないためです（そして .47 * .43 = .20）。

Windows でのプロファイリング

WPR と WPA の紹介

高レベルのパフォーマンス分析（メモリ使用量を含む）は、Windows Performance Recorder (WPR) と Windows Performance Analyzer (WPA) を使って実行できます。 名前が示すとおり、WPR はシステム統計情報（イベント トレース ログ、別名 ETL ファイルの形式）を記録するためのものであり、WPA はこれらの ETL ファイルを分析するためのものです。

WPR はシステム全体の統計情報を収集するため、rustc に関連するものだけでなく、 そのマシン上で実行されている他のすべてのものも記録します。 分析中に、関心のあるものだけにフィルタリングできます。

これらのツールは非常に強力ですが、Rust コンパイラをうまくプロファイリングできるようになるには、 少し学習も必要です。

ここでは、Rust コンパイラを分析するために WPR と WPA を使用する方法を見ていくとともに、 rustc の分析を容易にするよう特別に設計された有用な「プロファイル」（つまり、WPR と WPA のデフォルトを調整する設定ファイル）へのリンクも提供します。

WPR と WPA のインストール

WPR と WPA は、Windows Assessment and Deployment Kit (ADK) のダウンロード時に選択できる Windows Performance Toolkit の一部としてインストールできます。 ADK インストーラーは こちらからダウンロードできます。 Windows Performance Toolkit を必ず選択してください（他には何も選択する必要はありません）。

記録

システム分析を実行するには、まず WPR でシステムを記録する必要があります。 WPR を開き、ウィンドウの下部で記録したいものの「プロファイル」を選択します。 rustc のブートストラップ プロセスのメモリ使用量を調べる場合は、以下の項目を選択します。

• CPU 使用率
• VirtualAlloc 使用状況

「Heap usage」も記録したくなるかもしれませんが、これはヒープ割り当てを 1 つ残らず記録するため、 非常に、非常に高コストになる可能性があります。 高レベルの分析では、これはオフのままにしておくのが最善かもしれません。

次に、記録するためのセットアップを準備する必要があります。 メモリ使用量の分析では、デバッグ シンボル付きの stage 1 コンパイラ ビルドを使って stage 2 コンパイラ ビルドを記録するのが最善です。 rustc のビルドに使用しているコンパイラにシンボルがあると、WPA が Rust のシンボルを正しく解決できるため、 分析に大いに役立ちます。 残念ながら、stage 0 コンパイラではシンボルが有効になっていないため、 stage 1 コンパイラをビルドし、 続いて stage 2 コンパイラを自分でビルドする必要があります。

これを行うには、bootstrap.toml ファイルで rust.debuginfo-level = 1 を設定していることを確認してください。 これにより、ブートストラップ時にスタック フレームを含むデバッグ情報を生成するよう rustc に指示します。

これで stage 1 コンパイラをビルドできます: x build --stage 1 -i library、または stage 1 コンパイラをビルドしたい他の任意の方法でビルドしてください。

stage 1 コンパイラがビルドできたので、stage 2 ビルドを記録できます。 WPR に戻り、 「start」ボタンをクリックして stage 2 コンパイラをビルドします（例: x build --stage=2 -i library）。 このプロセスが完了したら、記録を停止します。

Save ボタンをクリックし、そのプロセスが完了したら、表示される「Open in WPA」ボタンをクリックします。

注: トレース ファイルはかなり大きいため、WPA がファイルを開き終えるまでに少し時間がかかることがあります。

分析

ETL ファイルが WPA で開かれたので、結果を分析できます。 まず、rustc のブートストラップ分析に適した状態に WPA を設定する、 事前作成済みの「プロファイル」を適用します。 プロファイルはこちらからダウンロードしてください。 上部の「Profiles」メニューを選択し、次に「apply」を選択して、ダウンロードしたプロファイルを選択します。

次のようなものが表示されるはずです。

次に、Rust のスタック トレースを適切にデマングルできるように、デバッグ シンボルを読み込んで処理するよう WPA に指示する必要があります。 これを行うには、「Trace」をクリックしてから「Load Symbols」を選択します。 この手順には時間がかかることがあります。

WPA が rustc のシンボルを読み込んだら、rustc.exe ノードを展開し、割り当てが最も大きいスタックを掘り下げていけます。

そのためには、「Commit Stack」列の [Root] ノードを展開し、興味深いスタック フレームが見つかるまで 展開を続けます。

ヒント: 展開したいノードを選択した後、右矢印キーを押します。これによりそのノードが展開され、 展開された集合内で次に大きいノードに選択が移動します。 興味深いフレームに到達するまで、右矢印キーを押し続けることができます。

このサンプルでは、このプロファイル全体を通して、codegen 経由の呼び出しが合計で約 30GB のメモリを割り当てていることがわかります。

その他の分析タブ

このプロファイルには、役立つ可能性のある他のタブもいくつか含まれています。

• System Configuration
  • キャプチャが記録されたシステムに関する一般情報。
• rustc Build Processes
  • rustc.exe、cargo.exe、link.exe などの関連プロセスのフラットな一覧。
  • 各プロセスには、そのコマンドライン引数が表示されます。
  • 特定の rustc プロセスが何に取り組んでいたかを把握するのに役立ちます。
• rustc Build Process Tree
  • プロセスがいつ開始し終了したかを示すタイムライン。
• rustc CPU Analysis
  • rustc のホットスポットを表示するように事前設定されたチャートが含まれています。
  • これらのチャートは、rustc がどこで時間を費やしているかを分析することを支援するよう設計されています。
• rustc Memory Analysis
  • rustc がどこでメモリを割り当てているかを表示するように事前設定されたチャートが含まれています。

rustc-perf によるプロファイリング

Rust benchmark suite は、Rust コンパイラをプロファイリングおよびベンチマークするための包括的な方法を提供します。 このスイートの使用方法については、そのマニュアルに手順があります。

ただし、このスイートを手動で使用するのは少し面倒な場合があります。 rustc コントリビューターがこれをより簡単に使えるようにするため、 コンパイラビルドシステム（bootstrap）もベンチマークスイートとの組み込み連携を提供しており、 スイートのダウンロードとビルド、ローカルのコンパイラツールチェーンのビルドを行い、簡略化されたコマンドラインインターフェイスを使用してそれをプロファイリングできるようにします。

この連携を使用するには、./x perf <command> [options] コマンドを使用できます。

このコマンドには、たとえば --stage 1 や --stage 2 などの通常の bootstrap フラグを使用して、作成される sysroot のステージを変更できます。また、プロファイリングをより適切にサポートするために bootstrap.toml を設定すると役立つ場合があります。たとえば、ビルドされたコンパイラにソース行情報を追加するには rust.debuginfo-level = 1 を設定します。

x perf は現在、次のコマンドをサポートしています。

• benchmark <id>: コンパイラのベンチマークを実行し、結果を渡された id の下に保存します。
• compare <baseline> <modified>: 渡された 2 つの id を持つ 2 つのコンパイラのベンチマーク結果を比較します。
• eprintln: コンパイラを実行し、その stderr 出力をキャプチャするだけです。 コンパイラは通常、stderr に何も出力しないことに注意してください。 そのため、何らかの出力を得るには eprintln! 呼び出しをいくつか追加するとよいかもしれません。
• samply: samply サンプリングプロファイラを使用してコンパイラをプロファイリングします。
• cachegrind: Cachegrind を使用して、コンパイラ実行の詳細なシミュレーショントレースを生成します。

プロファイラのより詳細な説明は、rustc-perf マニュアルにあります。

x perf コマンドには、次のオプションを使用できます。これらは、このスイートで使用できる profile_local コマンドおよび bench_local コマンドの対応するオプションを反映しています。

• --include: プロファイリングまたはベンチマークすべきベンチマークを選択します。
• --profiles: プロファイリングまたはベンチマークすべきプロファイル（Check, Debug, Opt, Doc）を選択します。
• --scenarios: プロファイリングまたはベンチマークすべきシナリオ（Full, IncrFull, IncrPatched, IncrUnchanged）を選択します。

外部クレート向けプロファイリング差分の例

外部クレートに対して、コンパイラの 2 つのコミットのローカル差分を生成することに関心があるかもしれません。 まず、rustc-perf リポジトリで、Rust コンパイラのベンチマークを実行する collector を次のようにビルドします。

cargo build --release -p collector

その後、collector バイナリを指定して、cargo を使用して collector を実行できます。 これは次の引数を想定しています。

• <PROFILE>: パフォーマンスをどのように測定すべきかを表すプロファイラの選択。 この例では、Cachegrind を使用します。
• <RUSTC>: ベンチマーク対象の Rust コンパイラのリビジョンで、rust-lang/rust のコミット SHA として指定します。 任意引数により、上記のようにプロファイルとシナリオを実行できます。 必須引数および任意引数に関する詳細は、rustc-perf-readme-profilers にあります。

次に、rust-lang/rust リポジトリの 2 つのコミット <SHA1> と <SHA2> について、クレート serve_derive-1.0.136 のプロファイル差分を生成する場合は、 rustc-perf リポジトリで次を実行します。

cargo run --release --bin collector profile_local cachegrind +<SHA1> --rustc2 +<SHA2> --exact-match serde_derive-1.0.136 --profiles Check --scenarios IncrUnchanged

crates.io の依存関係

Rust コンパイラは、crates.io から取得した一部の依存関係を用いたビルドをサポートしています。

Rust Forge には、新しい依存関係を精査するための公式ポリシーがあります。

許可されている依存関係

tidy ツールには、許可されているクレートのリストがあります。 コンパイラにまだ含まれていない依存関係を追加するには、そのリストに追加する必要があります。

コントリビューション手順

バグ報告

バグは残念なものですが、ソフトウェアにおける現実です。 私たちは把握していないものを修正することはできないため、どうぞ積極的に報告してください。 何かがバグかどうか確信が持てない場合でも、遠慮なく issue を開いてください。

バグを公開で報告することが Rust ユーザーに対するセキュリティリスクになると考えられる場合は、 セキュリティ脆弱性を報告するための手順に従ってください。

nightly チャンネルを使用している場合は、バグを報告する前に、そのバグが 最新のツールチェーンにも存在するか確認してください。 すでに修正されている可能性があります。

可能であれば、バグを報告する前に [search existing issues] を行ってください。 他の誰かがすでにそのエラーを報告している可能性があるためです。 これは常にうまくいくとは限らず、何を検索すればよいか分かりにくい場合もあるため、 追加で行うとよいこと程度に考えてください。 誤って重複した報告を作成してしまっても問題ありません。

同様に、そのバグに遭遇した他の人があなたの issue を見つけやすくするために、 そのバグに固有である可能性のある情報を含む、説明的なタイトルで issue を作成することを検討してください。 それは、使用している言語機能またはコンパイラ機能、 バグを引き起こす条件、またはエラーメッセージがある場合はその一部などです。 例としては、戻り位置の impl Trait のライフタイム推論における “impossible case reached” が考えられます。

issue を開くには、[このリンク][create an issue]をたどり、提供されている適切なテンプレート内の フィールドに記入するだけです。

バグ修正または「通常の」コード変更

ほとんどの PR では、特別な手順は必要ありません。 単に open a PR すれば、それがレビューされ、承認され、マージされます。 これには、ほとんどのバグ修正、リファクタリング、その他のユーザーから見えない変更が含まれます。 次のいくつかのセクションでは、このルールの例外について説明します。

また、WIP PR や GitHub の Draft PRs を開くことはまったく問題ないことにも注意してください。 進めながらフィードバックを得たり、 共同作業者とコードを共有したりするために、これを好む人もいます。 また、PR のビルドとテストに CI を利用できるようにするためにこれを行う人もいます（たとえば、遅いマシンで開発している場合）。

新機能

Rust には強力な後方互換性の保証があります。 したがって、新機能を stable Rust に直接実装することはできません。 代わりに、stable、beta、nightly という 3 つのリリースチャンネルがあります。 Rust のトレインリリースモデルの詳細については、The Rust Book を参照してください。

• Stable: 一般的な利用向けの最新の安定版リリースです。
• Beta: 次のリリースです（6 週間以内に stable になります）。
• Nightly: リポジトリの main ブランチに従います。 これは、不安定な機能の利用が想定されている唯一のチャンネルであり、 その利用はオプトインの feature gate を通じて行われます。

詳細については、新機能の実装に関するこの章を参照してください。

破壊的変更

破壊的変更には、dev-guide 内に[専用のセクション][Breaking Changes]があります。

大規模な変更

コンパイラチームには、破壊的変更を引き起こすかどうかにかかわらず、大きな変更のための特別なプロセスがあります。 このプロセスは Major Change Proposal (MCP) と呼ばれます。 MCP は、コンパイラに対する大きな変更についてフィードバックを得るための、 比較的軽量な仕組みです（完全な RFC や、チームとの設計ミーティングとは対照的なものです）。

MCP が必要となる可能性のあるものの例には、大規模なリファクタリング、 重要な型への変更、コンパイラが何かを行う方法への重要な変更、 または小規模なユーザー向け変更が含まれます。

迷った場合は、on Zulip で質問してください。 最終的にマージされない PR に多くの労力を費やすのは 残念なことです！ MCP の詳細については、このドキュメントを参照してください。

パフォーマンス

コンパイラのパフォーマンスは重要です。 私たちはここ数年、それを徐々に改善することに多くの労力を注いできました。

あなたの変更がパフォーマンスの低下（または改善）を引き起こす可能性があると考えられる場合は、 “perf run” をリクエストできます（また、レビュアーも承認前にこれをリクエストする場合があります）。 これは、あなたの変更を含むコンパイラで ベンチマーク群をコンパイルする、さらに別のボットです。 数値はこちらに報告され、 あなたの変更を最新の main と比較して確認できます。

rustc 開発にも役立つ、一般的な Rust コードのパフォーマンス入門については、 The Rust Performance Book を参照してください。

プルリクエスト

プルリクエスト（略して PR）は、Rust を変更するために私たちが使用する主要な仕組みです。 GitHub 自体にも、Pull Request 機能の使用方法に関する優れたドキュメントがあります。 私たちは “fork and pull” モデルを使用しています。 このモデルでは、コントリビューターが自分の個人用 fork に変更を push し、プルリクエストを作成して それらの変更をソースリポジトリに取り込みます。 Rust へのコントリビューション時に Git を使用する方法についての章があります。

潜在的に大規模、複雑、横断的、かつ/または非常にドメイン固有な変更に関する助言

ローテーション中のコンパイラレビュアーは通常、それぞれがよく知っているコンパイラの領域を持っていますが、 あまり詳しくない領域もあります。あなたの PR に大規模、複雑、横断的、かつ/または非常にドメイン固有な変更が含まれている場合、 そのような PR のすべての変更を安心してレビューできる適切なレビュアーを見つけることは非常に困難になります。 これは、変更がコンパイラ固有のものだけでなく、標準ライブラリチームのような他チームのレビュアーの管轄に属する変更も含む場合にも当てはまります。 変更されたファイルに基づいて、関連するチームに通知し、特定のアラートを設定している人に ping する bot があります。

そのような変更を行う前に、提案する変更について事前にコンパイラチームと話し合うこと（および、その変更に承認が必要となる他のチームとも話し合うこと）を強く推奨します。また、コンパイラチームと協力して、潜在的にレビュー不能な大規模 PR を、個別にレビューしやすいより小さな PR の連続に分割できるかを検討してください。

提案する変更について話し合うには、Zulip に #t-compiler スレッドを作成してコンパイラチームと連絡を取ることができます。

事前にコンパイラチームと連絡を取ることは、いくつかの点で役立ちます。

1. PR が適時にレビューされる可能性が高まります。
   • 実際の PR を開く前に適切なレビュアーを特定する手助けをしたり、変更手続きを進めるためのアドバイザーやリエゾンを見つける手助けをしたり、必要に応じて try-job、perf 実行、crater 実行を行う手助けをしたりできます。
2. コンパイラチームがあなたの変更を追跡しやすくなります。
3. コンパイラチームは、変更の方向性がコンパイラチームの望む方向と一致しているかを確認するために、早い段階から頻繁にあなたの変更の感触を確認できます。
4. コンパイラチームが受け入れる意思のない大規模な変更に多大な時間と労力を費やしてしまう状況や、変更がコンパイラチームの同意しない方向であることに非常に遅い段階で気付く状況を避けるのに役立ちます。

ブランチを最新に保つ

rust-lang/rust の CI は、あなたのパッチを、ブランチの基点となっているコミットではなく、現在の main に対して直接適用します。 これにより、明示的なマージコンフリクトがない場合でも、 ブランチが古くなっていると予期しない失敗につながることがあります。

ブランチを更新するのは必要な場合だけにしてください。つまり、マージコンフリクトがある場合、上流の CI が壊れていてグリーンな PR を妨げている場合、またはメンテナーから要求された場合です。 必要がない限り、レビュー中のすでにグリーンな PR を更新することは避けてください。 レビュー中は、フィードバックに対応するためにインクリメンタルなコミットを作成してください。 squash や rebase は最後に行うか、レビュアーから要求された場合に行うことを推奨します。

更新する際は、git push --force-with-lease を使用し、何が変わったかを説明する簡潔なコメントを残してください。 一部のリポジトリでは、rebase の代わりに upstream/main からのマージを好みます。 プロジェクトの慣例に従ってください。 詳細な手順については、最新状態を保つを参照してください。

rebase 後は、CI が実行される前に問題を検出するために、関連するテストをローカルで実行することを推奨します。

r?

すべてのプルリクエストは別の人によってレビューされます。 @rustbot という bot があり、変更したファイルに基づいて、あなたのリクエストをレビューするランダムな人を自動的に割り当てます。

特定の人にプルリクエストのレビューを依頼したい場合は、 プルリクエストの説明またはコメントに r? を追加できます。 たとえば、@awesome-reviewer にレビューを依頼したい場合は、 プルリクエストの説明の末尾に次の内容を追加します。

r? @awesome-reviewer

すると、@rustbot はランダムな人ではなく、そのレビュアーに PR を割り当てます。 これは完全に任意です。

r? rust-lang/groupname と書くことで、特定のチームからランダムなレビュアーを割り当てることもできます。 例として、診断の変更を行っている場合は、 次の内容を追加することで診断チームからレビュアーを得ることができます。

r? rust-lang/diagnostics

指定可能な groupname の完全な一覧については、 [triagebot.toml 設定ファイル]の adhoc_groups セクション、 または [rust-lang チームデータベース]のチーム一覧を確認してください。

レビューを待つ

注記

プルリクエストのレビュアーは、多くの場合、作業量が上限に達しており、 その多くはボランティアとして貢献しています。 レビューの遅延を最小限に抑えるため、 プルリクエストの作成者と割り当てられたレビュアーは、レビューラベル （S-waiting-on-review と S-waiting-on-author）が最新に保たれるようにし、 適切なタイミングで次のコマンドを呼び出すべきです。

• @rustbot author: レビューは完了しており、 PR 作成者はコメントを確認し、それに応じて対応するべきです。

• @rustbot review: 作成者はレビューの準備ができており、 この PR はレビュアーのキューに再度入れられます。

レビュアーは人間であり、そのほとんどは空き時間に rustc に取り組んでいることに注意してください。 つまり、応答して PR をレビューするまでに時間がかかることがあります。 また、レビュアーが割り当てられた一部の PR を見逃す可能性もあるということです。

PR を前進させるために、Triage WG はレビュー待ちで、少なくとも 2 週間議論されていないすべての PR を定期的に確認しています。 2 週間以内にレビューを受けられない場合は、Zulip の #t-release/triage で Triage WG に遠慮なく尋ねてください。 彼らは、いつ ping すべきか、誰が休暇中かもしれないか、などを把握しています。

レビュアーは GitHub のコードレビューインターフェイスを使用して、いくつかの変更を要求することがあります。 一部の PR については、特別な手続きを要求することもあります。 そのような手続きの例については、Crater と [Breaking Changes] の章を参照してください。

CI

人間によるレビューに加えて、プルリクエストは継続的インテグレーション（CI）によって自動的にテストされます。 基本的に、プルリクエストを開いたり更新したりするたびに、 CI はコンパイラをビルドし、[compiler test suite] に対してテストし、さらにプルリクエストが Rust のスタイルガイドラインに準拠していることの確認など、他のテストも実行します。

継続的インテグレーションテストを実行することで、PR 作成者は最初のレビューサイクルを経ることなく早期にミスを発見でき、またレビュアーが特定のプルリクエストの状態を把握し続ける助けにもなります。 Rust には十分な CI キャパシティがあり、変更を push するたびに 計算リソースを無駄にすることを心配する必要はまったくありません。 また、生産性の向上に役立つのであれば、変更のテストに CI を使うことも まったく問題ありません（むしろ推奨されています！）。 特に、完全な ./x test スイートをローカルで実行することは推奨していません。 実行に非常に長い時間がかかるためです。 Rust の CI を使って変更をテストする方法については、Testing with CI の章を参照してください。

r+

誰かがあなたのプルリクエストをレビューした後、その人はプルリクエストに r+ という注釈を残します。 これは次のような見た目です。

@bors r+

これは、私たちの頼れるインテグレーションボットである @bors に、 あなたのプルリクエストが承認されたことを伝えます。 その後 PR は [merge queue] に入り、そこで @bors が 私たちのサポートするすべてのプラットフォームですべてのテストを実行します。 すべてうまくいけば、@bors はあなたのコードを main にマージし、プルリクエストを閉じます。

変更の規模によっては、少し異なる形式の r+ を目にすることがあります。

@bors r+ rollup

追加の rollup は、この変更を常に「ロールアップ」するべきであることを @bors に伝えます。 ロールアップされる変更は、処理を高速化するために、他の PR と一緒にテストおよびマージされます。 通常、互いに競合しないと見込まれる小さな変更だけが 「常にロールアップ」としてマークされます。

辛抱強く待ってください。 これには時間がかかる場合があり、キューが長くなることもあります。 また、PR が手動でマージされることは決してない点にも注意してください。

Opening a PR

これでプルリクエスト（PR）を提出する準備ができましたか？ すばらしいです！ 知っておくべき点がいくつかあります。

すべてのプルリクエストは、別のブランチを対象にすべきだと確実に分かっている場合を除き、 main ブランチに対して提出する必要があります。

PR を送信する前に、いくつかのスタイルチェックを実行してください。

./x test tidy --bless

このチェックは、すべてのプルリクエストの前に（またプルリクエスト内のすべての新しいコミットの前にも） 実行することを推奨します。 このチェックを忘れないように、push の前に [git hooks] を追加できます。 CI でも tidy が実行され、tidy が失敗すると CI も失敗します。

Rust は no merge-commit policy に従っています。 これは、マージコンフリクトに遭遇した場合、 マージではなく常にリベースすることが求められるという意味です。 たとえば、main ブランチの最新の変更を自分の feature ブランチに取り込むときは、 常に rebase を使用してください。 PR にマージコミットが含まれている場合、has-merge-commits としてマークされます。 たとえばインタラクティブリベースによってマージコミットを削除したら、再度そのラベルを 削除する必要があります。

@rustbot label -has-merge-commits

詳細については、この章を参照してください。

マージコンフリクトに遭遇した場合、またはレビュー担当者から何らかの 変更を求められた場合、PR は S-waiting-on-author としてマークされます。 それらを解決したら、@rustbot を使って S-waiting-on-review としてマークする必要があります。

@rustbot ready

GitHub では キーワードを使って issue を閉じることができます。 この機能は issue トラッカーを整然と保つために使用するべきです。 ただし、一般的には、 “closes #123” というテキストはコミットメッセージではなく PR の説明に入れることが好まれます。 特にリベース中に、コミット内で issue 番号を引用すると、該当する issue に 「スパム」を送ることになり得ます。

ただし、PR が stable-to-beta または stable-to-stable のリグレッションを修正し、 beta および/または stable へのバックポートが承認されている場合（つまり beta-accepted および/または stable-accepted としてマークされている場合）は、そのようなキーワードを 使用しないでください。修正が main に入った時点で、対応する issue が自動的に閉じられることを 望まないためです。 issue についてはどこかで言及したまま、PR の説明を更新してください。 たとえば、Fixes (after beta backport) #NNN. と書くことができます。

追加の対応として、タイトルが [beta] または [stable] で始まり、 対象の PR をバックポートする PR に十分注意してください。 その PR がマージされたら、関連する issue を閉じることができます。 閉じるコメントでは、関係したすべての PR に言及する必要があります。 issue を閉じる権限がない場合は、 元の PR にコメントを残し、レビュー担当者に代わりに閉じてもらうよう依頼してください。

Reverting a PR

PR が誤コンパイル、重大なパフォーマンスリグレッション、またはその他の重大な問題を引き起こす場合、 その PR をリグレッションテストケースとともに revert したいことがあります。 Forge docs の revert policy も確認できます （主にレビュー担当者向けですが、PR 作成者にとっても有用な情報が含まれています）。

PR に巨大な変更が含まれている場合、revert が難しくなり、その後の更新で インクリメンタルな修正をレビューすることが難しくなる場合があります。 また、その PR 内の特定のコードが後続の PR に大きく依存されている場合、 それを revert することが難しくなることがあります。

そのような場合は、#128271 に示されているように、問題のあるコードを特定し、一部の入力に対して無効化できます。

MIR 最適化については、#132356 に示されているように、 -Zunsound-mir-opt オプションを使って mir-opt をゲートすることもできます。

External dependencies

このセクションは “Using External Repositories” に移動しました。

Writing documentation

ドキュメントの改善は大歓迎です。 doc.rust-lang.org のソースは ツリー内の src/doc にあり、標準 API ドキュメントは ソースコード自体から生成されます（例: library/std/src/lib.rs）。ドキュメントのプルリクエストは、 他のプルリクエストと同じように機能します。

ドキュメント関連の issue を見つけるには、[A-docs label] を使用してください。

ドキュメントのスタイルガイドラインは [RFC 1574] にあります。

標準ライブラリのドキュメントをビルドするには、x doc --stage 1 library --open を使用します。 書籍（例: unstable book）のドキュメントをビルドするには、x doc src/doc/unstable-book. を使用します。 結果は build/host/doc に表示され、同時にデフォルトブラウザーで自動的に開かれるはずです。 詳細については、Building Documentation を参照してください。

小さな修正を確認するために、rustdoc を直接使用することもできます。 たとえば、rustdoc src/doc/reference.md は reference を doc/reference.html にレンダリングします。 CSS は乱れるかもしれませんが、HTML が正しいことは確認できます。

内部ドキュメントに対するタイポグラフィやスペルチェックの修正は受け付けていないことに注意してください。 通常、それは変更の churn やレビュー時間に見合わないためです。 内部ドキュメントの例としては、コードコメントや rustc api docs があります。 ただし、同じ PR 内の他の改善に伴う場合は、それらを修正しても構いません。

Contributing to rustc-dev-guide

Contributions to the [rustc-dev-guide] はいつでも歓迎されており、 [rust-lang/rustc-dev-guide リポジトリ][rdgrepo]で直接行うことができます。 そのリポジトリの issue tracker も、やるべきことを見つけるのに最適な方法です。 初心者向けの issue も、高度なコンパイラ開発者向けの issue もあります！

覚えておいてほしいことがいくつかあります：

• 過度に長い行はできるだけ避け、意味的な改行（各文の後で行を改行すること）を使用してください。 行の長さに厳密な制限はありません。 文または文の一部が、同じ行で自然な終わりまで続くようにしてください。

  これを支援するために、ci/sembr にあるツールを使用できます。 そのヘルプ出力は、次のコマンドで確認できます：

  cargo run --manifest-path ci/sembr/Cargo.toml -- --help
  

• ガイドにテキストをコントリビュートする場合は、何らかの期間 および/または理由を添えて情報に文脈を与え、読者がその情報をどの程度信頼すべきか分かるようにしてください。 適切な量の文脈を提供することを目指してください。たとえば、以下を含めることが考えられますが、これらに限定されません：

  • テキストが古くなっている可能性がある理由として、「変更」以外のもの。 変更はプロジェクト全体で常に起こるものだからです。

  • コメントが追加された日付。たとえば、「現在、…」 や 「現時点では、…」 と書く代わりに、次のいずれかの形式で日付を追加することを検討してください：

    • Jan 2021
    • January 2021
    • jan 2021
    • january 2021

    .github/workflows/date-check.yml には CI アクションがあり、 6 か月を超えているものを示す月次レポートを生成します （例）。

    アクションが日付を拾えるようにするには、日付を指定する前に特別なアノテーションを追加します：

    <!-- date-check --> Nov 2025
    

    例：

    As of <!-- date-check --> Nov 2025, the foo did the bar.
    

    日付を表示されるレンダリング結果の一部にすべきでない場合は、 代わりに次を使用してください：

    <!-- date-check: Nov 2025 -->
    

  • 関連する WG、tracking issue、rustc rustdoc ページ、または類似のものへのリンク。 変更プロセスの詳しい説明や、その情報が古くなっていないことを検証する方法を提供している可能性があります。

• テキストがかなり長くなった場合（数回ページスクロールする量を超える）や、複雑になった場合（4 つを超える サブセクションがある場合）は、先頭に目次を置くとよいかもしれません。 先頭に <!-- toc --> マーカーを含めることで自動生成できます。

⚠️ 注: rustc-dev-guide の変更をどこにコントリビュートするか

rustc-dev-guide の変更をどこにコントリビュートするか、およびそうすることの利点についての詳細は、 rustc-dev-guide チームのドキュメントを参照してください。

Issue トリアージ

https://forge.rust-lang.org/release/issue-triaging.html を参照してください。

rfcbot ラベル

rfcbot は、変更を承認または却下するなど、非同期の意思決定を調整するプロセスを追跡するために 独自のラベルを使用します。 これは RFCs、issue、pull request に使用されます。

役立つリンクと情報

このセクションは [“このガイドについて”] の章に移動しました。 [“About this guide”]: about-this-guide.md#other-places-to-find-information [search existing issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue [Breaking Changes]: bug-fix-procedure.md [triagebot.toml config file]: https://github.com/rust-lang/rust/blob/HEAD/triagebot.toml [rust-lang teams database]: https://github.com/rust-lang/team/tree/HEAD/teams [compiler test suite]: tests/intro.md [merge queue]: https://bors.rust-lang.org/queue/rust [git hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks [A-docs label]: https://github.com/rust-lang/rust/issues?q=is%3Aopen%20is%3Aissue%20label%3AA-docs [RFC 1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text [rustc-dev-guide]: https://rustc-dev-guide.rust-lang.org/ [rdgrepo]: https://github.com/rust-lang/rustc-dev-guide [create an issue]: https://github.com/rust-lang/rust/issues/new/choose

コンパイラーチームについて

注記: チームについての詳細は Forge 上 に多く存在しており、以下の大半は古くなっています。

rustc は Rust コンパイラーチームによって保守されています。 このチームに所属する人々は、共同でリグレッションの追跡や新機能の実装に取り組んでいます。 Rust コンパイラーチームのメンバーは、rustc とその設計に対して重要な貢献を行ってきた人々です。

議論

現在、コンパイラーチームは Zulip でチャットしています。

• チームチャットは Zulip インスタンス上の t-compiler ストリームで行われます
• 関連する Zulip チャンネルも他にいくつかあります。 たとえば t-compiler/help では rustc 開発について助けを求めることができ、 t-compiler/meetings ではチームが週次のトリアージミーティングと運営ミーティングを行っています。

レビュアー

コンパイラーの特定の部分について誰が質問に答えられるのかを知りたい場合や、単に誰が何に取り組んでいるのかを知りたい場合は、 triagebot.toml の assign セクションを確認してください。 そこには、コンパイラーのさまざまな部分と、それぞれの部分のレビュアーである人々の一覧が含まれています。

Rust コンパイラーミーティング

コンパイラーチームには週次ミーティングがあり、そこでトリアージを行い、 一般に新しいバグやリグレッションを把握し、重要な事柄全般について議論するよう努めています。 ミーティングは Zulip で開催されます。 おおよそ次のように進行します。

• お知らせ、MCP/FCP、WG チェックイン: チームの残りのメンバーに対して、 全員に知っておいてほしい重要な事柄についていくつかのお知らせを共有します。 また、MCP と FCP の状況も共有し、 いくつかの WG から作業状況の更新を聞く機会としても使います。
• beta および stable へのノミネーションの確認: これらは、それぞれ beta と stable に バックポートするもののノミネーションです。 その後、実際に使われている、以前は動作していたコードをコンパイラーが壊した新しいケースを探します。 リグレッションは修正すべき重要な問題であるため、 P-critical または P-high としてタグ付けされている可能性があります。主な例外は バグ修正です（ただしその場合でも、私たちは多くの場合 まず警告を出すことを目指します）。
• P-critical および P-high のバグのレビュー: P-critical および P-high のバグは、 私たちが進捗を能動的に追跡するのに十分重要なものです。 P-critical および P-high のバグには、理想的には常に担当者がいるべきです。
• S-waiting-on-t-compiler および I-compiler-nominated issue の確認: これらは、 チームからのフィードバックが求められている issue です。
• パフォーマンストリアージレポートの確認: パフォーマンスを悪化させた PR を確認し、 パフォーマンスリグレッションを revert する価値があるのか、それとも そのリグレッションを将来の PR で対処できるのかを判断しようとします。

現在、ミーティングは木曜日のボストン時間午前 10 時に行われています （通常は UTC-4 ですが、サマータイムによって複雑になることがあります）。

チームメンバーシップ

Rust チームのメンバーシップは通常、ある人がしばらくの間 コンパイラーに対して重要な貢献を行ってきたときに提供されます。 メンバーシップは承認であると同時に義務でもあります。 コンパイラーチームのメンバーには、一般にレビューやその他の作業を行うだけでなく、 維持管理を手助けすることも期待されます。

コンパイラーチームのメンバーになることに関心がある場合、最初に行うべきことは、 いくつかのバグ修正を始めるか、ワーキンググループに参加することです。 バグを見つけるよい方法の 1 つは、 E-easy がタグ付けされた未解決の issue または E-mentor を探すことです。

また、非アクティブのため close された PR の墓場を掘り起こすこともできます。 その中には、まだ有用な作業が含まれているものがあるかもしれません。関連する issue があれば参照してください。 そして、元の作者に時間がなかったために、仕上げだけが必要な場合もあります。

r+ 権限

rustc に対して個別の PR をいくつか作成した後、私たちはしばしば r+ 権限を提供します。 これは、PR をマージするように 「bors」（どの PR を rustc に取り込むかを管理するロボット）へ指示する権利があることを意味します （bors とやり取りする方法についての説明はこちら）。

レビュアー向けのガイドラインは次のとおりです。

• 誰に割り当てられているかに関係なく、どの PR でもいつでもレビューしてかまいません。 ただし、次の場合を除き、PR に r+ しないでください。
  • コードのその部分に自信がある。
  • 他の誰も先にレビューしたいと思っていないと確信している。
    • たとえば、特にデリケートな部分のコードに触れているなどの理由で、 PR が取り込まれる前にレビューしたいという希望を表明する人がいることがあります。
• レビューするときは常に礼儀正しくしてください。あなたは Rust プロジェクトの代表者であるため、行動規範に関しては 期待を上回る対応をすることが求められます。

レビュアーローテーション

r+ 権限を持つと、レビュアーローテーションに追加されることもできます。 triagebot は、受信した PR をレビュアーに自動的に割り当てる bot です。 追加された場合、PR のレビュー担当としてランダムに選ばれます。 自分に割り当てられた PR をレビューすることに不安がある場合は、 r? @so-and-so のようなコメントを残して、他の誰かに割り当てることもできます。 誰に依頼すればよいかわからない場合は、単に r? @nikomatsakis for reassignment と書けば、@nikomatsakis があなたのために誰かを選びます。

レビュアーローテーションに加わることは、私たち全員のレビュー負担を軽減するため、とてもありがたいことです。 ただし、PR に対してタイムリーなフィードバックを人々に返す時間がない場合は、 リストに加わらないほうがよいかもしれません。

Git の使用

Rust プロジェクトでは、ソースコードの管理に Git を使用しています。 コントリビュートするには、自分の変更をコンパイラに取り込めるようにするため、 Git の機能にある程度慣れている必要があります。

このページの目的は、新しいコントリビューターが直面しがちな、より一般的な質問や 問題をいくつか取り上げることです。 ここでも Git の基本をいくつか扱いますが、 それでも少し進みが速いと感じる場合は、まず Atlassian のこのチュートリアルの 「Beginner」や「Getting started」セクションなど、Git の入門記事を読むとよいでしょう。 GitHub も初心者向けのドキュメントやガイドを提供しています。 また、より詳しい Git の書籍を参照することもできます。

このガイドは完全ではありません。 このページでは解決できない git の問題に遭遇した場合は、 修正方法を文書化できるように、issue を開いてください。

前提条件

Git をインストールし、rust-lang/rust をフォークし、フォークしたリポジトリを 自分の PC にクローン済みであるものとします。 Git とのやり取りにはコマンドラインインターフェイスを使用します。 一般的には同じことができる GUI や IDE 連携も数多くあります。

フォークをクローンしている場合、ローカルリポジトリではそれを origin として参照できます。 次のようにして、公式の rust-lang/rust リポジトリ用のリモートも設定しておくと便利かもしれません。

git remote add upstream https://github.com/rust-lang/rust.git

HTTPS を使用している場合、または

git remote add upstream git@github.com:rust-lang/rust.git

SSH を使用している場合です。

注: このページは rust-lang/rust 向けのワークフローを扱っていますが、 Rust プロジェクト内の他のリポジトリへコントリビュートする際にも役立つ可能性があります。

標準的な手順

以下は、ほとんどの小さな変更や PR で使用することになる通常の手順です。

1. main を基点に変更を加えていることを確認します: git checkout main。
2. Rust リポジトリから最新の変更を取得します: git pull upstream main --ff-only。 （これについての詳細はマージ禁止ポリシーを参照してください）。
3. 変更用の新しいブランチを作成します: git checkout -b issue-12345-fix。
4. リポジトリに変更を加え、テストします。
5. git add src/changed/file.rs src/another/change.rs で変更をステージし、 その後 git commit でコミットします。 もちろん、中間コミットを作成するのもよい考えです。 git add . は避けてください。サブモジュールの更新など、 コミットすべきでない変更を意図せずコミットしてしまいやすくなるためです。 ステージし忘れたファイルがないか確認するには、git status を使用できます。
6. 変更を自分のフォークへプッシュします: git push --set-upstream origin issue-12345-fix （コミットを追加した後は git push を使用でき、リベースまたは pull-and-rebase の後は git push --force-with-lease を使用できます）。
7. 自分のフォークから rust-lang/rust の main ブランチへ PR を開きます。

最終的にリベースが必要になり、コンフリクトに遭遇している場合は、リベースを参照してください。 長期間続く機能や issue に取り組んでいる間に upstream を追跡したい場合は、 最新の状態に保つを参照してください。

レビュー担当者から変更を求められた場合、その変更の手順もほぼ同じですが、 いくつかの手順は省かれます。

1. 自分のコードの最新バージョンに対して変更を加えていることを確認します: git checkout issue-12345-fix。
2. 以前と同じように、追加の変更を行い、ステージし、コミットします。
3. それらの変更を自分のフォークへプッシュします: git push。

git の問題のトラブルシューティング

rust-lang/rust が古くなっていても、最初からクローンし直す必要はありません！ 修復できないほど壊してしまったと思っていても、リポジトリ全体を再度ダウンロードせずに git の状態を修正する方法があります。 遭遇する可能性のある一般的な問題をいくつか示します。

誤ってマージコミットを作成してしまいました。

Git には、ブランチを最新の変更で更新する方法が 2 つあります。マージとリベースです。 Rust はリベースを使用しています。 マージコミットを作成してしまっても、修正はそれほど難しくありません: git rebase -i upstream/main。

リベースの詳細については、リベースを参照してください。

GitHub 上の自分のフォークを削除してしまいました！

これは git の観点では問題ではありません。 git remote -v を実行すると、 次のような内容が表示されます。

$ git remote -v
origin  git@github.com:jyn514/rust.git (fetch)
origin  git@github.com:jyn514/rust.git (push)
upstream        https://github.com/rust-lang/rust (fetch)
upstream        https://github.com/rust-lang/rust (fetch)

フォークの名前を変更した場合は、次のように URL を変更できます。

git remote set-url origin <URL>

ここで <URL> は新しいフォークです。

誤ってサブモジュールを変更してしまいました

通常、これは cargo が変更されたと rustbot が GitHub にコメントを投稿したときに気づきます。

Web UI でコンフリクトに気づく場合もあります。

最も一般的な原因は、変更後にリベースし、サブモジュールを更新するための x を先に実行せずに git add . を実行したことです。 あるいは、x fmt ではなく cargo fmt を実行し、 サブモジュール内のファイルを変更してから、その変更をコミットした可能性もあります。

修正するには、次のことを行います（cargo 以外のサブモジュールを変更した場合は、 src/tools/cargo をそのサブモジュールへのパスに置き換えてください）。

1. 誤った変更が含まれているコミットを確認します: git log --stat -n1 src/tools/cargo
2. そのコミットに対する変更を取り消します: git checkout <my-commit>~ src/tools/cargo。 ~ はそのまま入力しますが、<my-commit> は手順 1 の出力に置き換えてください。
3. git に変更をコミットするよう指示します: git commit --fixup <my-commit>
4. 変更したすべてのサブモジュールについて、手順 1〜3 を繰り返します。
   • 複数の異なるコミットでサブモジュールを変更した場合は、変更した各コミットについて 手順 1〜3 を繰り返す必要があります。 git log コマンドが自分の作成者ではないコミットを表示したときに、 そこで止めればよいことが分かります。
5. 変更を既存のコミットに squash します: git rebase --autosquash -i upstream/main
6. 変更をプッシュします。

リベースしようとすると “error: cannot rebase” が表示されます

リベース時によく見られるエラーは次の 2 つです。

error: cannot rebase: Your index contains uncommitted changes.
error: Please commit or stash them.

error: cannot rebase: You have unstaged changes.
error: Please commit or stash them.

（この 2 つの違いについては https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_the_three_states を参照してください。） これは、前回コミットした時点から変更を加えていることを意味します。 リベースできるようにするには、 変更をコミットするか、リベースを完了したときにそれらをまだコミットされていない状態にしておくために “stash” と呼ばれる一時的なコミットを作成します。 git がこの “stash” を自動的に作成するように設定したい場合があります。これにより、 ほぼすべての場合で “cannot rebase” エラーを防げます。

git config --global rebase.autostash true

stash の詳細については、https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning を参照してください。

‘Untracked Files: src/stdarch’ が表示されますか?

これは library/ ディレクトリへの移動の名残です。 残念ながら、git rebase はサブモジュールのリネームを追跡しないため、 自分でディレクトリを削除する必要があります。

rm -r src/stdarch

<<< HEAD が表示されますか?

おそらく、リベースまたはマージ競合の途中だったのでしょう。 競合を修正する方法については、競合 を参照してください。 変更内容を気にせず、 リポジトリのクリーンなコピーを取り戻したいだけであれば、git reset を使用できます。

# 警告: これにより、あなたが行ったローカルの変更はすべて破棄されます! 代わりに競合を解決することを検討してください。
git reset --hard main

failed to push some refs

git push は正しく動作せず、次のようなことを言います。

 ! [rejected]        issue-xxxxx -> issue-xxxxx (non-fast-forward)
error: failed to push some refs to 'https://github.com/username/rust.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

ここで示されるアドバイスは正しくありません! Rust の “no-merge” ポリシー により、git pull によって作成されるマージコミットは 最終的な PR では許可されませんし、そもそもリベースの目的も損なってしまいます! 代わりに git push --force-with-lease を使用してください。

Git が自分で書いていないコミットをリベースしようとしていますか?

リベースリストに多数のコミット、マージコミット、または自分で 書いていない他の人のコミットが表示される場合、おそらく間違ったブランチを対象にリベースしようとしています。 たとえば、rust-lang/rust のリモート upstream があるのに、git rebase upstream/main ではなく git rebase origin/main を実行したのかもしれません。 修正方法は、リベースを中止し、代わりに正しいブランチを使用することです。

git rebase --abort
git rebase --interactive upstream/main

サブモジュールに関する簡単な注意

git pull でローカルリポジトリを更新すると、自分が一度も編集していないファイルを 変更したと Git が言うことに気づく場合があります。 たとえば、 git status を実行すると次のような出力になります（new commits という言及に注意してください）。

On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   src/llvm-project (new commits)
	modified:   src/tools/cargo (new commits)

no changes added to commit (use "git add" and/or "git commit -a")

これらの変更はファイルへの変更ではなく、サブモジュールへの変更です（これについては後ほど詳しく説明します）。 これらを取り除くには、次を実行します。

git submodule update

一部のサブモジュールは実際には必要ありません。たとえば、download-ci-llvm を使用している場合、 src/llvm-project をチェックアウトする必要はありません。 その履歴を取得し続けなくて済むようにするには、 git submodule deinit -f src/llvm-project を使用できます。これにより、再び変更済みとして表示されることも避けられます。

リベースと競合

ローカルでコードを編集するとき、フィーチャーブランチを作成した時点で存在していた rust-lang/rust のバージョンに変更を加えています。 そのため、PR を提出すると、それ以降に rust-lang/rust に加えられた変更の一部が、 あなたの加えた変更と競合する可能性があります。 これが発生した場合、変更をマージできるようにする前に競合を解決する必要があります。 そのためには、自分の作業を rust-lang/rust の上にリベースする必要があります。

リベース

フィーチャーブランチを rust-lang/rust の main ブランチの最新バージョンの上に リベースするには、自分のブランチをチェックアウトしてから、次のコマンドを実行します。

git pull --rebase https://github.com/rust-lang/rust.git main

次のエラーが表示された場合:

error: cannot pull with rebase: Your index contains uncommitted changes.
error: please commit or stash them.

これは、ワーキングツリーに未コミットの作業があることを意味します。その 場合は、リベースする前に git stash を実行し、リベースしてすべての競合を 修正した後に git stash pop を実行してください。

ブランチを main にリベースすると、そのブランチ上のすべての変更が main の最新バージョンに再適用されます。 言い換えると、Git は、 古いバージョンの main に対して行った変更が、代わりに新しいバージョンの main に 対して行われたかのように見せようとします。 この処理中には、少なくとも 1 つの「リベース競合」に遭遇することを想定しておくべきです。 これは、あなたの変更が他の加えられた変更と競合したために、 Git による変更の再適用が失敗したときに発生します。 次のような行が出力に表示されるため、これが発生したことがわかります。

CONFLICT (content): Merge conflict in file.rs

これらのファイルを開くと、次の形式のセクションが表示されます。

<<<<<<< HEAD
Original code
=======
Your code
>>>>>>> 8fbf656... Commit fixes 12345

これは、Git がどのようにリベースすればよいか判断できなかったファイル内の行を表しています。 <<<<<<< HEAD と ======= の間のセクションには main のコードがあり、反対側にはあなたのバージョンのコードがあります。 競合にどう対処するかを決める必要があります。 自分の変更を残したい場合もあれば、 main 上の変更を残したい場合、またはその 2 つを組み合わせたい場合もあります。

一般に、競合の解決は 2 つの手順で構成されます。まず、特定の競合を修正します。 ファイルを編集して望む変更を加え、その過程で <<<<<<<、=======、>>>>>>> の各行を削除します。 次に、周辺のコードを確認します。 競合があった場合、そこには論理的なエラーも潜んでいる可能性があります! ここで x check を実行して、明らかなエラーがないことを確認するのはよい考えです。

競合の修正がすべて完了したら、競合があったファイルを git add で ステージする必要があります。 その後、git rebase --continue を実行して、 競合を解決したのでリベースを完了してよいことを Git に知らせます。

リベースが成功したら、フォーク上の関連するブランチを git push --force-with-lease で更新します。

最新の状態に保つ

上記のセクションは、作業をリベースし、マージ競合に対処するための具体的な ガイドです。 ローカルリポジトリをアップストリームの変更に追従させて最新の状態に保つ方法について、一般的なアドバイスを以下に示します。 ローカルの main ブランチ上で定期的に git pull upstream main を使用すると、最新の状態を保てます。 フィーチャーブランチも最新の状態に保つ必要があります。 pull した後、フィーチャーブランチをチェックアウトしてリベースできます。

git checkout main
git pull upstream main --ff-only # マージコミットがないことを確実にするため
git rebase main feature_branch
git push --force-with-lease # (origin をローカルと同じ状態に設定する)

No-Merge Policy に従ってマージを避けるには、 git config pull.ff only を使用するとよいでしょう（これにより、設定はローカルリポジトリにのみ適用されます）。 これにより、毎回 --ff-only や --rebase を渡さなくても、 git pull 時に Git がマージコミットを作成しないようにできます。

また、main から git push --force-with-lease を実行することで、 フィーチャーブランチが GitHub 側の状態と同期していることを再確認することもできます。

高度なリベース

コミットを squash する

コミットを互いに「squash」すると、それらは 1 つのコミットに統合されます。 これの利点でも欠点でもあるのは、履歴が単純化されることです。 一方では、変更が行われた手順を追跡できなくなりますが、 履歴は扱いやすくなります。

rust-lang/rust リポジトリの PR でコミットを squash する最も簡単な方法は、PR のコメントで @bors squash コマンドを使用することです。 デフォルトでは、bors は PR のすべてのコミットメッセージを squash 後のコミットメッセージに結合します。 コミットメッセージをカスタマイズするには、@bors squash msg="<commit message>" を使用します。 たとえば、@bors squash msg="Improve diagnostics for missing lifetime parameter" です。

ローカルの git 操作を使用してコミットを squash したい場合は、以下を読み進めてください。

コンフリクトがなく、履歴を整理するためだけに squash する場合は、 git rebase --interactive --keep-base main を使用します。 これにより、PR の分岐点が同じまま保たれるため、 リベースをまたいで何が起きたかの diff をレビューしやすくなります。

squash は、コンフリクト解決の一環としても役立つことがあります。 ブランチに同じコードの連続した複数の書き換えが含まれている場合、または リベースのコンフリクトが非常に深刻な場合は、 git rebase --interactive main を使用してプロセスをより細かく制御できます。 これにより、コミットをスキップするか、スキップしないコミットを編集するか、 適用される順序を変更するか、またはそれらを互いに「squash」するかを選択できます。

あるいは、次のようにしてコミット履歴を犠牲にすることもできます。

# すべての変更を 1 つのコミットに squash し、コンフリクトを 1 回だけ気にすればよいようにする
git rebase --interactive --keep-base main  # その過程ですべての変更を squash する
git rebase main
# すべてのマージコンフリクトを修正する
git rebase --continue

場合によっては、最後の数個のコミットだけをまとめて squash したいこともあります。 それらが実際の変更ではなく「fixup」だけを表している場合などです。 たとえば、 git rebase --interactive HEAD~2 を使用すると、2 つのコミットだけを編集できます。

git range-diff

リベースを完了した後、変更を push する前に、 古いブランチと新しいブランチの間の変更をレビューしたい場合があります。 これは git range-diff main @{upstream} HEAD で行えます。

range-diff の最初の引数、この場合は main は、 古いブランチと新しいブランチを比較する基準となるリビジョンです。 2 番目の引数は ブランチの古いバージョンです。この場合、@upstream は GitHub に push 済みのバージョンを意味し、これはプルリクエストで他の人が見るものと同じです。 最後に、range-diff の 3 番目の引数は ブランチの新しいバージョンです。この場合は HEAD であり、これは現在 ローカルリポジトリでチェックアウトされているコミットです。

同等の省略形である git range-diff main @{u} HEAD も使用できることに注意してください。

通常の Git diff とは異なり、range-diff の出力では、別の - または + の隣に - または + が表示されます。 左側のマーカーは 古いブランチと新しいブランチの間の変更を示し、右側のマーカーはコミットした変更を示します。 したがって、range-diff は「diff の diff」と考えることができます。 古い diff と新しい diff の間の違いを示すためです。

以下は git range-diff の出力例です（Git のドキュメントから取得）:

-:  ------- > 1:  0ddba11 Prepare for the inevitable!
1:  c0debee = 2:  cab005e Add a helpful message at the start
2:  f00dbal ! 3:  decafe1 Describe a bug
    @@ -1,3 +1,3 @@
     Author: A U Thor <author@example.com>

    -TODO: Describe a bug
    +Describe a bug
    @@ -324,5 +324,6
      This is expected.

    -+What is unexpected is that it will also crash.
    ++Unexpectedly, it also crashes. This is a bug, and the jury is
    ++still out there how to fix it best. See ticket #314 for details.

      Contact
3:  bedead < -:  ------- TO-UNDO

（端末での git range-diff の出力は色が付くため、おそらくこの例よりも 読みやすいことに注意してください。）

git range-diff のもう 1 つの機能は、git diff とは異なり、コミットメッセージの diff も表示することです。 この機能は、複数のコミット メッセージを修正する際に、正しい箇所を変更したことを確認できるため便利です。

git range-diff は非常に便利なコマンドですが、その出力形式に慣れるには多少時間がかかることに注意してください。 また、このコマンドに関する Git のドキュメント、 特に “Examples” セクションも役立つかもしれません。

No-Merge Policy

rust-lang/rust リポジトリでは、「リベースワークフロー」として知られるものを使用しています。 これは、PR 内のマージコミットが受け入れられないことを意味します。 そのため、ローカルで git merge を実行している場合は、代わりにリベースすべき可能性が高いです。 もちろん、これは常に正しいわけではありません。git pull が通常行うマージのように、 マージが単なる fast-forward である場合、 マージコミットは作成されないため、心配する必要はありません。 一度 git config merge.ff only を実行すると（これにより、設定はローカルリポジトリに適用されます）、 実行するすべてのマージがこの種類であることが保証されるため、 ミスをすることができなくなります。

この決定にはいくつかの理由があり、他のすべてのものと同様に、これはトレードオフです。 主な利点は、一般的に線形なコミット履歴です。 これにより bisect が大幅に単純化され、履歴とコミットログがはるかに 追いやすく理解しやすくなります。

レビューのヒント

NOTE: このセクションは PR を作成するためではなく、レビューするためのものです。

空白を非表示にする

GitHub には、空白の変更を無効にするための便利なボタンがあります。 ローカルで変更を表示するには、git diff -w origin/main を使用することもできます。

PR を取得する

PR をローカルにチェックアウトするには、git fetch upstream pull/NNNNN/head && git checkout FETCH_HEAD を使用できます。

github の CLI ツールを使用することもできます。 GitHub は PR 上にボタンを表示し、ローカルにチェックアウトするためのコマンドをコピー & ペーストできます。 詳細については https://cli.github.com/ を参照してください。

GitHub dev の使用

GitHub Web UI の代替として、GitHub Dev はリポジトリや PR を閲覧するための Web ベースのエディタを提供します。 URL の github.com を github.dev に置き換えるか、 GitHub ページで . を押すことで開けます。 詳細については、github.dev エディタのドキュメント を参照してください。

大きなコードセクションの移動

ファイル内部での大きな移動に対する Git と GitHub のデフォルトの diff 表示はかなり貧弱です。各 行が削除済み、各行が追加済みとして表示されるため、各行を自分で比較する必要があります。 Git には、移動された行を別の色で表示するオプションがあります。

git log -p --color-moved=dimmed-zebra --color-moved-ws=allow-indentation-change

詳細については、--color-moved のドキュメントを参照してください。

range-diff

PR 作成者向けの関連セクションを参照してください。 これは、予期しない変更がないことを確認するために、 force-push されたコードを比較する際に役立ちます。

特定のファイルへの変更を無視する

リポジトリ内の多くの大きなファイルは自動生成されています。 それらのファイルへの変更を無視した diff を表示するには、 次の構文を使用できます（例: Cargo.lock）。

git log -p ':!Cargo.lock'

任意のパターンがサポートされています（例: :!compiler/*）。パターンは .gitignore と同じ構文を使用し、パターンであることを示すために先頭に : を付けます。

Git サブモジュール

注記: サブモジュールについて知っておくのは良いことですが、rustc にコントリビュートするための 絶対的な前提条件ではありません。 Git を初めて使用する場合は、 このセクションを読む前に Git の主要な概念に慣れておくとよいでしょう。

rust-lang/rust リポジトリでは、rust リポジトリ内から他の Rust プロジェクトを利用する方法として Git submodules を使用しています。 例として、Rust の llvm-project のフォーク、cargo、 stdarch や backtrace のようなライブラリがあります。

これらのプロジェクトは別の Git（および GitHub）リポジトリで開発・保守されており、 それぞれ独自の Git 履歴/コミット、issue トラッカー、PR を持っています。 サブモジュールを使うと、rust リポジトリ内にある種の埋め込みサブリポジトリを作成し、 それらを rust リポジトリ内のディレクトリであるかのように使用できます。

llvm-project を例に考えてみましょう。 llvm-project は rust-lang/llvm-project リポジトリで保守されていますが、 rust-lang/rust ではコンパイラによるコード生成と最適化のために使用されています。 これを rust にはサブモジュールとして、src/llvm-project フォルダに取り込んでいます。

サブモジュールの内容は Git によって無視されます。サブモジュールはある意味で、 リポジトリの他の部分から分離されています。 しかし、cd src/llvm-project を実行してから git status を実行してみると、次のようになります。

HEAD detached at 9567f08afc943
nothing to commit, working tree clean

git から見ると、あなたはもはや rust リポジトリ内ではなく、llvm-project リポジトリ内にいます。 ここでは “detached HEAD” 状態、すなわちブランチ上ではなく 特定のコミット上にいることに気づくでしょう。

これは、あらゆる依存関係と同様に、使用するバージョンを制御できるようにしたいためです。 サブモジュールを使うと、まさにそれが可能になります。各サブモジュールは特定の コミットに「ピン留め」されており、手動で変更しない限り変わりません。 llvm-project ディレクトリで git checkout <commit> を使用し、 rust ディレクトリに戻ると、たとえば git add src/llvm-project を実行することで、この変更を 他の変更と同じようにステージできます。（なお、コミットするためにその変更をステージしない場合、 x を実行したときに、サブモジュールが自動的に「更新」される際に以前のコミットへ戻され、 変更が取り消されてしまうリスクがあります。）

このバージョン選択は通常、プロジェクトのメンテナーによって行われ、 こちらのようになります。

Git サブモジュールに慣れるには少し時間がかかるため、まだ完全に明確でなくても心配しないでください。 直接使わなければならないことはめったにありませんし、繰り返しになりますが、 Rust にコントリビュートするためにサブモジュールについてすべてを知っている必要はありません。 それらが存在し、Git がうまく、そしてかなり便利に扱ってくれる、ある種の埋め込みサブリポジトリ依存関係に 対応していることだけを知っておいてください。

サブモジュールを hard-reset する

ときどき（git status を実行したときに）次のような状況に遭遇することがあります。

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
  (commit or discard the untracked or modified content in submodules)
        modified:   src/llvm-project (new commits, modified content)

そして git submodule update を実行しようとすると、次のようなエラーでひどく壊れることがあります。

error: RPC failed; curl 92 HTTP/2 stream 7 was not closed cleanly: CANCEL (err 8)
error: 2782 bytes of body are still expected
fetch-pack: unexpected disconnect while reading sideband packet
fatal: early EOF
fatal: fetch-pack: invalid index-pack output
fatal: Fetched in submodule path 'src/llvm-project', but it did not contain 5a5152f653959d14d68613a3a8a033fb65eec021. Direct fetching of that commit failed.

(new commits, modified content) が表示される場合は、次を実行できます。

git submodule foreach git reset --hard

その後、もう一度 git submodule update を試してください。

git サブモジュールを deinit する

それでもうまくいかない場合は、すべての git サブモジュールを deinit してみることができます…

git submodule deinit -f --all

残念ながら、何らかの理由でローカルの git サブモジュール設定が 完全におかしくなってしまうことがあります。

fatal: not a git repository: <submodule>/../../.git/modules/<submodule> を克服する

ときどき、何か不運な理由で、次のような状況に遭遇することがあります。

fatal: not a git repository: src/gcc/../../.git/modules/src/gcc

この状況では、指定されたサブモジュールパス、すなわちこの例では <submodule_path> = src/gcc について、次を行う必要があります。

1. rm -rf <submodule_path>/.git
2. rm -rf .git/modules/<submodule_path>/config
3. 何らかの理由で .gitconfig のロックが孤立している場合は、rm -rf .gitconfig.lock

その後、./x fmt のようなものを実行して、bootstrap にサブモジュールのチェックアウトを管理させます。

git blame 中にコミットを無視する

一部のコミットには、機能を変更しない大規模な再フォーマット変更が含まれています。 これらは、.git-blame-ignore-revs を通じて git blame に無視するよう指示できます。

1. 無視するコミットの一覧として .git-blame-ignore-revs を使用するように git blame を設定します: git config blame.ignorerevsfile .git-blame-ignore-revs
2. git blame に無視させたい適切なコミットを追加します。

.git-blame-ignore-revs に追加するコミットにはコメントを含めてください。そうすれば、そのコミットが なぜ無視されているのかを他の人が簡単に理解できます。

@rustbot を使いこなす

@rustbot（triagebot としても知られています）は、主に任意のコントリビューターが、 通常であれば rust-lang organization の GitHub メンバーシップを必要とする特定のタスクを 実行できるようにするために使われるユーティリティロボットです。rustc への コントリビューターにとって特に興味深い機能は、Issue の引き受けとラベル変更です。

Issue の引き受け

@rustbot は、誰でも Issue を自分に割り当てることができるコマンドを公開しています。 作業したい Issue を見つけた場合は、対象の Issue にコメントとして次のメッセージを 送信できます。

@rustbot claim

これにより、まだ担当者がいない場合、@rustbot はその Issue をあなたに割り当てます。 いくつかの GitHub の制約により、間接的に割り当てられる場合があることに注意してください。 つまり、@rustbot はプレースホルダーとして自身を割り当て、先頭のコメントを編集して、 その Issue が現在あなたに割り当てられていることを反映します。

Issue から自分の割り当てを解除したい場合、@rustbot には別のコマンドがあります。

@rustbot release-assignment

Issue のラベル変更

Issue や PR のラベルを変更することも、通常は organization のメンバーに限られています。 しかし、@rustbot を使うと、いくつかの制限はあるものの、自分で Issue のラベルを 変更できます。これは主に次の2つのケースで役立ちます。

Issue トリアージの支援: Rust の Issue トラッカーには、執筆時点で 5,000 件を超える 未解決の Issue があるため、ラベルは可能な限り整理された状態を保つために私たちが持つ 最も強力なツールです。Issue をトリアージするために Issue トラッカーで何時間も費やす 必要はありませんが、Issue を開いた場合、自分で行うことに不安がなければ、自由に ラベルを付けてかまいません。

PR のステータスの更新: 私たちは PR のステータスを反映するために「ステータスラベル」を 使用しています。たとえば、あなたの PR にマージコンフリクトがある場合、自動的に S-waiting-on-author が割り当てられ、PR をリベースするまでレビュー担当者はレビューしない 可能性があります。ブランチをリベースしたら、S-waiting-on-author ラベルを削除し、 S-waiting-on-review を追加し直すために、自分でラベルを変更する必要があります。 この場合、@rustbot コマンドは次のようになります。

@rustbot label -S-waiting-on-author +S-waiting-on-review

このコマンドの構文はかなり緩やかなので、このコマンド呼び出しには他にもバリエーションが あります。ラベルを更新するためのショートカットもあり、たとえば @rustbot ready は 上記のコマンドと同じことを行います。 詳細については、ラベル付けに関するドキュメントページとショートカットを参照してください。

その他のコマンド

@rustbot に何ができるのかを知りたい場合は、そのドキュメントを確認してください。 これは bot のリファレンスとして意図されており、bot がアップグレードされるたびに最新の状態に 保たれるべきものです。

@rustbot は Release チームによってメンテナンスされています。既存のコマンドに関する フィードバックや新しいコマンドの提案がある場合は、遠慮なく Zulip で連絡するか、triagebot リポジトリに Issue を作成してください。

ウォークスルー: 典型的なコントリビューション

バグの修正、パフォーマンスの改善、機能設計の支援、既存機能へのフィードバックの提供など、Rust コンパイラにコントリビュートする方法は_非常にたくさん_あります。 この章は、その表面をなぞるものですらありません。 代わりに、新機能の設計と実装を順を追って説明します。 ここで説明する手順やプロセスのすべてが、すべてのコントリビューションに必要なわけではありません。 必要に応じて、その点も指摘するようにします。

一般に、コントリビューションに関心があるものの、どこから始めればよいかわからない場合は、遠慮なく質問してください！

概要

この章で説明する機能は、マクロ用の ? Kleene 演算子です。 基本的には、次のようなものを書けるようにしたいと考えています。

macro_rules! foo {
    ($arg:ident $(, $optional_arg:ident)?) => {
        println!("{}", $arg);

        $(
            println!("{}", $optional_arg);
        )?
    }
}

fn main() {
    let x = 0;
    foo!(x); // OK！ "0" を出力する
    foo!(x, x); // OK！ "0 0" を出力する
}

つまり基本的に、マクロ内の $(pat)? マッチャーは、他の正規表現構文と同様に、「このパターンは 0 回または 1 回出現できる」という意味です。

アイデアから安定版 Rust の機能に至るまでには、いくつもの手順がありました。 以下は簡単な一覧です。 これらについては、以下で順番に見ていきます。 先ほど述べたように、これらすべてがあらゆる種類のコントリビューションに必要なわけではありません。

• アイデアの議論/Pre-RFC Pre-RFC は、機能の初期ドラフトまたは設計に関する議論です。 この段階は、設計空間を少し具体化し、 アイデアに関するさまざまな利点や問題点を把握することを目的としています。 より広い読者に提示する前に、自分のアイデアについて早期のフィードバックを得る優れた方法です。 元の議論はこちらで確認できます。
• RFC これは、検討のために自分のアイデアをコミュニティへ正式に提示する段階です。 RFC はこちらで確認できます。
• 実装 自分のアイデアをコンパイラに不安定な形で実装します。 元の実装はこちらで確認できます。
• 場合によっては反復/改良 コミュニティが nightly コンパイラや std であなたの 機能を使って経験を積むにつれて、調整が必要になる可能性のある設計上の選択について 追加のフィードバックが寄せられることがあります。 この特定の機能は、いくつもの反復を経ました。
• 安定化 機能が十分に成熟すると、Rust チームメンバーが 安定化を提案することがあります。 合意があれば、それで完了です。
• ひと休み あなたの機能は、安定版 Rust の機能になりました！

Pre-RFC と RFC

注: 一般に、Rust やそのエコシステムに対する_新しい_機能や実質的な 変更を提案するのでなければ、RFC プロセスに従う必要はありません。 代わりに、実装へ直接進むことができます。

RFC を開くべきタイミングに関する公式ガイドラインはこちらで確認できます。

RFC は、提案する機能や変更を詳細に説明する文書です。 誰でも RFC を書くことができます。 プロセスは Rust チームメンバーを含め、全員に対して同じです。

RFC を開くには、GitHub 上の rust-lang/rfcs リポジトリで PR を開きます。 詳細な手順は README で確認できます。

RFC を開く前に、自分のアイデアを「具体化」するための調査を行うべきです。 性急に提案された RFC は、受け入れられない傾向があります。 一般には、動機、影響、欠点、および他の機能との潜在的な相互作用について、十分な説明があるべきです。

それが大変そうに聞こえるなら、実際に大変だからです。 でも心配はいりません！ コンパイラハッカーでなくても、pre-RFC を行うことで有益なフィードバックを得ることができます。 これは、そのアイデアに関する_非公式な_議論です。 これを行うのに最適な場所は internals.rust-lang.org です。 投稿は特定の構成に従う必要はありません。 まとまったアイデアである必要すらありません。 通常は大量のフィードバックが得られ、それを取り入れて優れた RFC を作成できます。

（もう 1 つの実践的なヒント: 関連する過去のアイデアについて、RFC リポジトリと internals を検索してみてください。 多くの場合、アイデアはすでに検討されており、 却下されているか、後で再試行するために延期されています。 これにより、あなた自身と他の全員の時間を節約できます）

この例の場合、pre-RFC スレッドの参加者が 構文上の曖昧さと潜在的な解決策を指摘しました。 また、全体的なフィードバックは好意的に見えました。 このケースでは議論はかなり早く収束しましたが、 アイデアによっては、はるかに多くの議論が行われることもあります（たとえば、なんと 684 件ものコメントを受け取ったこの RFC を参照してください！）。 そのような場合でも、落胆しないでください。 それはコミュニティがあなたのアイデアに関心を持っているという意味ですが、おそらく何らかの調整が必要なのです。

私たちの ? マクロ機能に関する RFC も、RFC スレッドでいくらか議論されました。 ほとんどの RFC と同様に、議論だけでは答えられない質問がいくつかありました。 判断するには、その機能を使用した経験が必要だったのです。 そのような質問は、RFC の「未解決の質問」セクションに記載されています。 また、RFC の議論の過程では、議論の流れを反映するために、RFC 文書自体を更新したくなることもおそらくあるでしょう（たとえば、新しい代替案や過去の取り組みを追加したり、提案自体の一部を変更することにしたりする場合があります）。

最終的に、議論が合意に達し、少し落ち着いてきたように見えると、 Rust チームメンバーが、3 つの可能な処分のいずれかを伴って「最終コメント期間」（FCP）へ進むことを提案する場合があります。 これは、その人が、適切なチームの他のメンバーに RFC をレビューしてコメントしてほしいと考えていることを意味します。 さらに議論が続く場合があり、その結果、さらなる変更や未解決の質問が追加されることがあります。 ある時点で全員が満足すると、RFC は FCP に入ります。これは、 人々が異議を提起できる最後の機会です。 FCP が終了すると、その処分が採択されます。 3 つの可能な処分は次のとおりです。

• Merge: 機能を受け入れる。 こちらが、私たちの ? マクロ機能をマージする提案です。
• Close: この機能は、現在の形では Rust に適していない。 あなたの RFC がこのようになっても落胆しないでください。また、個人的に受け止めないでください。 これはあなた自身への評価ではなく、Rust が 別の方向へ進むというコミュニティの決定です。
• Postpone: この方向に進むことへの関心はあるが、現時点では行わない。 これは多くの場合、該当する Rust チームに、その機能をプロセスを通じて 安定化まで導く余力がないために起こります。 多くの場合、その機能がチームのロードマップに合わない場合がこれに該当します。 延期されたアイデアは、後で再検討されることがあります。

RFC がマージされると、PR は RFCs リポジトリにマージされます。 新しい tracking issue が rust-lang/rust リポジトリに作成され、その機能の進捗を追跡し、 未解決の質問、実装の進捗、ブロッカーなどについて議論します。 こちらが、私たちの ? マクロ機能に関する tracking issue です。

Experimental RFC (eRFC)

eRFC は RFC プロセスの一種で、高レベルの必要性は明確だが、 設計空間が大きすぎて詳細な仕様を最初から確定できない複雑な機能に使われます。 最終的な設計を提供する代わりに、eRFC は一定期間の積極的な実験を認可するための 高レベルな戦略を概説します。 これにより、チームは feature gate の背後で機能を実装し、 実践的なデータを収集できます。そのデータは、その後の安定化に向けた正式な RFC に反映されます。 このプロセスは coroutines のような主要機能で使われましたが（RFC 2033 を参照）、 明示的な “eRFC” ラベルは今日ではほとんど使われていません。 現在このプロジェクトでは一般に、初期バージョンに対して標準の RFC を承認し、最終的な安定化の前に nightly channel を通じて反復することが好まれています。

実装

コンパイラに変更を加えるには、rust-lang/rust リポジトリに対して PR を開きます。

機能、変更、バグ修正、改善によっては、実装は 比較的簡単な場合もあれば、大きな取り組みになる場合もあります。 経験豊富なコンパイラ開発者に、いつでも助けやメンターシップを求めることができます。 また、あなたの機能を実装するのがあなた自身である必要はありません。 ただし、自分で実装しない場合、誰か他の人が実装するまでにしばらくかかる可能性があることは覚えておいてください。

? マクロ機能については、私はコンパイラにおける マクロ展開の関連部分を理解する必要がありました。 個人的には、コード内のコメントを改善することは、自分がそれを理解しているかを 確認するうえで役立つ方法だと思っていますが、 望まないのであればそうする必要はありません。

その後、RFC に記述されているとおりに、元の機能を実装しました。 新しい機能が実装されると、それは feature gate の背後に置かれます。つまり、 その機能を使うには #![feature(my_feature_name)] を使用する必要があります。 feature gate は、その機能が安定化されると削除されます。

ほとんどのバグ修正や改善には feature gate は必要ありません。 単に変更や改善を行うことができます。

rust-lang/rust で PR を開くと、bot があなたの PR をレビュー担当者に割り当てます。 一緒に作業している特定の Rust チームメンバーがいる場合は、 スレッドに r? @reviewer-github-id（例: r? @eddyb）というコメントを残すことで、そのレビュー担当者をリクエストできます。誰をリクエストすればよいかわからない場合は、 誰もリクエストしないでください。 bot が、変更したファイルに基づいて自動的に誰かを割り当てます。

レビュー担当者は、あなたの PR を承認する前に変更を求めることがあります。また、コメントを残した後に PR に “S-waiting-on-author” ラベルを付けることがあります。これは、要求された変更をあなたが行うまで PR がブロックされていることを意味します。 変更の反復作業が完了したら、@rustbot ready というコメントを残すことで、 PR を再び S-waiting-on-review としてマークできます。これにより、 S-waiting-on-author ラベルが削除され、S-waiting-on-review ラベルが追加されます。

質問したり、理解できないことや同意できないことについて議論したりしてかまいません。 ただし、Rust チームの誰かが承認しない限り、PR はマージされないことを認識してください。 レビュー担当者が r=me after fixing ... のようなコメントを残した場合、それはそのレビュー担当者が PR を承認しており、 軽微な問題を修正した後に @bors r=reviewer-github-id（例: @bors r=eddyb）というコメントでマージできることを意味します。 r=someone には権限が必要であり、r=someone とコメントしたときに bors が “🔑 Insufficient privileges…” のように言う場合があることに注意してください。 その場合は、レビュー担当者にあなたの PR を再確認してもらうよう依頼する必要があります。

レビュー担当者が PR を承認すると、それは @bors というさらに別の bot のキューに入ります。 @bors は CI のビルドおよびマージキューを管理します。 あなたの PR が @bors キューの先頭に到達すると、@bors は GitHub Actions 上であなたの PR に対して すべてのテストを実行し、マージを試します。 これが完了するには多くの時間がかかります。 すべてのテストに合格すると、PR はマージされ、次の nightly コンパイラの一部になります！

レビュー過程で一部の PR に起こり得ることがいくつかあります

• 変更が十分に大きい場合、レビュー担当者は PR に対して FCP を要求することがあります。 これにより、該当するチームのすべてのメンバーが変更をレビューする機会を得ます。
• 変更が破壊的変更を引き起こす可能性がある場合、レビュー担当者は crater の実行を要求することがあります。 これは、あなたの変更を含むコンパイラをコンパイルし、その変更済みコンパイラで crates.io 上のすべての crate のコンパイルを試みます。 これは、エコシステムの大きな部分に影響するコンパイラの挙動変更を導入したかどうかを 確認するための優れたスモークテストです。
• あなたの PR の diff が大きい場合やレビュー担当者が忙しい場合、先にマージされてしまった他の PR と マージコンフリクトが発生することがあります。 通常の git の手順を使って、これらのマージコンフリクトを修正する必要があります。

新機能やそれに類するものを行っていない場合（たとえば バグを修正している場合）は、これで終わりです！ ご貢献ありがとうございます :)

実装を洗練する

nightly で新機能を使う経験が蓄積されるにつれて、軽微な変更が 提案されたり、未解決の質問が解決されたりすることがあります。 更新や変更は、上で説明したように、他の変更を実装する場合と同じプロセスを経ます （つまり、PR を提出し、レビューを受け、@bors を待つ、などです）。

一部の変更は、FCP と Rust チームメンバーによるレビューを必要とするほど大きい場合があります。

? マクロ機能については、元の実装後にいくつかの異なる反復を経ました: 1, 2, 3. その過程で、? は区切り記号を取るべきではないと判断しました。これは以前、RFC に未解決の問題として記載されていたものです。 また、曖昧性解消の戦略も変更しました。? を他の繰り返し演算子（例: + や *）の区切りトークンとして使用できる機能を削除することにしました。ただし、これは破壊的変更であるため、エディション境界を越えて行うことにしました。 したがって、この新機能は 2018 エディションでのみ有効にできます。元の RFC からのこれらの差異には、別の FCP が必要でした。

安定化

最後に、この機能が nightly でしばらく試用された後、言語チームのメンバーが これを安定化する動議を提出しました。

安定化レポート を作成する必要があり、そこには以下を含めます。

• 振る舞いの簡単な説明と RFC からの差異
• どのエディションが影響を受けるか、およびその影響
• 興味深い側面を示すいくつかのテストへのリンク

この機能の安定化レポートはこちらです。

その後、機能ゲートを削除し、機能をデフォルトで（2018 エディションで）有効にするために、PR が作成されます。 この機能についての注記が Release notes に追加されます。

機能を安定化する手順は、機能の安定化で確認できます。

新しい言語機能の実装

コンパイラに新しい重要な機能を実装したい場合は、 すべてが円滑に進むように、このプロセスを通る必要があります。

注: このセクションは言語機能を対象としており、別のプロセスを使用するライブラリ機能は対象外です。

言語への変更を提案する方法については、Rust Language Design Team の手順も参照してください。

@rfcbot FCP プロセス

変更が小さく、議論の余地がなく、破壊的変更ではなく、 stable の言語に対してユーザーが観測できる形で影響せず、新しい不安定機能も追加しない場合は、 単に PR を書き、そのコード部分に詳しい人から r+ を得るだけで実施できます。 しかし、そうでない場合は、さらに行うべきことがあります。 コンパイラ内部の作業であっても、 チームの他のメンバーから合意を得ずに議論のある変更を押し通すのはよくありません （「分散システム」という意味では、自分の知らないものを壊さないようにするためであり、 社会的な意味では、PR 上の争いを避けるためです）。

チームの合意が必要な変更については、 最終コメント期間（FCP）を提案するプロセスを使用します。 関連するチームに所属していない場合（したがって @rfcbot の権限がない場合）は、 所属している人に開始を依頼してください。 その人自身に懸念がない限り、開始してくれるはずです。

FCP プロセスが必要なのは、合意が必要な場合だけです – 変更に対して合意を要求するプロセスがなく、 誰も問題にしないと思うなら、r+ だけに頼っても問題ありません。 たとえば、 コンパイラ開発や標準ライブラリでの使用のために、 予約済みのコンパイラ内部用 rustc_ 名前空間にある不安定なコマンドラインフラグや 属性を追加または変更することは、 nightly エコシステムで広く使われることが想定されない限り、FCP なしで問題ありません。 一部のチームは、このようなシナリオで使用する、より軽量なプロセスを持っています。 たとえば、 コンパイラチームは、完全な合意を必要とせずに支持とフィードバックを得る軽量な方法として、 Major Change Proposal（MCP）を提出することを推奨しています。

FCP を提案するために、実装が r+ を得られるほど完全に準備できている必要はありませんが、 少なくとも概念実証があるのは、一般的によい考えです。 そうすることで、人々があなたの話している内容を確認できます。

FCP が提案されると、チームの全メンバーがその FCP を承認する必要があります。 全員が承認した後、 10 日間の「最終コメント期間」（名前の由来です）があり、その間は誰でもコメントできます。 懸念が提起されなければ、その PR/issue は FCP の承認を得ます。

機能を書く際の実務

機能を動作する形で実装するために、 いくつかの「実務上の」手続きを通る必要があるかもしれません。

警告サイクル

場合によっては、機能やバグ修正が、いくつかのエッジケースで既存のプログラムを壊す可能性があります。 その場合は、 影響を評価するために crater run を実施し、必要に応じて将来互換性 lint を追加することになるでしょう。 これは、エディションで制限された lint で使われるものと似ています。

安定性

私たちは Rust の安定性を重視しています。 stable で動作し実行できるコードは、（ほとんどの場合）壊れるべきではありません。 そのため、 チームの合意とコードレビューだけで機能を世に出したくはありません - nightly でその機能を使用する実際の経験を得たいと考えていますし、 その経験に基づいて機能を変更したい場合もあります。

それを可能にするために、 ユーザーが誤ってその新機能に依存しないようにする必要があります - そうしなければ、 特に実験に時間がかかったり遅延したりして、その機能がリリース列車に乗って stable に到達した場合、 事実上 stable になってしまい、 人々のコードを壊さずに変更できなくなってしまいます。

そのための方法として、すべての新機能がフィーチャーゲートされていることを保証します - フィーチャーゲート（#[feature(foo)]）を有効にしなければ使用できず、 これは stable/beta コンパイラでは行えません。 技術的な詳細については、コードにおける安定性セクションを参照してください。

最終的に、その機能を使用して十分な経験を得て、必要な変更を行い、 満足できる状態になったら、こちらで説明されている安定化プロセスを使用して世に公開します。 それまでは、その機能は確定したものではありません。 機能のあらゆる部分は変更される可能性があり、機能が完全に書き直されたり削除されたりする可能性もあります。 機能は、不安定なまま長期間変更されなかったというだけで、既得権を得ることはありません。

追跡 issue

不安定機能の状態、 nightly で使用する中で得られた経験、 そして安定化を妨げている懸念を追跡するために、 すべてのフィーチャーゲートには追跡 issue が必要です。 その機能に関連する issue や PR を作成するときは、この追跡 issue を参照し、 機能の進捗に関する更新があるときは、それらを追跡 issue に投稿してください。

承認済み RFC または承認済みの lang experiment の一部である機能については、 その追跡 issue を使用してください。

その他の機能については、その機能の追跡 issue を作成してください。 issue のタイトルは “Tracking issue for YOUR FEATURE” にする必要があります。 “Tracking Issue” issue テンプレートを使用してください。

Lang experiment

コンパイラに取り込まれるためには、 言語に対してユーザーから見える影響を持つ機能（不安定なものを含む）は、 承認済み RFC の一部であるか、承認済みの lang experiment でなければなりません。

新しい lang experiment を提案するには、 動機と意図した解決策を説明する issue を rust-lang/rust に開いてください。 受け入れられた場合、この issue はその実験の追跡 issue になるため、 これらの他の詳細も含めつつ、追跡 issue のテンプレートを使用してください。 その issue を lang チームに nominate し、@rust-lang/lang と @rust-lang/lang-advisors を CC してください。 実験が承認されると、追跡 issue は B-experimental としてマークされます。

lang experiment に関連するフィーチャーフラグは、 その機能の RFC が承認されるまで incomplete としてマークされなければなりません。

コードにおける安定性

新しい不安定機能を実装するためには、以下の手順に従う必要があります。

1. トラッキングイシューを開くか、特定します。 受理済み RFC または承認済みの lang experiment の一部であるフィーチャーについては、 そのトラッキングイシューを使用します。

   トラッキングイシューに C-tracking-issue と関連する F-feature_name ラベルを付けます （必要であればそのラベルを追加します）。

2. フィーチャーゲートの名前を選びます（RFC の場合は、RFC 内の名前を使用します）。

3. rustc_span/src/symbol.rs の Symbols {...} ブロックにフィーチャー名を追加します。

   このブロックはアルファベット順でなければならないことに注意してください。

4. rustc_feature/src/unstable.rs の unstable な declare_features ブロックにフィーチャーゲート宣言を追加します。

   /// フィーチャーの説明
   (unstable, $feature_name, "CURRENT_RUSTC_VERSION", Some($tracking_issue_number))

   まだトラッキングイシューを開いていない場合 （たとえば、そのフィーチャーが受け入れられそうかどうかについて最初のフィードバックを得たい場合）は、 一時的に None を使用できます。ただし、PR がマージされる前に必ず更新してください！

   例:

   /// ASCII を超える識別子の定義を許可します。
   (unstable, non_ascii_idents, "CURRENT_RUSTC_VERSION", Some(55467)),

   フィーチャーは incomplete としてマークできます。 その type を incomplete に設定することで、 デフォルトで警告となる incomplete_features lint を発生させます。

   /// deref パターンを許可します。
   (incomplete, deref_patterns, "CURRENT_RUSTC_VERSION", Some(87121)),

   lang experiment に関連するフィーチャーフラグは、 そのフィーチャーの RFC が受理されるまで incomplete としてマークしなければなりません。

   セマンティックなマージコンフリクトを避けるため、 1.70 や別の明示的なバージョン番号ではなく CURRENT_RUSTC_VERSION を使用します。

5. フィーチャーゲートが設定されていない限り、新しいフィーチャーを使用できないようにします。 コンパイラ内のほとんどの場所では、 式 tcx.features().$feature_name() を使用して確認できます。

   フィーチャーゲートが設定されていない場合は、 状況に応じて、フィーチャー導入前の挙動を維持するか、エラーを発生させるべきです。 エラーには通常 rustc_session::errors::feature_err を使用するべきです。 エラーを追加する例については、#81015 を参照してください。

   新しい構文を導入するフィーチャーでは、代わりに展開前ゲーティングを使用するべきです。 パース中に新しい構文がパースされたとき、 self.psess.gated_spans.gate(sym::my_feature, span) によって、 その symbol を現在のクレートの GatedSpans に挿入しなければなりません。

   gated spans に挿入した後、 実際にフィーチャーを拒否する rustc_ast_passes::feature_gate::check_crate 関数で その span をチェックしなければなりません。 正確にどのようにゲートするかはフィーチャーの正確な種類によりますが、 ほとんどの場合は gate_all!() マクロを使用することになるでしょう。

6. フィーチャーゲートなしではそのフィーチャーを使用できないことを保証するテストを、 tests/ui/feature-gates/feature-gate-$feature_name.rs を作成して追加します。 対応する .stderr ファイルは、 ./x test tests/ui/feature-gates/ --bless を実行して生成できます。

7. unstable book にセクションを追加します。 場所は src/doc/unstable-book/src/language-features/$feature_name.md です。

8. 新しいフィーチャーについて多くのテストを書きます。できれば tests/ui/$feature_name/ に置きます。 テストのない PR は受け入れられません！

9. PR のレビューを受け、マージします。 これで Rust にフィーチャーを実装することに成功しました！

テストの呼びかけ

実装が完了すると、 そのフィーチャーは nightly ユーザーが利用できるようになりますが、まだ stable Rust の一部ではありません。 これは、Rust のメインブログにブログ記事を書き、 「テストの呼びかけ」を行うのに適したタイミングです。

過去のそのようなブログ記事には次のものがあります。

1. GAT 安定化に向けた取り組み
2. Rust 2024 における impl Trait の変更
3. Async Closures MVP: テストの呼びかけ！

あるいは、This Week in Rust にはこのためのセクションがあります。 これが使用された例の 1 つは次のとおりです。

• cfg 述語としての真偽値リテラルに関するテストの呼びかけ

どの選択肢を選ぶかは、その言語変更がどれほど重要かに依存するかもしれません。 ただし、This Week in Rust のセクションは、 Rust のメインブログでの専用投稿よりも目立ちにくい可能性があることに注意してください。

仕上げ

ユーザーに洗練された体験を提供するということは、単に rustc にフィーチャーを実装する以上のことを意味します。 私たちは、提供しているすべてのツールとリソースについて考える必要があります。 この作業には次が含まれます。

• 言語フィーチャーを Rust Reference に文書化する。
• 新しい構文がある場合は、それをフォーマットするように rustfmt を拡張する（該当する場合）。
• rust-analyzer を拡張する（該当する場合）。 この作業の範囲は言語フィーチャーの性質によって異なる場合があります。 一部のフィーチャーは、完全な サポートを待つ必要がないためです。
  • 言語フィーチャーが rust-analyzer でサポートが実装される前に存在するだけで ユーザー体験を悪化させる場合、 lang チームがブロッキングな懸念を提起する可能性があります。
  • そのような例には、rust-analyzer がパースできない新しい構文や、 誤った診断につながる、rust-analyzer が理解できない型推論の変更などが含まれるかもしれません。

安定化

フィーチャーライフサイクルの最終ステップは安定化です。 これは、そのフィーチャーがすべての Rust ユーザーに利用可能になるときです。 この時点では、 後方互換性のない変更は一般的に許可されなくなります （詳細については、lang チームの定義済み semver ポリシーを参照してください）。 安定化についてさらに詳しく知るには、安定化ガイドを参照してください。

安定性保証

このページでは、私たちの安定性保証の概要を説明します。

RFC

• RFC 1105 API の進化
• RFC 1122 言語の SemVer

ブログ記事

• 成果物としての安定性

rustc-dev-guide のリンク

• ライブラリ機能の安定化
• 言語機能の安定化
• 何がバグ修正に該当するのか？

適用除外

私たちのインフラストラクチャの一部が他者によって使用できる場合でも、それは依然として 内部的なものと見なされ、安定性保証はありません。以下は、安定性保証のない コンポーネントの網羅的ではないリストです。

• remote-test-client / remote-test-server によって使用される CLI と環境変数

安定性属性

このセクションでは、rustc の標準ライブラリで、安定した API が内部的に不安定な API を使用できるようにする安定性属性と仕組みについて説明します。

NOTE: このセクションは ライブラリ 機能についてのものであり、言語 機能についてのものではありません。 言語機能を安定化する手順については、Stabilizing Features を参照してください。

unstable

#[unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")] 属性は、アイテムを不安定であると明示的にマークします。 “unstable” としてマークされたアイテムは、nightly コンパイラであっても、そのクレートに対応する #![feature] 属性がなければ使用できません。 この制限はクレート境界を越える場合にのみ適用され、不安定なアイテムはそれを定義しているクレート内では使用できます。

issue フィールドは、関連する GitHub の issue number を指定します。 このフィールドは必須であり、すべての不安定機能には関連する追跡 issue があるべきです。 適切な値がないまれなケースでは、issue = "none" が使用されます。

unstable 属性はすべてのサブアイテムに波及し、その属性を再適用する必要はありません。 したがって、これをモジュールに適用すると、そのモジュール内のすべてのアイテムが不安定になります。

機能名を変更する場合は、有用なエラーメッセージを生成するために old_name = "old_name" を追加できます。

特定のサブアイテムを安定にするには、それらに #[stable] 属性を使用します。 安定性の仕組みは、pub の動作と似ています。 非公開モジュールの公開関数を持つことができるのと同様に、不安定なモジュール内に安定した関数を持つことも、その逆も可能です。

以前は、rustc bug により、不安定なモジュール内の安定したアイテムが、その場所では安定版コードから利用可能でした。

破壊的変更を避けるために必要な場合を除き、この属性をこれ以上のアイテムに追加してはいけません。

unstable 属性には soft 値を持たせることもでき、これによりハードエラーではなく、デフォルトで deny となる将来非互換 lint になります。 これは、過去に誤って受け入れられていた bench 属性で使用されています。 これにより、Cargo の lint capping を利用して依存関係を壊すことを防ぎます。

stable

#[stable(feature = "foo", since = "1.420.69")] 属性は、アイテムが安定化済みであることを明示的にマークします。 安定した関数は、その本体内で不安定なものを使用できることに注意してください。

rustc_const_unstable

#[rustc_const_unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")] は、unstable 属性と同じインターフェイスを持ちます。 これは、const fn の const 性が不安定であることをマークするために使用されます。 これはまれなケースでのみ必要です。

• const fn が不安定な言語機能または intrinsic を使用している場合。 （これに該当する場合、コンパイラがこの属性を追加するよう指示します。）
• const fn が #[stable] であるが、まだ const-stable にすることが意図されていない場合。
• const-unstable な intrinsic を呼び出すために必要な feature gate を変更する場合。

const 安定性は通常の安定性とは異なり、再帰的です。#[rustc_const_unstable(...)] 関数は、安定版コードから間接的に呼び出すことすらできません。 これは、不安定なコンパイラ実装の成果物が誤って安定版コードに漏れ出したり、不完全な実装の偶発的な癖に縛られたりすることを避けるためです。 このチェックを細かく調整する方法については、下記の rustc_const_stable_indirect 属性と rustc_allow_const_fn_unstable 属性を参照してください。

rustc_const_stable

#[rustc_const_stable(feature = "foo", since = "1.420.69")] 属性は、const fn の const 性が stable であることを明示的にマークします。

rustc_const_stable_indirect

#[rustc_const_stable_indirect] 属性は、#[rustc_const_unstable(...)] 関数に追加することで、#[rustc_const_stable(...)] 関数から呼び出せるようにできます。 これは、その関数が実装の観点では安定版に対応する準備ができていること（つまり、不安定なコンパイラ機能を使用していないこと）を示します。その関数がまだ const-stable でない唯一の理由は API 上の懸念です。

これは、コンパイラ内で const 呼び出しが合成される lang item にも追加するべきです。これにより、それらの呼び出しが再帰的な const 安定性ルールを回避しないようにします。

rustc_intrinsic_const_stable_indirect

intrinsic において、この属性はその intrinsic を「公開された安定関数によって使用される準備ができている」とマークします。 その intrinsic に rustc_const_unstable 属性がある場合は、削除するべきです。 intrinsic にこの属性を追加するには、t-lang と wg-const-eval の承認が必要です！

rustc_default_body_unstable

#[rustc_default_body_unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")] 属性は、unstable 属性と同じインターフェイスを持ちます。 これは、trait 内のアイテムのデフォルト実装を不安定としてマークするために使用されます。 default-body-unstable なアイテムを持つ trait は、そのようなアイテムに明示的な本体を提供することで安定的に実装できます。または、対応する #![feature] を有効にすることでデフォルト本体を使用できます。

ライブラリ機能の安定化

機能を安定化するには、次の手順に従います。

1. @T-libs-api メンバーに、追跡 issue で FCP を開始するよう依頼し、FCP が完了するまで待ちます（disposition-merge を伴う）。
2. #[unstable(...)] を #[stable(since = "CURRENT_RUSTC_VERSION")] に変更します。
3. この API のテストまたは doc-test から #![feature(...)] を削除します。 その機能がコンパイラまたはツールで使用されている場合は、そこからも削除します。
4. これが const fn の場合は、#[rustc_const_stable(since = "CURRENT_RUSTC_VERSION")] を追加します。 あるいは、これをまだ const 安定化する想定ではない場合は、新しい feature gate（新しい追跡 issue を伴う）用に #[rustc_const_unstable(...)] を追加します。
5. rust-lang/rust に対して PR を開きます。
   • 適切なラベルを追加します: @rustbot modify labels: +T-libs-api。
   • 追跡 issue にリンクし、“Closes #XXXXX” と記載します。

機能を安定化する例としては、tracking issue #81656 with FCP と、関連する implementation PR #84642 を参照できます。

allow_internal_unstable

マクロとコンパイラの糖衣構文展開は、その本体を呼び出し元に公開します。 標準ライブラリのマクロ内で不安定なものを使用できない問題を回避するために、指定された機能を安定したマクロ内で使用できるようにする #[allow_internal_unstable(feature1, feature2)] 属性があります。

マクロが const コンテキストで使用され、#[rustc_const_unstable(...)] 関数への呼び出しを生成する場合、allow_internal_unstable があっても、それは依然として拒否されることに注意してください。 そのマクロが再帰的な const 安定性チェックを誤って回避できないようにするため、関数に #[rustc_const_stable_indirect] を追加してください。

rustc_allow_const_fn_unstable

上で説明したように、安定した const fn の内部では、不安定な const 機能は間接的であっても許可されません。 しかし、ときには、ある機能が安定化されることは分かっているが、それがいつなのかは分からない、あるいは安定した（ただし、たとえば実行時には遅い）回避策があるため、不安定機能を破棄した場合でも常に何らかの安定版にフォールバックできる、という場合があります。 そのような場合、[rustc_allow_const_fn_unstable(feature1, feature2)] 属性を使用して、安定した（または間接的に安定した）const fn の本体内で一部の不安定機能を許可できます。

また、const fn には、実行時に呼び出した場合とコンパイル時に呼び出した場合で同じように振る舞う必要があるという不変条件があり、それを維持するよう注意する必要があります（こちらのブログ記事も参照）。 これは、たとえばメモリアドレスを整数に変換するような const fn を作成してはならないことを意味します。 なぜなら、もののアドレスは非決定的であり、コンパイル時には不明であることが多いからです。

いずれかの const fn に rustc_allow_const_fn_unstable 属性を追加する場合は、必ず @rust-lang/wg-const-eval に通知してください。

staged_api

stable または unstable 属性を使用するクレートは、そのクレートに #![feature(staged_api)] 属性を含めなければなりません。

deprecated

標準ライブラリにおける非推奨化は、ユーザーコードにおける非推奨化とほぼ同じです。 項目に #[deprecated] を使用する場合は、stable または unstable 属性も付与されていなければなりません。

deprecated は次の形式です。

#[deprecated(
    since = "1.38.0",
    note = "explanation for deprecation",
    suggestion = "other_function"
)]

suggestion フィールドは任意です。 指定する場合は、警告を修正するための機械的に適用可能な提案として使用できる文字列であるべきです。 これは通常、識別子の名前が変更されたものの、その他の大きな変更が不要な場合に使用されます。 suggestion フィールドを使用する場合は、クレートルートに #![feature(deprecated_suggestion)] が必要です。

ユーザーコードとのもう 1 つの違いは、since フィールドが実際に現在の rustc のバージョンに対してチェックされることです。 since が将来のバージョンである場合、deprecated_in_future lint がトリガーされます。これはデフォルトでは allow ですが、標準ライブラリの大部分では #![warn(deprecated_in_future)] によって警告に引き上げています。

unstable_feature_bound

#[unstable_feature_bound(foo)] 属性は、#[unstable] 属性と併用して、安定した型および安定したトレイトの impl を不安定としてマークするために使用できます。 std/core では、#[unstable_feature_bound(foo)] が注釈された項目は、同じく #[unstable_feature_bound(foo)] が注釈された別の項目からのみ使用できます。 std/core の外部では、#[unstable_feature_bound(foo)] を持つ項目を使用するには、クレートに #![feature(foo)] 属性を指定してその機能を有効化する必要があります。

現在、#[unstable_feature_bound] を注釈できる項目は次のとおりです。

• impl
• 自由関数
• トレイト

名前変更された機能と削除された機能

不安定機能は名前変更および削除されることがあります。 機能の名前を変更する場合は、#[unstable] 属性に old_name = "old_name" を追加できます。 機能を削除する場合は、削除された機能のユーザーに分かりやすいエラーメッセージを生成するために、#!unstable_removed(feature = "foo", reason = "brief description", link = "link", since = "1.90.0") 属性を使用するべきです。

link フィールドは、GitHub issue、コメント、PR など、その機能の削除に関する最も関連性の高い情報へリンクするために使用できます。

安定化のリクエスト

注記: このページは言語機能の安定化について説明しています。 ライブラリ機能の安定化については、ライブラリ機能の安定化を参照してください。

不安定機能が十分にテストされ、未解決の懸念がなくなったら、誰でもその安定化を推進できますが、その機能に携わってきた人々を関与させるのが賢明です。 以下の手順に従ってください。

必要であれば RFC を書く

その機能が lang experiment の一部であった場合、lang チームは一般に、安定化の前にまず RFC を受理したいと考えます。

ドキュメント PR

その機能は Unstable Book に文書化されている可能性があり、これは src/doc/unstable-book にあります。 feature gate のページが存在する場合は削除してください。 そのドキュメントの有用な部分を他の場所に統合してください。

ドキュメントの更新が必要になる可能性がある場所は次のとおりです。

• The Reference: これは完全な詳細を含めて更新しなければならず、安定化をマージできるようになる前に、lang-docs チームのメンバーが PR をレビューして承認しなければなりません。
• 判断に迷う場合は、このリポジトリで issue を開いてください。そこで議論できます。
• 標準ライブラリドキュメント: これは必要に応じて更新されます。 言語機能では多くの場合これは不要ですが、? が言語に追加されたときのように、慣用的な例の書き方を変える機能であれば、ライブラリドキュメント内のこれらを更新することが重要です。 また、標準ライブラリ内のキーワードドキュメントと ABI ドキュメントも確認してください。これらは言語の変更に応じて更新が必要になる場合があります。

上記のリポジトリについて、この新機能に関するドキュメントを更新する PR を準備してください。 これらのリポジトリのメンテナーは、安定化プロセス全体が完了するまで、これらの PR をオープンのままにしておきます。 その間に、次の手順に進むことができます。

安定化レポートを書く

このリポジトリにあるテンプレートを使用して安定化レポートを作成してください。

安定化レポートは以下を要約します。

• RFC が受理されてからの主要な設計上の決定と逸脱。これには、FCP された、または言語チームによって他の形で受理された決定と、lang チームに初めて提示されるものの両方が含まれます。
  • 多くの場合、最終的に安定化される言語機能には、元の RFC から大きな設計上の逸脱があります。 それは問題ありませんが、これらの逸脱は明確に示し、慎重に説明しなければなりません。
• RFC が受理されてから行われた作業。言語機能の前進を支えた主要なコントリビューターを明記します。

Stabilization Template には、この機能と lang のサブチーム（例: types、opsem、lang-docs など）との関連を明らかにし、見落とされがちな項目を特定することを目的とした一連の質問が含まれています。

安定化レポートは通常、安定化 PR のメインコメントとして投稿されます（次のセクションを参照）。

安定化 PR

機能はそれぞれ異なり、このガイドで説明している内容を超える手順が必要になる場合もあります。

lang チームが安定化を検討する前に、その機能を説明する The Reference への完全な PR が存在していなければならず、安定化 PR がマージされる前に、その PR は lang-docs チームによってレビューされ、承認されていなければなりません。

feature-gate 一覧の更新

不安定な feature-gate の中央一覧は compiler/rustc_feature/src/unstable.rs にあります。 declare_features! マクロを検索してください。 安定化しようとしている機能のエントリがあるはずです。 たとえば次のようなものです（rust-lang/rust#32409 から引用）。

// pub(restricted) 可視性 (RFC 1422)
(unstable, pub_restricted, "CURRENT_RUSTC_VERSION", Some(32409)),

上記の行は compiler/rustc_feature/src/accepted.rs に移動する必要があります。 declare_features! 呼び出し内のエントリはソートされているため、正しい場所を見つけてください。 完了すると、次のようになります。

// pub(restricted) 可視性 (RFC 1422)
(accepted, pub_restricted, "CURRENT_RUSTC_VERSION", Some(32409)),
// これを変更したことに注意

（過去の変更のファイル内でバージョン番号を見かけることになりますが、安定化が行われると予想する rustc バージョンを入れるべきではありません。代わりに CURRENT_RUSTC_VERSION を使用してください。）

feature-gate の既存の使用箇所の削除

次に、コードベース内で機能文字列（この場合は pub_restricted）を検索し、それが出現する場所を見つけます。 std および任意の rustc クレート内の #![feature(XXX)] の使用箇所を （これには library/ および compiler/ 配下のテストフォルダーが含まれますが、トップレベルの tests/ は含まれません） #![cfg_attr(bootstrap, feature(XXX))] に変更してください。 これにより、feature-gate は stage1 にのみ含まれます。stage1 は現在のベータを使用してビルドされます（これは、その機能が現在のベータではまだ不安定であるために必要です）。

また、テスト（例: tests/ 配下）からそれらの文字列を削除してください。feature-gate を特に対象とするテスト（つまり、その機能を使うには feature-gate が必要であることだけをテストし、それ以外は何もテストしないもの）がある場合は、そのテストを単に削除してください。

その機能の使用に feature-gate を要求しない

最も重要なのは、feature-gate が存在しない場合にエラーを示すコードを削除することです（その機能は現在では安定していると見なされるためです）。 その機能が何らかの新しい構文を使用するために検出できる場合、そのコードの一般的な場所は compiler/rustc_ast_passes/src/feature_gate.rs です。 たとえば、次のようなコードが見つかるかもしれません。

gate_all!(pub_restricted, "`pub(restricted)` 構文は実験的です");

gate_all! マクロは、pub_restricted 機能が有効になっていない場合にエラーを報告します。 pub(restricted) が安定した現在では、これは不要です。

より微妙な機能については、次のようなコードが見つかる場合があります。

if self.tcx.features().async_fn_in_dyn_trait() { /* XXX */ }

この pub_restricted フィールド（機能にちなんで名付けられたもの）は、通常、feature flag が存在しない場合は false、存在する場合は true になります。 そのため、そのフィールドが true であると仮定するようにコードを変換してください。 この場合、それは if を削除し、/* XXX */ だけを残すことを意味します。

if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ }
これは次のようになります
/* XXX */

if self.tcx.sess.features.borrow().pub_restricted && something { /* XXX */ }
 これは次のようになります
if something { /* XXX */ }

チームのノミネート

安定化 PR を開くときは、lang チームとそのアドバイザー（@rust-lang/lang @rust-lang/lang-advisors）、およびその機能に関連するその他のチームを CC してください。例:

• @rust-lang/types: 型システムとの相互作用について。
• @rust-lang/opsem: unsafe コードとの相互作用について。
• @rust-lang/compiler: 実装の堅牢性について。
• @rust-lang/libs-api: 標準ライブラリ API またはその保証に対する変更について。
• @rust-lang/lang-docs: これを Reference でどのように文書化すべきかに関する質問について。

安定化レポートとともに安定化 PR が開かれたら、すぐに寄せられるコメントを少し待ってください。 そのようなコメントが「落ち着いて」、その PR を lang チームが検討する準備ができたと感じたら、今後の lang ミーティングで検討される議題に載せるために、PR をノミネートしてください。

あなたが rust-lang organization のメンバーでない場合は、割り当てられたレビュアーに、あなたに代わって関連チームを CC するよう依頼できます。

PR で FCP を提案する

lang チームやその他の関連チームが安定化をレビューし、彼らからの質問があればそれに回答した後、いずれかのチームのメンバーが次のコメントをすることで、安定化の受け入れを提案できます。

@rfcbot fcp merge

十分な数のチームメンバーがレビューすると、その PR は「最終コメント期間」（FCP）に移行します。 新たな懸念が提起されなければ、この期間は完了し、その PR は通常どおり実装レビューを経てマージできます。

安定化のレビューとマージ

安定化において、r+ を与える前に、その PR が次を満たしていることを確認してください。

• チームが安定化対象として提案した内容、および Reference PR に文書化されている内容と一致していること。
• 懸念を解決または回避するために、チームが途中で要求すると決定した変更をすべて含んでいること。
• それ以外の点では、安定化レポート、および関連する RFC や過去の lang FCP に記載されている内容と完全に一致していること。
• 指定され、安定化が受け入れられ、Reference に文書化されたもの以外の挙動を stable で公開していないこと。
• これらを説得力をもって示すための十分なテストがあること。
• lang-docs のメンバーによってレビューおよび承認された Reference への PR が添えられていること。

特に、PR をレビューするときは、lang チームが検討および指定し損ねたユーザーから見える詳細がないか注意してください。 そのようなものを見つけた場合は、それを説明し、lang チームに対して PR をノミネートしてください。

安定化レポートテンプレート

これは何か？

これは、言語機能の安定化レポート用のテンプレートです。各質問は、最も頻繁に必要とされる詳細を引き出すことを目的としています。これらの詳細は、レビュー担当者が潜在的な問題を事前に特定するのに役立ちます。テンプレートのすべての部分が、すべての安定化に当てはまるわけではありません。質問が当てはまらない場合は、その理由を簡潔に説明してください。

区切り線より後ろをすべてコピーし、Markdownとして編集してください。各TODOをあなたの回答に置き換えてください。

安定化レポート

概要

この機能が何であり、どのような価値を提供するのかを思い出させてください。この安定化に至るまでの経緯を説明してください。

例として、以下を参照してください。

• AFIT/RPITITを安定化する
• RTNを安定化する
• ATPITを安定化する
• opaque typeの正確なキャプチャを安定化する

TODO

追跡:

• TODO（追跡issueへのリンク。）

Reference PR:

• TODO（Reference PRへのリンク。）

cc @rust-lang/lang @rust-lang/lang-advisors

安定化されるもの

安定化される各挙動を説明し、今後受理されるようになるコードの短い例を示してください。

#![allow(unused)]
fn main() {
todo!()
}

安定化されないもの

安定化されない機能の部分を説明してください。今後何を行いたい可能性があるのか、またそのためにどのような扉を開いたままにしているのかについて述べてください。安定化しない内容がユーザーに驚きをもたらす可能性がある場合は、特にその点について述べてください。

設計

Reference

Referenceにどのような更新が必要ですか？各PRにリンクしてください。Referenceにこの機能を説明するために必要な内容が欠けている場合は、その点を議論してください。

• TODO

RFCの履歴

この機能について、どのRFCが受理されていますか？

• TODO

未解決の質問への回答

RFCによって未解決のまま残された質問は何ですか？それらにはどのように回答されましたか？関連するlangの決定があればリンクしてください。

TODO

RFC後の変更

RFCが受理されて以降、その他にどのようなユーザーから見える変更が発生しましたか？langチームが受理した変更（およびそれらの決定へのリンク）と、この安定化レポートで初めてチームに提示される変更の両方を説明してください。

TODO

重要なポイント

どの決定が最も困難で、安定化される挙動のうちどれが最も議論を呼びましたか？すべての立場における主要な主張を要約し、以前の文書や議論にリンクしてください。

TODO

Nightly拡張

この機能には、まだ不安定なまま残っている拡張がありますか？私たちがそれらに誤ってコミットしていないことを、どのように確認していますか？

TODO

閉じられる扉

この安定化によって、言語に対する将来の変更について、どのような扉が閉じられますか？たとえば、この安定化によって、他のRFC、lang実験、または進行中であることが知られている提案を後で実施することがより困難または不可能になりますか？

フィードバック

テストの呼びかけ

「テストの呼びかけ」は行われましたか？行われた場合、どのようなフィードバックが得られましたか？

TODO

Nightlyでの使用

既知のnightlyユーザーはこの機能を使用していますか？GitHub上でgrepを使って#![feature(FEATURE_NAME)]のインスタンス数を数えると参考になるかもしれません。

TODO

実装

主要部分

実装の主要部分を要約し、コード内の該当箇所や関連するPRへのリンクを示してください。

例として、async closuresの主要部分についての次の内訳を参照してください。

• https://rustc-dev-guide.rust-lang.org/coroutine-closures.html

TODO

カバレッジ

この機能のテストカバレッジを要約してください。

この機能の「境界」がどこにあるかを考慮してください。私たちは特に、近接するもののうち正確に何を安定化しないのかについて確信を与えるテストを見ることに関心があります。もちろん、テストはこの機能が機能することを包括的に実証するべきです。よくある間違いが行われた場合や機能が誤って使用された場合に見られる診断を実証することも考えてください。

各テスト内では、テストの目的と、それが実証しようとする不変条件の集合を説明するコメントを先頭に含めてください。これは私たちのレビューにとって大いに助けになります。

テストカバレッジにおける既知または意図的なギャップを説明してください。

テストフォルダおよび個々のテストへのリンクを示し、文脈を説明してください。

TODO

未解決のバグ

この機能に関係する未解決のバグは何ですか？それらを列挙してください。そのいずれかが安定化をブロックするべきですか？その理由、またはそうでない理由を議論してください。

TODO

• TODO
• TODO
• TODO

未解決のFIXME

その機能に関して、コード内にまだどのようなFIXMEが残っており、それらを残しておいて問題ないのはなぜですか？

TODO

ツールの変更

この機能をサポートするために、他のツールにどのような変更を加える必要がありますか。この作業は完了していますか？関連するPRやissueがあればリンクしてください。

• rustfmt
  • TODO
• rust-analyzer
  • TODO
• rustdoc（JSONとHTMLの両方）
  • TODO
• cargo
  • TODO
• clippy
  • TODO
• rustup
  • TODO
• docs.rs
  • TODO

TODO

破壊的変更

この安定化が既知の破壊的変更を表す場合は、craterレポート、craterレポートの分析、およびこの破壊的変更の影響を受けるエコシステムプロジェクトに対して私たちが作成したすべてのPRにリンクしてください。把握または修正できることの制限について議論してください。

TODO

Craterレポート:

• TODO

Crater分析:

• TODO

影響を受けるcrateへのPR:

• TODO
• TODO
• TODO

型システム、opsem

コンパイル時チェック

未定義動作を防ぐために必要な、どのようなコンパイル時チェックが行われますか？

これらのチェックが行われていることを実証するテストにリンクしてください。

TODO

• TODO
• TODO
• TODO

型システムのルール

この機能ではどのような型システムのルールが強制され、それぞれの目的は何ですか？

TODO

デフォルトで健全か？

この機能の実装は、UBを防ぐために特定のチェックを必要としますか？それともデフォルトで健全であり、危険な操作やunsafeな操作を実行するには特定のオプトインが必要ですか？デフォルトで健全でない場合、その根拠は何ですか？

TODO

AMを破るか？

ユーザーはこの機能を使用して未定義動作を導入できますか？または、この機能を使用してRustの抽象化を破り、基礎となるアセンブリレベルの実装を露出させることができますか？該当する場合はその点を説明してください。

TODO

一般的な相互作用

一時値

この機能は、一時値を生成できる新しい式を導入しますか？それらの一時値のスコープは何ですか？

TODO

Drop順序

この機能は、値をどの順序でdropすべきかについて疑問を生じさせますか？ここで行われた決定と、それらが以前の決定とどのように一貫しているかについて述べてください。

TODO

展開前 / 展開後

この機能は、展開前（例: #[cfg(false)]で覆われたコード内）に何を受理すべきかと、展開後に何を受理すべきかについて疑問を生じさせますか？これについてどのような決定が行われましたか？

TODO

Edition hygiene

この機能がeditionでゲートされている場合、トークンのedition hygieneの文脈で、コードを受理するか拒否するかをどのように判断しますか？たとえば、判断にはどのトークンを使用しますか？

TODO

SemVerへの影響

この機能は、ライブラリ作者がマイナーバージョンリリースを行う際に、下流を壊さないよう注意しなければならない新たな方法を生み出しますか？それらを説明してください。これらの新たな危険性は、RFC 1105 に照らして「メジャー」ですか、それとも「マイナー」ですか？

TODO

他の機能の露出

この機能によって、他の不安定な機能の挙動が何らかの形で露出する可能性はありますか？その中で最もリスクが高い機能は何ですか？

TODO

履歴

ここに至った経緯を理解するうえで重要な issue と PR を列挙してください。

• TODO
• TODO
• TODO

謝辞

表彰のため、またそれらの人々に安定化について通知されるように、この機能への貢献者を名前で要約してください。この作業に関わった人の中で、これを今すぐ安定化すべきではないと考えている人はいますか？もしそうであれば、その点について知らせてください。

TODO

未解決項目

まだ完了しておらず、これが安定化される前に完了すべき既知の項目を列挙してください。

• TODO
• TODO
• TODO

機能ゲート

この章は、機能ゲートの追加、削除、変更に関する基本的な支援を提供することを目的としています。

rustc がコンパイラパイプライン内で機能ゲートをどのように適用し、チェックするかについては、 機能ゲートチェックを参照してください。

これは言語機能ゲートに固有の内容であることに注意してください。ライブラリ機能ゲートでは別の 仕組みを使用します。

機能ゲートを追加する

手順については、「新機能を実装する」セクションの“コード内の安定性”を参照してください。

機能ゲートを削除する

機能ゲートを削除するには、次の手順に従ってください。

1. rustc_feature/src/unstable.rs 内の機能ゲート宣言を削除します。 次のようなものです。

   /// 機能の説明
   (unstable, $feature_name, "$version", Some($tracking_issue_number))

2. 削除したばかりの機能ゲート宣言を変更したバージョンを rustc_feature/src/removed.rs に追加します。

   /// 機能の説明
   (removed, $old_feature_name, "$version", Some($tracking_issue_number),
    Some("$why_it_was_removed"))

機能ゲートの名前を変更する

機能ゲートの名前を変更するには、次の手順に従ってください（最初の 2 つは、機能ゲートを削除するときに 従う手順と同じです）。

1. rustc_feature/src/unstable.rs 内の古い機能ゲート宣言を削除します。 次のようなものです。

   /// 機能の説明
   (unstable, $old_feature_name, "$version", Some($tracking_issue_number))

2. 削除したばかりの古い機能ゲート宣言を変更したバージョンを rustc_feature/src/removed.rs に追加します。

   /// 機能の説明
   /// `$new_feature_name` に名前変更済み
   (removed, $old_feature_name, "$version", Some($tracking_issue_number),
    Some("renamed to `$new_feature_name`"))

3. 新しい名前の機能ゲート宣言を rustc_feature/src/unstable.rs に追加します。 これは古い宣言と非常によく似たものになるはずです。

   /// 機能の説明
   (unstable, $new_feature_name, "$version", Some($tracking_issue_number))

機能を安定化する

手順については、「機能の安定化」章の“機能ゲート一覧の更新”を参照してください。 単に宣言を更新するだけでなく、追加で行う必要がある手順があります！

コーディング規約

この章では、フォーマット、正しさのためのコーディング、 crates.io のクレートの使用、およびレビューしやすい PR の構成に関するヒントを扱います。