外部リポジトリの使用

rust-lang/rust git リポジトリは、rust-lang organization 内のいくつかの他のリポジトリに依存しています。 依存関係の利用方法には、主に 3 つあります。

1. crates.io 経由の Cargo 依存関係として（例: rustc-rayon）
2. git（例: clippy）または josh（例: miri）のサブツリーとして
3. git サブモジュールとして（例: cargo）

一般的なルールとして:

• エコシステム内の他の人にとっても有用になり得るライブラリには crates.io を使用する
• コンパイラ内部に依存し、破壊的変更がある場合に更新が必要なツールにはサブツリーを使用する
• コンパイラから独立しているツールにはサブモジュールを使用する

外部依存関係（サブツリー）

以下の外部プロジェクトは、何らかの形式の subtree を使用して管理されています。

• clippy
• miri
• portable-simd
• rustfmt
• rust-analyzer
• rustc_codegen_cranelift
• rustc_codegen_gcc
• rustc-dev-guide
• compiler-builtins
• stdarch

submodule 依存関係とは対照的に （それらについては以下を参照）、subtree 依存関係は通常のファイルとディレクトリにすぎず、 ツリー内で更新できます。ただし、可能であれば、これらのツールに固有の機能強化、バグ修正などは、 各ツールのそれぞれの upstream リポジトリに直接報告するべきです。 例外として、新しいツール機能やテストを実装するために rustc の変更が必要な場合は、 それを 1 つのまとまった rustc PR で行うべきです。

subtree 依存関係は現在、2 つの異なるアプローチで管理されています。

• git subtree を使用する
  • clippy（同期ガイド）
  • portable-simd（同期スクリプト）
  • rustfmt
  • rustc_codegen_cranelift（同期スクリプト）
  • rustc_codegen_gcc（同期ガイド）
• josh ツールを使用する
  • miri
  • rust-analyzer
  • rustc-dev-guide
  • compiler-builtins
  • stdarch

Josh サブツリー

josh ツールは git サブツリーの代替であり、git 履歴を異なる方法で管理し、大規模なリポジトリに対してよりよくスケールします。 josh を扱うには専用のツールが必要です。 同期を支援するためのヘルパーツール rustc-josh-sync を提供しており、これについては以下で説明します。

Josh サブツリーの同期

Josh サブツリーの更新を実行するために、rustc-josh-sync という専用ツールを使用します。 以下のコマンドはすべての Josh サブツリーで使用できますが、miri については、 pull 中にいくつかの追加手順を実行する必要がある点に注意してください。

以下のコマンドでツールをインストールできます。

cargo install --locked --git https://github.com/rust-lang/josh-sync

pull（rust-lang/rust からサブツリーへ変更を同期する）と push（サブツリーから rust-lang/rust へ変更を同期する）は、どちらもサブツリーのリポジトリから実行します（したがって、まず ターミナルでそのリポジトリのチェックアウトディレクトリへ移動してください）。

pull の実行

1. サブツリーへ PR を作成するために使用する新しいブランチをチェックアウトする
2. pull コマンドを実行する

   rustc-josh-sync pull
   

3. ブランチを自分の fork に push し、サブツリーリポジトリへの PR を作成する
   • gh CLI がインストールされている場合、rustc-josh-sync が PR を作成できます。

push の実行

注: 続行する前に、Git に関連するいくつかのガイダンスを [josh-sync README 上で]確認してください。

1. push コマンドを実行し、<gh-username> アカウント配下の rustc fork に <branch-name> という名前のブランチを作成する

   rustc-josh-sync push <branch-name> <gh-username>
   

2. <branch-name> から rust-lang/rust への PR を作成する

新しい Josh サブツリー依存関係の作成

リポジトリ依存関係を git subtree または git submodule から josh へ移行したい場合は、このガイドを確認できます。

git サブツリーの同期

サブツリーベースの依存関係に対して行われた変更は、定期的にこの リポジトリと upstream ツールリポジトリの間で同期する必要があります。

サブツリー同期は通常、それぞれのツールメンテナーによって処理されます。 他のユーザーも 同期 PR を提出できますが、そのためにはローカルの git インストールを変更し、 非常に正確な一連の手順に従う必要があります。 これらの手順は、いくつかの有用なヒントやコツとともに、Clippy の Contributing ガイド内の syncing subtree changes セクションに文書化されています。 この手順は、任意のサブツリーベースのツールで使用できますが、必ず 対応する正しいサブツリーディレクトリとリモートリポジトリを使用してください。

同期プロセスには、subtree push と subtree pull の 2 つの方向があります。

subtree push は、このリポジトリ内のコピーに対して発生したすべての変更を取り込み、 ローカルの変更に対応するコミットをリモートリポジトリ上に作成します。 サブツリーに触れたすべてのローカルコミットはリモートリポジトリ上のコミットを発生させますが、 指定されたディレクトリからツールリポジトリのルートへファイルを移動するように変更されます。

subtree pull は、最後の subtree pull 以降のすべての変更を ツールリポジトリから取り込み、ツールの変更を Rust リポジトリ内の指定されたディレクトリへ移動する マージコミットとともに、これらのコミットを rustc リポジトリに追加します。

常に最初に push を行い、それをツールのデフォルトブランチへマージしてもらうことを推奨します。 その後 pull を行うと、マージは競合なしで機能します。 pull 中に競合を解決することはもちろん可能ですが、PR が十分速くマージされず新しい競合が発生した場合、 競合解決をやり直さなければならないことがあります。 git subtree pull の結果を rebase しようとしないでください。一般に、マージコミットを rebase するのは悪い考えです。

サブツリーディレクトリと対応するリモート リポジトリには、常に -P プレフィックスを指定する必要があります。 誤ったディレクトリまたはリポジトリを指定すると、 誤ったディレクトリを誤ったリモートリポジトリへ push しようとする、とても愉快なマージが発生します。 幸い、rustc 内の pull されたコミットまたはリモート上の push されたブランチのいずれかを破棄することで、 何の影響もなくこれを中止してやり直すことができます。 同期されようとしているコミットが突然数千個表示されるため、 通常、この状況が発生していることはかなり明らかです。

新しい subtree 依存関係の作成

既存のリポジトリから新しい subtree 依存関係を作成したい場合は、（この リポジトリのルートディレクトリから！）次を実行してください。

git subtree add -P src/tools/clippy https://github.com/rust-lang/rust-clippy.git master

これにより新しいコミットが作成されます。このコミットは、いかなる場合でもリベースしてはなりません！ リベースする必要がある場合は、そのコミットを削除して操作をやり直してください。

これで完了です。src/tools/clippy ディレクトリは、Clippy が rustc モノレポの一部であるかのように振る舞うため、実際に git subtree を使う必要があるのは、 あなた（または subtree を同期する他の人）だけです。

外部依存関係（サブモジュール）

Rust のビルドでは、git submodules を使って追跡される外部 Git リポジトリも使用します。 完全な一覧は .gitmodules ファイルで確認できます。 これらのプロジェクトの一部は必須（標準ライブラリ向けの stdarch など）であり、 一部は任意（src/doc/book など）です。

サブモジュールの使用方法については、Git の使用に関する章でさらに詳しく説明されています。

一部のサブモジュールは、ビルドできない、またはテストが通らない「broken」状態になることが許容されています。たとえば、 The Rust Reference のようなドキュメントブックです。 これらのプロジェクトのメンテナーには、 プロジェクトが broken 状態になっているときに通知され、できるだけ早く修正する必要があります。 現在の状態は toolstate website で追跡されています。 詳細は Forge の Toolstate chapter で確認できます。 実際には、ドキュメントが broken toolstate になることは非常にまれです。

beta および stable チャンネルでは破損は許可されておらず、PR がマージされる前に対処されなければなりません。 また、beta cut までの 1 週間は、main で broken であることも許可されません。