【Rust】Cargo.toml チートシート

package セクション

[package]
name = "hello_world"
version = "0.1.0"
edition = '2021'

name フィールド

パッケージの識別名となり、必須フィールドである アルファベット・数字・- ・ _ が利用可能 crates.io で公開する場合は以下に従う必要がある

• ASCII 文字のみ
• 予約語を使用してはならない
• nul のような Windows の特殊名を使用してはならない
• 64文字以下

version フィールド

Semantic Versioningに従うバージョン番号 省略時はデフォルトの 0.0.0 となる

edition フィールド

どの Rust Edition でコンパイルするかを指定するオプションフィールド

[package]
edition = '2021'

rust-version フィールド

 Rust 1.56.0 以降で有効なパッケージをコンパイルできる Rust 言語とコンパイラのバージョンを指定するオプションのキー

[package]
rust-version = "1.56"

authorsフィールド

パッケージの作成者とみなされる人物または組織を配列でリストするオプションのフィールド 公開済みのパッケージマニフェストは変更できないため、公開時には正確な値を設定する

[package]
authors = ["Graydon Hoare", "Fnu Lnu <no-reply@rust-lang.org>"]

description フィールド

パッケージの短い説明をプレーンテキストで設定。crates.io への公開時には必須

[package]
description = "A short description of my package"

documentation フィールド

クレートのドキュメントをホストする Web サイトへの URL を指定

[package]
documentation = "https://docs.rs/bitflags"

homepage フィールド

パッケージのホームページURLを指定

[package]
homepage = "https://serde.rs/"

repository フィールド

パッケージのソースリポジトリのURLを指定

[package]
repository = "https://github.com/rust-lang/cargo/"

readme フィールド

README ファイルパスを指定。指定が無い場合は、パッケージルートの README.md, README.txt または README が自動で選択されるため、値を設定するケースは少ない

[package]
readme = "README.md"

license フィールド

SPDX license list 3.20に定義されたライセンス名を指定。crates.io への公開時には必須。 複数ライセンスの場合は AND と OR で連結する

[package]
license = "MIT OR Apache-2.0"

以下のようにライセンスファイルを指定することもできる。

[package]
license-file = "LICENSE.txt"

keywords フィールド

レジストリでパッケージを検索する際のキーワードを指定

[package]
keywords = ["gamedev", "graphics"]

crates.io では最大 5 つのキーワードが許可される(ASCII テキストで、最大 20 文字で、英数字で始まり、文字、数字、または _ , -, + のみを許容)。

categories フィールド

このパッケージが属するカテゴリの文字列の配列

[package]
categories = ["command-line-utilities", "development-tools::cargo-plugins"]

crates.io では最大 5 つのカテゴリがあり、https://crates.io/category_slugsの定義に一致する必要がある

workspace フィールド

このパッケージがワークスペースのメンバになる場合に、ワークスペースのルートクレートのパスを指定(このパッケージがワークスペース ルートのサブディレクトリ外に位置する場合に指定)。

[package]
workspace = "path/to/workspace/root"

[workspace] セクションを定義している場合は、workspace フィールドを指定することはできない。

build フィールド

ネイティブコードをビルドするための(パッケージルートに位置する)ビルドスクリプトファイルを指定する。

[package]
build = "custom_build_name.rs"

デフォルトは "build.rs" であり、build = false とすることでスクリプトファイルの自動検出を無効化できる。

links フィールド

リンクするネイティブライブラリの名前を指定。

[package]
links = "git2"

exclude include フィールド

プロジェクトをパッケージングして公開するときに含めるファイルや、特定の種類の変更追跡を行うファイルを明示的に指定する。

[package]
exclude = ["/ci", "images/", ".*"]
include = ["/src", "COPYRIGHT", "/examples", "!/examples/big_example"]

どのファイルがパッケージに含まれるかは以下で確認できる。

cargo package --list

publish フィールド

パッケージを公開するレジストリを指定する。

[package]
publish = ["some-registry-name"]

publish = false とすることで誤ってパッケージをレジストリに公開してしまうことを防ぐことができる。

default-run フィールド

cargo run の実行対象を指定する。src/bin/a.rs と src/bin/b.rs が存在した場合は以下のように指定する。

[package]
default-run = "a"

resolver フィールド

feature のリゾルバーアルゴリズムを指定する。

[package]
resolver = "2"

Cargo 1.50 まではバージョン"1"リゾルバーであり、現在は"2"。 リゾルバーはグローバル オプションであり、ワークスペースを利用する場合は[workspace] セクションで指定する必要がある。

[workspace]
members = ["member1", "member2"]
resolver = "2"

auto-discovery フィールド

Cargo ではパッケージレイアウトに応じてビルドターゲットを自動的に決定する(ターゲットの設定は後述のターゲットテーブル([lib], [[bin]], [[test]], [[bench]], [[example]])で個別設定可能)。 自動検出を無効とするには以下のように設定する。

[package]
autobins = false     # Disables binary auto discovery
autoexamples = false # Disables example auto discovery
autotests = false    # Disables test auto discovery
autobenches = false  # Disables bench auto discovery

Target テーブル

ターゲットのビルド方法をカスタマイズするには、[lib], [[bin]], [[example]], [[test]],  [[bench]] セクションを構成する。 これらのセクションには以下のフィールドを利用できる(ここでは[lib]セクションを例に記載)。

[lib]
name = "foo"           # The name of the target.
path = "src/lib.rs"    # The source file of the target.
test = true            # Is tested by default.
doctest = true         # Documentation examples are tested by default.
bench = true           # Is benchmarked by default.
doc = true             # Is documented by default.
plugin = false         # Used as a compiler plugin (deprecated).
proc-macro = false     # Set to `true` for a proc-macro library.
harness = true         # Use libtest harness.
edition = "2015"       # The edition of the target.
crate-type = ["lib"]   # The crate types to generate.
required-features = [] # Features required to build this target (N/A for lib).

[[]] のようなダブルブラケットセクションは array-of-table of TOML であり、同じセクションを複数定義できる。 一方[lib]は通常のTOMLテーブルのため、1つしか指定できない。

dependency テーブル

Cargo は、デフォルトで crates.io の依存関係を対象とする。 加えてローカル ファイル システム上の他のレジストリ、gitリポジトリ、サブディレクトリに依存することができる

dependencies セクション

名前とバージョン文字列を指定し、crates.io に公開されたクレートへの依存を定義する。

[dependencies]
time = "0.1.12"

crates.io 以外のレジストリを使用するには、.cargo/config.toml でレジストリを定義し、依存関係で、registry キーを使用する(crates.io では外部に依存したパッケージは公開できない)。

[dependencies]
some-crate = { version = "1.0", registry = "my-registry" }

gitリポジトリ内にあるライブラリに依存する場合は以下のように指定する。

[dependencies]
regex = { git = "https://github.com/rust-lang/regex.git" }

rev、tag、branch を指定することもできる。例えば next ブランチを指定する場合は以下となる。

[dependencies]
regex = { git = "https://github.com/rust-lang/regex.git", branch = "next" }

プロジェクト内にサブクレートを作成し、そのパスで依存関係を指定するこもできる。

[dependencies]
hello_utils = { path = "hello_utils" }

プラットフォーム毎の依存関係を定義する場合は以下のようになる([target.*.dependencies] セクション)。

[target.'cfg(windows)'.dependencies]
winhttp = "0.4.0"

[target.'cfg(unix)'.dependencies]
openssl = "1.0.1"

[target.'cfg(target_arch = "x86")'.dependencies]
native-i686 = { path = "native/i686" }

[target.'cfg(target_arch = "x86_64")'.dependencies]
native-x86_64 = { path = "native/x86_64" }

依存には feature を指定できる(クレートのオプション機能を取捨選択)。serde の derive 機能を有効化する場合は以下のようになる。

[dependencies]
serde = { version = "1.0.118", features = ["derive"] }

デフォルトの機能を無効化して、特定の機能のみを選択する場合は以下のようになる。

[dependencies]
flate2 = { version = "1.0.3", default-features = false, features = ["zlib"] }

dev-dependencies セクション

開発の依存関係を[dependencies]と同様の形式で追加する。

[dev-dependencies]
tempdir = "0.3"

開発依存関係は、test、example, bench をコンパイルするために使用される。これらの依存関係は、このパッケージに依存する他のパッケージには伝播されない。

以下のようにターゲット固有の開発依存関係を定義することもできる。

[target.'cfg(unix)'.dev-dependencies]
mio = "0.0.1"

build-dependencies セクション

ビルドスクリプトで使用する他の Cargo ベースのクレートへの依存関係を[dependencies]と同様の形式で追加する。

[build-dependencies]
cc = "1.0.3"

以下のようにターゲット固有の開発依存関係を定義することもできる。

[target.'cfg(unix)'.build-dependencies]
cc = "1.0.3"

バージョン番号定義

バージョン番号は、1.0.0 以降は SemVer に従う。1.0.0 より前のバージョンを指定した場合の互換性範囲は以下のようになる。

1.2.3  :=  >=1.2.3, <2.0.0
1.2    :=  >=1.2.0, <2.0.0
1      :=  >=1.0.0, <2.0.0
0.2.3  :=  >=0.2.3, <0.3.0
0.2    :=  >=0.2.0, <0.3.0
0.0.3  :=  >=0.0.3, <0.0.4
0.0    :=  >=0.0.0, <0.1.0
0      :=  >=0.0.0, <1.0.0

チルダを指定した場合は以下の互換性範囲となる。

~1.2.3  := >=1.2.3, <1.3.0
~1.2    := >=1.2.0, <1.3.0
~1      := >=1.0.0, <2.0.0

ワイルドカードを指定した場合は以下の互換性範囲となる。

*     := >=0.0.0
1.*   := >=1.0.0, <2.0.0
1.2.* := >=1.2.0, <1.3.0

features セクション

条件付きコンパイルやオプションの依存関係を表現するメカニズムを提供する

webp という機能は以下のように定義する。

[features]
webp = []

ソース上では以下のように条件付きでコードの取り込みを制御できる。

#[cfg(feature = "webp")]
pub mod webp;

default でデフォルトの feature を定義でき、features 間の依存は ico = ["bmp", "png"] のように指定する。

[features]
default = ["ico", "webp"]
bmp = []
png = []
ico = ["bmp", "png"]
webp = []

feature はコマンドラインフラグにより、どの機能を有効にするかを制御できる。 * --features FEATURES : リストされた機能を有効する(カンマまたはスペースで区切り --features "foo bar") * --all-features: すべての機能をアクティブ化 * --no-default-features : 選択したパッケージの default 機能を有効にしない

lints.* セクション

lint のデフォルトレベルを上書き設定する。

[lints.rust]
unsafe_code = { level = "forbid", priority = 0 }
# unsafe_code = "forbid" のように省略系でも可

[lints.clippy]
enum_glob_use = "deny"

level には forbid, deny, warn, allow がある priority は符号付き整数で、小さい値は優先順位が低い。

workspace セクション

workspace により、複数のパッケージをまとめて管理できる。

以下のように定義すると、このパッケージがワークスペースのルートパッケージとなる。

[workspace]

[package]
name = "hello_world"
version = "0.1.0"

ルートには Cargo.toml(virtual manifest) だけを用意し、

# [PROJECT_DIR]/Cargo.toml
[workspace]
members = ["hello_world"]
resolver = "2"

サブディレクトリにパッケージを構成する形式も可。

# [PROJECT_DIR]/hello_world/Cargo.toml
[package]
name = "hello_world"
version = "0.1.0"

ワークスペースセクションには以下を定義できる

• resolver 使用する依存関係リゾルバー
• members ワークスペースに含めるパッケージ
• exclude ワークスペースから除外するパッケージ
• default-members 特定のパッケージが選択されていない場合に操作するパッケージ
• package パッケージ内で継承するためのキー
• dependencies パッケージの依存関係を継承するためのキー
• lintsパッケージ lint で継承するためのキー
• metadata 外部ツールの追加設定

patch セクション

crates.io などに公開前のクレートを使ってテストを行うなどの用途で、[dependencies] で定義した依存関係をオーバーライドする。

以下のような依存があり、

[dependencies]
uuid = "1.0"

crates.io 公開前にリポジトリをローカルに clone した場合、以下のようにしてローカルのリポジトリへの依存にオーバーライドすることができる。

[patch.crates-io]
uuid = { path = "../path/to/uuid" }

一時的な場合は、--config 'patch.crates-io.rand.path="rand"'のようにコマンドラインから構成することもできる。

Git リポジトリを指定する場合は以下

[patch.crates-io]
foo = { git = 'https://github.com/example/foo.git' }

依存関係がgit依存の場合、以下のようにローカルパスにオーバーライドすることができる。

[patch."https://github.com/your/repository"]
my-library = { path = "../my-library/path" }

profile.* セクション

最適化やシンボルのデバッグなどに影響を与えるコンパイラ設定を変更する。

Cargo には、dev, release, test, bench の4 つの組み込みプロファイルがある。

[profile.dev]
opt-level = 1               # Use slightly better optimizations.
overflow-checks = false     # Disable integer overflow checks.

ワークスペースを構成している場合は、ルートの設定のみが有効

以下のプロファイルが利用できる。

• opt-level 最適化レベル
• debug デバッグ情報の量
• split-debuginfo デバッグ情報が生成された場合に、それを実行可能ファイル自体に配置するか、実行可能ファイルに隣接して配置するか
• strip rustc にバイナリからシンボルまたは debuginfo を削除する
• debug-assertions 条件付きコンパイルをオンまたはオフにする
• overflow-checks 実行時の整数オーバーフローの動作を制御
• lto LLVM のリンク時間の最適化を制御
• panic どのパニック戦略を使用するかを制御
• incremental インクリメンタル コンパイルが有効かどうかを制御
• codegen-units クレートをいくつの「コード生成ユニット」に分割するかを制御
• rpath 実行時 検索パスを制御

package.metadata.* セクション

package.metadata テーブルは、外部ツール用の設定を Cargo.toml に保存するために使用できる(package.metadata テーブルは Cargoによって完全に無視る)。

[package]
name = "..."
# ...

[package.metadata.android]
package-name = "my-awesome-android-app"
assets = "path/to/static"

ワークスペースレベルでは、workspace.metadata テーブルが利用できる。

Rustの練習帳 ―コマンドラインツールの作成を通してRustを学ぶ

プログラミングRust 第2版