Cargo.tomlでGitHubリポジトリを参照するときのオプションの指定方法とリポジトリの構成を調査する

booink

Cargo.tomlでGitHubリポジトリを参照する方法。

クレート名のあとに { git = "https://github.com/booink/public-crate" } を指定する。

{} 内が git 指定のみなら main ブランチを参照する。

booink

{} 内には以下の属性が指定できる。

rev: リビジョン、コミットID
branch: ブランチ名
tag: タグ名

ブランチ名、タグ名以外の指定可能な値はすべて rev に指定する。

rev = "4c59b707"
rev = "refs/pull/493/head"

booink

今回何が気になって調査しようとしているかと言うと、

特定のセマンティックバージョンを指定して使用できるか
バージョンが指定できる場合、リポジトリ側ではどのように構成するべきか
- tagを使うのか、artifactのようなものを使うのかなど

理想的には、利用側でCargo.tomlに指定したバージョンのRustライブラリが意図した通りに使えれば良い。
リポジトリ側で必要なガイドラインや方法があるなら、それに倣って構築するまで。

booink

ここでは git と version が両方指定されている。

# Uses the given git repo when used locally, and uses
# version 1.0 from crates.io when published.
smallvec = { git = "https://github.com/servo/rust-smallvec", version = "1.0" }

上のコメントの部分を読んでみると

Uses the given git repo when used locally, and uses version 1.0 from crates.io when published.
ローカルで使用する場合は与えられたgit repoを使用し、公開する場合はcrates.ioのバージョン1.0を使用します。

利用側のプロジェクトをローカルで使用する、つまり公開せずに閉じた環境で使う場合は git リポジトリのコードを参照して、このプロジェクトをクレートとして公開する場合は crates.io などのレジストリに登録されている version 1.0 のコードが使用される、ということなのか。

さらにコードサンプルの下の説明を読んでみる。

One example where this can be useful is when you have split up a library into multiple packages within the same workspace. You can then use path dependencies to point to the local packages within the workspace to use the local version during development, and then use the crates.io version once it is published. This is similar to specifying an override, but only applies to this one dependency declaration.
この方法が有効な例としては、同じワークスペース内でライブラリを複数のパッケージに分割している場合があります。その場合、パス依存関係を使ってワークスペース内のローカルパッケージを指し、開発中はローカルバージョンを使用し、公開されたらcrates.ioのバージョンを使用することができます。これはオーバーライドの指定に似ていますが、この1つの依存性宣言にのみ適用されます。

なるほど。ワークスペースで分割しているプロジェクトに有効だ。
確かにクレートの開発中は、レジストリに公開済みのバージョンはローカルやgitで管理しているコードより古いし、公開したときは最新版として意図したバージョンを指しておいてもらわないと困る。
めちゃくちゃ合理的な仕組み。

だが、今回調査している目的には合わないので、この方法は使えない。

booink

version 指定が使えないなら、バージョンのtagを打っておいてそのバージョンを指定するのが良さそう。
revでもbranchでもいいけど。

あと気になるのは、複数のクレートで同じリポジトリを指す別バージョンを指定して、意図した読み込みが行われているか。を調査する。

booink

検証用のリポジトリ
https://github.com/booink/public-crate

booink

クレート利用側の検証用リポジトリ

booink

public-crate の crate-test-1 だけを 1.1.0 に Bump up して v1.1.0 タグを切った。

利用側では crate-test-1 だけ v1.1.0 を使うように指定した。

Cargo.lock を見ると、tagによって違うコミットが使われていて、それぞれのクレートのversionも意図したバージョンになっているのがわかる。

Cargo.lock

[[package]]
name = "crate-install-test"
version = "0.1.0"
dependencies = [
 "crate-test-1",
 "crate-test-2",
]

[[package]]
name = "crate-test-1"
version = "1.1.0"
source = "git+https://github.com/booink/public-crate?tag=v1.1.0#ae764159e1281619fb51035ec93f08826cd50c74"

[[package]]
name = "crate-test-2"
version = "1.0.0"
source = "git+https://github.com/booink/public-crate?tag=v1.0.0#5538e355ae4018751cca2ba159054f4b3b6a8bf5"

booink

利用側で crate-test-2 も v1.1.0 を使うように指定してみる。

Cargo.lock

 [[package]]
 name = "crate-test-2"
 version = "1.0.0"
-source = "git+https://github.com/booink/public-crate?tag=v1.0.0#5538e355ae4018751cca2ba159054f4b3b6a8bf5"
+source = "git+https://github.com/booink/public-crate?tag=v1.1.0#ae764159e1281619fb51035ec93f08826cd50c74"

tagの向き先だけが変わって、versionは 1.0.0 のままなので、意図通り。