diff --git a/src/editions/transitioning-an-existing-project-to-a-new-edition.md b/src/editions/transitioning-an-existing-project-to-a-new-edition.md index b439943..b4c2dc2 100644 --- a/src/editions/transitioning-an-existing-project-to-a-new-edition.md +++ b/src/editions/transitioning-an-existing-project-to-a-new-edition.md @@ -1,6 +1,7 @@ + # 既存のプロジェクトのエディションを移行する -Rust には、プロジェクトのエディションを進めるための自動移行ツールが付属しています。 -このツールは、あなたのソースコードを書き換えて次のエディションに適合させます。 -簡単にいうと、新しいエディションに進むためには次のようにすればよいです。 +Rust には、プロジェクトのエディションを更新するための自動移行ツールが付属しています。 +このツールは、ソースコードを書き換えて次のエディションに適合させます。 +新エディションを採用するために必要な手順は、概ね以下の通りです: -1. `cargo fix --edition` を実行する -2. `Cargo.toml` の `edition` フィールドを新しいエディションに設定する。たとえば、 `edition = "2021"` とする -3. `cargo build` や `cargo test` を実行して、修正がうまくいったことを検証する。 +1. `cargo update` を実行して、依存ライブラリを最新版にする +2. `cargo fix --edition` を実行する +3. `Cargo.toml` の `edition` フィールドを新しいエディションに設定する。たとえば、 `edition = "2024"` とする +4. `cargo build` や `cargo test` を実行して、修正がうまくいったことを検証する +5. `cargo fmt` を実行して、コードをリフォーマットする + +## 依存ライブラリを更新する + + + +作業前に、依存ライブラリを更新することをお勧めします。特に、proc macro や、ビルド時にコードを生成するような依存ライブラリは、エディションを進めることで互換性の問題が生じる場合があります。 +依存ライブラリを更新をしていなかった間に、それらの問題を解消した新バージョンが出ているかもしれません。 +以下のコマンドで依存ライブラリを更新できます。 + +```console +cargo update +``` + + + +更新後、コードが壊れていないことを確認するため、テストを実行しておくとよいでしょう。 +`git` などのバージョン管理システムを使っているなら、適切なコミット粒度のためにここで一旦コミットしておくとよいでしょう。 + -## あなたのコードを新しいエディションでコンパイルできるようにする +## コードが新しいエディションでコンパイルできるようにする -あなたのコードは新しいエディションに互換性のない機能を使っているかもしれないし、使っていないかもしれません。 -Cargo には [`cargo fix`] というサブコマンドがあり、これがあなたのコードを自動的に更新して次のエディションへの移行を補助してくれます。 +コードは、新しいエディションと非互換な機能を使っている可能性があります。 +Cargo の [`cargo fix`] サブコマンドで、コードを自動修正して次のエディションへ移行につなげることができます。 まず初めに、これを実行してみましょう。 ```console @@ -105,7 +135,7 @@ This will check your code, and automatically fix any issues that it can. Let's look at `src/lib.rs` again: --> -これはあなたのコードをチェックして、自動的に移行の問題を修正してくれます。 +コードは検査され、移行で発生する問題が自動的に修正されます。 もう一度 `src/lib.rs`を見てみましょう。 ```rust @@ -121,7 +151,7 @@ which is conventional for unused variables. --> `i32` 値をとるパラメータに名前が追加された形でコードが書き換えられています。 -この場合は、パラメータ名がなかったので、使用されていないパラメータの慣習に従って `_` を付加しています。 +この場合は、パラメータ名がなかったので、未使用パラメータの慣習に従って `_` を付加しています。 `cargo fix`は常に自動的にコードを修正してくれるわけではありません。 -もし、`cargo fix`がコードを修正できない時にはコンソールに修正できなかったという警告を表示します。 -その場合は手動でコードを修正してください。 -「[発展的な移行戦略]」の章では、移行に関するより多くの情報があります。また、このガイドの他の章では、どのような変更が必要かについても説明しますので、併せてご参照ください。 +`cargo fix` がコードを修正できない場合、コンソールに修正できなかったという警告を表示します。 +そのときは手動でコードを修正してください。 +「[発展的な移行戦略]」の節には、移行に関する詳細情報があります。 +また他の節では、どのような変更が必要かについても説明していますので、併せてご参照ください。 問題が発生したときは、[ユーザーフォーラム](https://users.rust-lang.org/) で助けを求めてください。 + +## 新エディションでテストを実行する + -次に、新しいエディション上であなたのプロジェクトをテストしましょう。 +次に、新しいエディション上でプロジェクトのテストを実行しましょう。 [`cargo test`] を実行するなどして、プロジェクトのテストを走らせ、すべてが元のまま動くことを確認してください。 新たに警告が出た場合、(`--edition` なしの) `cargo fix` をもう一度実行することで、コンパイラからの提案を受け入れてみるのも良いかもしれません。 + + +ここでも手動での変更が必要となる場合があります。たとえば、自動移行では doctest は修正されませんし、ビルド時コード生成やマクロなどは自分で書き換える必要があるかもしれません。 +詳しくは「[発展的な移行戦略]」の節をご参照ください。 + わーい。今やあなたのコードは Rust 2015 と Rust 2018 の両方で有効です! + + + + +## Rustfmt を用いてフォーマットする + + + +コードのフォーマットに [rustfmt] を利用しているなら、新エディションの新しいフォーマット規則に従ってフォーマットを実行すべきでしょう。 + + + +`git` などのバージョン管理システムを使っているなら、フォーマット実行前に現時点で一旦コミットしておくとよいでしょう。 +フォーマットの変更を別のコミットに分けておくと、コード整形とコードの書き換えを見分けたり、`git blame` でフォーマットの変更を無視したりと、後々役に立つかもしれません。 + +```console +cargo fmt +``` + + + +詳細は、[rustfmt の変更] に関する節をご参照ください。 + + + +[rustfmt]: https://github.com/rust-lang/rustfmt +[rustfmt の変更]: ../rust-2024/rustfmt-style-edition.md + + + +## 安定化されていないエディションに移行する + + + +エディションのリリース後、次のエディションが出るまでざっと3年かかります。 +それまでに、新機能が次期エディションに追加されることがあります。このエディションは [nightly チャンネル]限定です。 +新機能の安定化前の試用に協力したい場合、nightly チャンネルを使うとよいです。 + + + +基本的には手順は stable チャンネルと同様です。 + + + +1. `rustup update nightly` で最新の nightly をインストールします。 +2. `cargo +nightly fix --edition` を実行します。 +3. `Cargo.toml` を編集して、`cargo-features = ["edition20xx"]` を最上部に(`[package]` より前に)記述して、`edition = "20xx"` のように edition フィールドを書き換えます(`20xx` は移行先のエディション)。 +4. `cargo +nightly check` を実行して、新エディションでも問題ないことを確認します。 + + + +> **⚠ 注意**: 次期エディションに実装された機能は、ものによっては `cargo fix` による自動移行が使えなかったり、機能自体が未完成だったりします。 +> 本ガイドでは、nightly に実装されている機能の十分な情報や開発状況を可能な限り説明します。 +> エディションが安定化される数ヶ月前までには、全ての新機能が完全に実装され、[Rust Blog] で試用が呼びかけられます。 + [`cargo fix`]: ../../cargo/commands/cargo-fix.html [`cargo test`]: ../../cargo/commands/cargo-test.html [発展的な移行戦略]: advanced-migrations.md -[nightly channel]: ../../book/appendix-07-nightly-rust.html +[nightly チャンネル]: ../../book/appendix-07-nightly-rust.html +[Rust Blog]: https://blog.rust-lang.org/