Rust と TOML

はじめに

Rust のプロジェクトを効率的に管理するためには、設定ファイルの理解が欠かせません。Rust のビルドツール兼パッケージ管理ツールである Cargo は、設定ファイルとして TOML 形式を採用しています。

この記事では、TOML と Cargo.toml について説明します。

TOML

TOML（Tom's Obvious, Minimal Language） は設定ファイルのフォーマットの 1 つです。.toml の拡張子をもちます。

Rust の cargo では、プロジェクトの設定を TOML 形式で記述します。

TOML の基本的な構文は、キーと値の組み合わせからなり、テーブルを使って階層的な構造を表現します。

以下は簡単な TOML ファイルの例です。

example.toml

[owner]
name = "John Doe"
dob = 1998-01-21

[database]
server = "localhost"
port = 8080

# This is a TOML comment

この例では、owner テーブルと database テーブルがあり、それぞれのテーブル内でキーと値が指定されています。以下のような階層構造を持ちます。

階層構造

    ┌── owner/
    │   ├── name: "John Doe"
    │   └── dob: 1998-01-21
    └── database/
        ├── server: "localhost"
        └── port: 8080

テーブル名やキー名は、大文字と小文字を区別します。

値は、以下のいずれかの種類である必要があります。JSON よりも種類が多いです。

• 文字列（UTF-8 文字）: "fruit", 'C:\Users\nodejs'
• 整数: 32, -7
• 浮動小数点数: 3.14, 1e07
• ブール値: true, false
• オフセット付き日時: 2020-05-27T00:32:00-07:00
• ローカルの日時: 1979-05-27T07:32:00
• ローカルの日付: 1979-05-27
• ローカルの時刻: 07:32:00
• 配列: [ 0, 1, 2 ], [ [ 0, 1 ], ["x", "y", "z"] ]
• インライン テーブル: { first = "Taro", last = "Yamada" }

また、ハッシュ記号 (#) でコメントを記述することもできます。

TOML の細かな仕様については TOML: v1.0.0 を参考にしてください。

Cargo ではテーブルはセクション、キーはフィールドと呼ばれています。

Cargo.toml

Cargo.toml は cargo の設定ファイルで、プロジェクトの依存関係やビルド構成がここで管理されます。

Cargo.toml

[package]
# プロジェクトの実際の名前 (プロジェクトのディレクトリ名やGitのレポジトリ名と同じである必要はない)
name = "hello_world"
# プロジェクトのバージョン (セマンティック・バージョニングを採用)
# 詳しくは https://semver.org/ を参照
version = "0.1.0"
# プロジェクトがどのバージョンの Rust を対象としているかを明示
edition = "2021"

[dependencies]
# 依存関係を管理

[package] セクションにはプロジェクトのメタデータを設定します。必須なフィールドは name フィールドのみです。

• name フィールドの値は英数字または - または _ のみで構成されている必要があります。
• version フィールドのデフォルトの値は 0.0.0 です。パッケージを公開する場合にはこのフィールドは必須です。
• version フィールドでは、プロジェクトがどのバージョンの Rust を対象としているかを明示します。

[dependencies] セクションはプロジェクトが依存するクレート（ライブラリ）を指定します。

依存関係の追加・バージョン指定

• 依存関係の追加
  新しい依存関係を追加するには、[dependencies] セクションにクレート名とそのバージョンを指定します。

[dependencies]
# time クレートのバージョン 0.3.36 を追加
time = "0.3.36"

• バージョン指定
  バージョン指定には複数の方法があります。固定バージョン指定、範囲指定などがあります。

# 固定バージョン指定
# バージョン 0.3.36 のみを使用することを示す
time = "0.3.36"

# 範囲指定
# バージョン0.3.x（例えば、0.3.0、0.3.1、0.3.36など）の最新バージョンを選択
time = "0.3"

他にも、比較演算子や波ダッシュ、キャレットを使用した指定方法があります。

参考資料

Cargo に関する仕様については The Manifest Format - The Cargo Book や Specifying Dependencies - The Cargo Book を参考にしてください。

セマンティック・バージョニングについては Semantic Versioning を参考にしてください。