Cargo.toml を壊れたままにしない

具体例

具体例を見てみましょう。

            [package]
name = "test-dep"
version = "0.0.0"
edition = "2018"

[dependencies]
libflate = "1"
          

            $ cargo check
    Updating crates.io index
   Compiling crc32fast v1.2.1
    Checking cfg-if v1.0.0
    Checking rle-decode-fast v1.0.1
    Checking libflate_lz77 v1.0.0
    Checking adler32 v1.2.0
    Checking libflate v1.0.3
    Checking test-dep v0.0.0 (/run/user/1000/deptest/po)
    Finished dev [unoptimized + debuginfo] target(s) in 3.21s
$
          

            $ cargo tree
test-dep v0.0.0 (/run/user/1000/deptest/po)
└── libflate v1.0.3
    ├── adler32 v1.2.0
    ├── crc32fast v1.2.1
    │   └── cfg-if v1.0.0
    ├── libflate_lz77 v1.0.0
    └── rle-decode-fast v1.0.1
$
          

libflate = "1" と指定すると、先に解説したように 1.0.0 と互換な任意のバージョンを使えると cargo に伝えることになります。 cargo は最初のビルドや cargo update 等の機会に、利用可能な中で最新のバージョンを取得します。 2020-12-13 時点では v1.0.3 が最新で、これが利用されていることがメッセージからわかります。

さて、これでコンパイルが通ったからといって cargo publish してしまう人は多いのでしょうが、実はこの Cargo.toml は壊れているのです。 実際に確認してみましょう。

            $ cargo +nightly update -Z minimal-versions
    Updating crates.io index
    Updating adler32 v1.2.0 -> v1.0.0
    Removing cfg-if v1.0.0
    Updating crc32fast v1.2.1 -> v1.0.1
    Updating libflate v1.0.3 -> v1.0.0
    Updating rle-decode-fast v1.0.1 -> v1.0.0
      Adding rustc_version v0.2.0
      Adding semver v0.6.0
      Adding semver-parser v0.7.0
$
          

            $ cargo tree
test-dep v0.0.0 (/run/user/1000/deptest/po)
└── libflate v1.0.0
    ├── adler32 v1.0.0
    ├── crc32fast v1.0.1
    │   [build-dependencies]
    │   └── rustc_version v0.2.0
    │       └── semver v0.6.0
    │           └── semver-parser v0.7.0
    ├── libflate_lz77 v1.0.0
    └── rle-decode-fast v1.0.0
$
          

            $ cargo check
   Compiling semver-parser v0.7.0
    Checking rle-decode-fast v1.0.0
    Checking adler32 v1.0.0
   Compiling semver v0.6.0
   Compiling rustc_version v0.2.0
   Compiling crc32fast v1.0.1
error[E0277]: the trait bound `Version: From<({integer}, {integer}, {integer})>` is not satisfied
 --> /home/lo48576/.cargo/registry/src/github.com-1ecc6299db9ec823/crc32fast-1.0.1/build.rs:8:30
  |
8 |     if version >= (1, 27, 0).into() {
  |                              ^^^^ the trait `From<({integer}, {integer}, {integer})>` is not implemented for `Version`
  |
  = help: the following implementations were found:
            <Version as From<semver_parser::version::Version>>
  = note: required because of the requirements on the impl of `Into<Version>` for `({integer}, {integer}, {integer})`

error: aborting due to previous error

For more information about this error, try `rustc --explain E0277`.
error: could not compile `crc32fast`

To learn more, run the command again with --verbose.
$
          

何が起きているかというと、 Rust コンパイラである rustc の --version オプションの出力が rustc 1.29.0 から変化したのですが、ビルド時依存である rustc_verison crate の v0.2.0 がこれに対応しておらず、結果コンパイルエラーとなるのです。 この問題は crc32fast crate の v1.1.1 以降で対処されているのですが、当然この問題が存在しなかった時代の人々が Cargo.toml で事前にこれに対処することはできません。 つまり後から壊れてしまったビルドは、後世の人々が気付いて修正するしかないのです。

この例の場合であれば libflate v1.0.1 で対処済^[1]ですから、 Cargo.toml で libflate = "1.0.1" を指定してやれば問題なくコンパイルが通るであろうと予想できます。

            [package]
name = "test-dep"
version = "0.0.0"
edition = "2018"

[dependencies]
libflate = "1.0.1"
          

            $ cargo +nightly update -Z minimal-versions
    Updating crates.io index
    Updating crc32fast v1.0.1 -> v1.1.1
    Updating libflate v1.0.0 -> v1.0.1
    Removing rustc_version v0.2.0
    Removing semver v0.6.0
    Removing semver-parser v0.7.0
$
          

            $ cargo tree
test-dep v0.0.0 (/run/user/1000/deptest/po)
└── libflate v1.0.1
    ├── adler32 v1.0.0
    ├── crc32fast v1.1.1
    ├── libflate_lz77 v1.0.0
    └── rle-decode-fast v1.0.0
$
          

            $ cargo check
   Compiling crc32fast v1.1.1
    Checking libflate v1.0.1
    Checking test-dep v0.0.0 (/run/user/1000/deptest/po)
    Finished dev [unoptimized + debuginfo] target(s) in 0.82s
$
          

Cargo.tomlが壊れているということ

先の具体例で見たように、文法的に正しく、普通に実行してもビルドが通るような Cargo.toml についても、サイレントに壊れている場合があります。 ここでいう壊れているとは、Cargo.toml で指定された制約に従って依存 crate を準備したのにビルドが通らないということです。 こういった壊れ方は cargo update 等により症状が隠れてしまう場合もあり、見逃されがちです。

このような壊れた Cargo.toml の発生要因としては、以下のようなものが考えられます。

新しい依存を追加するときは、古いものではなく最新のバージョンを明示的に指定する

依存 crate のバージョンは不必要に緩くすべきではありません。 現状で利用可能な、あるいは利用するつもりの API を持つバージョンのうちで、最新のものをパッチバージョンまで含めて (つまり "x.y.z" の形で) 指定しましょう。

たとえば libflate への依存を新たに追加したいのであれば、 libflate = "1" と書くのではなく libflate = "1.0.3" のように最新のものを指定すべきでしょう。 なぜならあなたはこれから libflate v1.0.0 を用いて実装するのではなく、 v1.0.3 で実装と動作確認を行うことになるからです。

あるいは serde を例に出してもいいかもしれません。 気をきかせたつもりで serde = "1" と書くのは簡単ですが、本当に serde v1.0.0 や serde_derive v1.0.0 でビルドできることを保証したいのですか？ serde v1.0.1 以降の追加・修正を必要としないコードを書いている確信があるのですか？ そのつもりがないなら、軽率に serde = "1" のような緩い制約を指定すべきではありません。

ローカルで検査する

要は制約が不必要に緩いのが問題なのであって、こういう場合手っ取り早くやるにはエッジケースでテストをするものと相場が決まっています [要出典]。 ここでいうエッジケースとは、すなわち最新のバージョンと最古のバージョンです^[3]。

最新のバージョンを cargo update で利用できるのは言うまでもありませんが、最古のバージョンを利用させる Cargo.lock の生成には nightly ツールチェインが必要です。 これは Cargo.lock の生成だけに必要で、一度生成してしまえば他の部分で nightly を使う必要はありません。

cargo +nightly update -Z minimal-versions を実行して Cargo.lock を生成し、しかるのちに cargo check や cargo testなどしましょう。 それだけです。

また、もし feature flag などによって追加の依存が発生することがあるなら、ビルド時に適宜 --no-default-features とか --all-features とかの有無のバリエーションも含めてテストするのが良いかと思います。 特定の feature を有効化したらビルドできなくなったとか悲しいので。

CI で自動的に検査する

GitHub や GitLab などメジャーな git リポジトリホスティングサービスは CI との連携機能を提供しており、 OSS については無料で利用可能な場合が多いです。 せっかくなので、単に最新の依存でビルドできるかだけではなく、制約を満たす最古のバージョンでビルドできるかも自動的に検査しましょう。

手順としては簡単で、ビルドやテストの前に rust の nightly ツールチェインをインストールし、 cargo +nightly update -Z minimal-versions を実行するだけです。 手動でやることとほとんど変わりません。 これにより所望の Cargo.lock が生成されるので、後の工程では nightly ツールチェインは不要です。 普通に stable なり beta なり MSRV なりで cargo check や cargo test を実行しましょう。

          # Template for test stage.
.test_template: &test
  stage: test
  before_script:
    # Use dependencies with minimal versions, if `USE_MINIMAL_VERSIONS` is nonzero.
    - if [ "${USE_MINIMAL_VERSIONS:-0}" -ne 0 ] ; then
        rustup install nightly &&
        cargo +nightly update -Z minimal-versions ;
      fi

# (snip)...

test:msrv:all-features-minimal-versions:
  <<: *test_msrv
  variables:
    FEATURES: --all-features
    USE_MINIMAL_VERSIONS: 1
        

          before_install:
  # (snip)...
  - |
    if [ "${TEST_MINIMAL_VERSIONS:-0}" -ne 0 ] ; then
        rustup install nightly
    fi
before_script:
  # Use dependencies with minimal versions.
  - |
    if [ "${TEST_MINIMAL_VERSIONS:-0}" -ne 0 ] ; then
        cargo +nightly update -Z minimal-versions
    fi
        

依存 crate に問題を発見したら報告する (可能ならパッチを投げる)

残念ながら、自分の書いた Cargo.toml でなく依存 crate での指定に問題があった場合、自分のプロジェクトでの CI が失敗することがあります。 このような場合、問題を報告しましょう。 気付いたあなたが直すのです。

というか私も何度かそういうパッチを投げたことがあり、もしや Cargo.toml の破壊という概念に誰も気付いていないのでは？？？ と思ったのでこの記事を書いています。 各位たのむ〜。

とはいえ、依存 crate の問題とはいっても、依存の連鎖を深く辿らないと原因の crate が出てこなかったり、問題が起きなくなる最小のバージョンを二分探索や CHANGELOG 確認で探したり、複数 crate が同時に壊れていたりなど、解決に手間がかかるケースもあります。 べつに本質的な難しさがあるわけではないのですが単純に面倒だったりするので、無理に頑張って諦めたり放置するくらいならまずは issue だけでも報告してしまいましょう。

README.md 等で不正確なバージョンでの案内をしない

よく README.md で「Cargo.toml に foo = "1.2" と書くと、この crate が利用できるようになりますよ〜」みたいな案内がある crate をよく見掛けます。 ここで不正確なバージョン番号を提示してあると、何も考えずそれを使って将来的に壊れるなどというケースがありえるので、ちゃんと正確な ("1.2.3" のような) バージョンを記載しましょう。 リリース前のバージョン番号更新忘れにも注意です。

そもそもの話をしてしまうと、私はあの案内は普通に不要だと思うのです。 単にコマンドをインストールしたいユーザならともかく、 Rust で物を書こうという人はたぶん TRPL とかを読んでると思うんですよね。 リリース毎に更新すべき箇所を断片的に増やして案の定忘れたりするくらいなら、最初からこんな基礎的で誤りやすい案内はない方がマシだと思います。 README で案内せずとも crates.io に Cargo.toml に追加すべき記述は掲載されているわけですからね。

README で最新のバージョンを提示するだけなら https://img.shields.io/crates/v/{{crate_name}}.svg を使うことでバッヂ画像を取得できます。 たとえば serde なら https://img.shields.io/crates/v/serde.svg といった具合です。 これを README の天辺に貼り付けて crates.io へのリンクにしておけば、バージョンの案内としては十分でしょう。

          [![Latest version](https://img.shields.io/crates/v/datetime-string.svg)](https://crates.io/crates/datetime-string)