Rustのパッケージ、クレート、モジュールに関するドキュメントを読む

これは、なにをしたくて書いたもの？

前にRustのGetting Startedの「Command line apps in Rust」をざっくり試してみました。

Getting started - Command Line Applications in Rust

RustのGetting Started「Command line apps in Rust」を試す - CLOVER🍀

ここでファイルを分割し始めた時に、用語や別のソースコードに定義した関数の呼び出し方がよくわからないぞ？という気分になったので、
このあたりに関するドキュメントを読むことにしました。

こちらです。

Managing Growing Projects with Packages, Crates, and Modules - The Rust Programming Language

なお、コードを使う場合は以下の環境で試しています。

$ rustup --version
rustup 1.27.1 (54dd3d00f 2024-04-24)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: The currently active `rustc` version is `rustc 1.83.0 (90b35a623 2024-11-26)`

Managing Growing Projects with Packages, Crates, and Modules

Rustのパッケージ、クレート、モジュールに関するドキュメントはこちらです。今回はこのページおよびその配下のページを見ていきます。

Managing Growing Projects with Packages, Crates, and Modules - The Rust Programming Language

最初に思ったのですが、このドキュメント内には「プロジェクト」という言葉がほとんど出てきません。

cargo newで作成する単位ってなんなんでしょうね？ドキュメントを見ると「Cargoパッケージ」みたいです。

This command will create a new Cargo package in the given directory.

cargo new - The Cargo Book

Cargo Guide内のドキュメントを見ても、「パッケージ」扱いなのですがパスを見ると前は「プロジェクト」と読んでいたのかもしれません…。

Creating a New Package - The Cargo Book

ここでは「プロジェクト」という言葉は忘れることにします。ドキュメント内にたまに「プロジェクト」という言葉がある単位を指して
出てきますが、「パッケージ」に読み替えることにします。

このページでは、用語がまとめられていますね。

• パッケージ … クレートをビルド、テスト、共有できるCargoの機能のこと
• クレート … ライブラリーまたは実行ファイルを生成するモジュールのツリーのこと
• モジュールとuse … パスの構成、スコープ、プライバシーを制御できる仕組みのこと
• パス … 構造体や関数、モジュールなどの項目に名前をつける方法のこと

Managing Growing Projects with Packages, Crates, and Modules - The Rust Programming Language

配下のページをたどって、順に見ていきましょう。

パッケージとクレート

まずはパッケージとクレートから。

Packages and Crates - The Rust Programming Language

用語としてはこうでした。

• パッケージ … クレートをビルド、テスト、共有できるCargoの機能のこと
• クレート … ライブラリーまたは実行ファイルを生成するモジュールのツリーのこと

クレートは、Rustコンパイラーが1度に考慮する最小量のコードだそうです。

A crate is the smallest amount of code that the Rust compiler considers at a time.

クレートはモジュールを含みます。

Crates can contain modules,

また、クレートには次の2種類があります。

• バイナリークレート
  • コマンドラインプログラムやサーバーなど、実行可能な形式にコンパイルできる
  • 実行時に呼び出されるmain関数が必要
• ライブラリークレート
  • 複数のパッケージで共有することを目的とした機能を定義する
    • あるRustプログラムを作成している時に「クレート」という言葉を使う時は、たいていの場合はライブラリークレートを指している
  • main関数はない

パッケージは、ある機能セットを提供するひとつ以上のクレートをまとめたものです。

A package is a bundle of one or more crates that provides a set of functionality.

パッケージから見たクレートに関する話は以下のようです。

• 複数のバイナリークレートを含むことができる
• ライブラリークレートは最大ひとつのみ
• バイナリークレート、ライブラリークレートは問わないが、少なくともひとつのクレートを含む必要がある

そして、クレートルートというものが出てきます。バイナリークレート、ライブラリークレートでそれぞれ以下の名前のようです。

• src/main.rs … バイナリークレートのクレートルート
• src/lib.rs … ライブラリークレートのクレートルート

どちらにも言えますが、src/main.rsであればパッケージと同じ名前のバイナリークレートのクレートルートであり、src/lib.rsであれば
パッケージと同じ名前のライブラリークレートのクレートルートであるという規則に従います。

rustcでコンパイルする時には、クレートルートが基点になるようです。

またパッケージには複数のクレートを含められるということでしたが、以下のようになるみたいです。

• パッケージにsrc/main.rsとsrc/lib.rsの両方が含まれている場合、バイナリークレートとライブラリークレートの2つのクレートが含まれ、どちらもパッケージ名と同じ名前のクレートとなる
• 複数のバイナリークレートを持つ場合は、src/bin配下に配置することで複数のバイナリークレートを含めることができる
  • 各ファイルは個別のバイナリークレートとなる

モジュールの定義とスコープ、プライバシーの制御

次はモジュールの定義とスコープ、プライバシーの制御についてです。

Defining Modules to Control Scope and Privacy - The Rust Programming Language

最初にチートシートがあるので簡単にまとめます。

• コンパイルの基点
  • クレートルート（src/main.rsおよびsrc/lib.rs）から始まる
• モジュールの宣言
  • クレートルートで新しいモジュールを宣言できる
    • 構文はmod [モジュール名];
  • モジュールを宣言すると、コンパイラは次の場所でモジュールのコードを探す
    • src/[モジュール名].rs
    • src/[モジュール名]/mod.rs（古いスタイル）
• サブモジュールの宣言
  • クレートルート以外で宣言されたモジュールのこと
    • 構文はmod [サブモジュール名];（モジュールの宣言と同じ）
  • コンパイラは親モジュールのディレクトリ内でサブモジュールのコードを探す
    • src/[親モジュール名]/[サブモジュール名].rs
    • src/[親モジュール名]/[サブモジュール名]/mod.rs（古いスタイル）
• モジュール内のコードへのパス
  • モジュールがクレートの一部になっている場合、プライバシーで許可されていればそのモジュールを参照可能
• privateとpublic
  • モジュール内のコードはデフォルトでは親モジュールに対してprivateになっている
  • publicなモジュールにするにはmod [モジュール名];の代わりにpub mod [モジュール名];で宣言する
  • publicモジュール内の定義もパブリックにするには、その定義の先頭にpublicを付与する
• use
  • スコープ内で、パスの長い繰り返し表現を減らすための構文

モジュールを使うことで、クレート内のコードを整理したり、ライブラリークレートとして公開するものであっても実装の詳細は
公開しないといった使い方ができるようです。

ドキュメントのサンプルをマネしてみましょう。

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

Cargoパッケージの作成。

$ cargo new backyard
$ cd backyard

サンプルから少し変形して、こんな感じにしました。

$ tree src
src
├── garden
│   └── vegetables.rs
├── garden.rs
└── main.rs

2 directories, 3 files

ソースコードはこんな感じです。

src/main.rs

use backyard::garden::vegetables::Asparagus;
// 以下でも可
use crate::garden::vegetables::Asparagus;

pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("I'm growing {plant:?}!");
}

src/garden.rs

pub mod vegetables;

src/garden/vegetables.rs

#[derive(Debug)]
pub struct Asparagus {}

実行。

$ cargo run
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/backyard`
I'm growing Asparagus!

ルートモジュールのモジュール名がCargoパッケージ名のようです。

ルートモジュール名はcrateというキーワードに置き換えることもできるようです。

use backyard::garden::vegetables::Asparagus;
// 以下でも可
use crate::garden::vegetables::Asparagus;

こうはなりません。

use crate::backyard::garden::vegetables::Asparagus;

また、モジュールは入れ子の構文で定義もできるようです。

src/lib.rs

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}

        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}

        fn serve_order() {}

        fn take_payment() {}
    }
}

これはモジュールツリーとしてはこうなるようです。

[パッケージ]
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

モジュールツリーを参照するパス

ここではモジュールツリーを参照するためのパスについて書かれています。

Paths for Referring to an Item in the Module Tree - The Rust Programming Language

パスには次の2つの形式があります。

• 絶対パス
  • クレートルートからの絶対パス
  • パスがルートモジュールから始まる場合はこちら
• 相対パス
  • 現在のモジュールからの相対パス
  • 現在のモジュール名またはself、superを使う

どちらを使用するかはパッケージのルールで決めるとされていますが、一般的には絶対パスを推奨しているようです。

バイナリークレートとライブラリークレートの両方を含むパッケージのベストプラクティスについて。

Best Practices for Packages with a Binary and a Library

この場合、モジュールツリーはsrc/lib.rsで定義すべきなようです。

The module tree should be defined in src/lib.rs.

バイナリークレートは、ライブラリークレートのクライアントとして機能します。

useキーワードを使ったパスとスコープの取り込み

useキーワードを使ったパスとスコープの取り込みについて。

Bringing Paths Into Scope with the use Keyword - The Rust Programming Language

他の言語におけるimportなどと似たような話なので、大半は割愛します。

ちょっと変わった機能としては、useするだけではなくpub useとすることで取り込んだパスを再エクスポートできるようです。

pub use crate::front_of_house::hosting;

モジュールを異なるファイルに分割する

最後は、モジュールを異なるファイルに分割するというテーマです。

Separating Modules into Different Files - The Rust Programming Language

ここでは、これまでひとつのファイルでモジュール定義をしていたものを分割するという内容です。1番最初の例が、すでに分割されていた
ような気がしますが…。

ここを読んでいくと、モジュールの宣言は以下で行うのが良さそうですね。

• src/lib.rs
• src/[モジュール名].rs

少し大きな例を

もう少し大きな例はないのかな？と思ったところ、Rust by Exampleを見るのが良さそうでした。

File hierarchy - Rust By Example

こんな例ですね。

$ tree .
.
├── my
│   ├── inaccessible.rs
│   └── nested.rs
├── my.rs
└── split.rs

こう見るとファイルとモジュールの単位がかなり近しく、こんな感じの利用になりそうですね。

• [モジュール名].rsを定義する
  • もしくはクレートルート
• モジュール内にサブモジュールを持つ場合、[モジュール名].rsに[モジュール名]配下に含まれるモジュール定義を列挙する

たとえば、上記例だとmy.rsの内容はこうなっています。

// Similarly `mod inaccessible` and `mod nested` will locate the `nested.rs`
// and `inaccessible.rs` files and insert them here under their respective
// modules
mod inaccessible;
pub mod nested;

pub fn function() {
    println!("called `my::function()`");
}

fn private_function() {
    println!("called `my::private_function()`");
}

pub fn indirect_access() {
    print!("called `my::indirect_access()`, that\n> ");

    private_function();
}

ちょっと気になったこととして、Getting Startedの「Command line apps in Rust」でsrc/main.rsの定義をsrc/lib.rsに移し、src/main.rsから
参照しようとした時に対象の関数をパッケージ名（ルートのクレート名）をつけて指定する必要がありました。

バイナリークレートのクレートルートからライブラリークレートのクレートルートを参照する時も、別クレート扱いなのでクレート名が
必要だということでしょうね（名前が同じで異なるモジュール？）。

おわりに

Rustのパッケージ、クレート、モジュールに関するドキュメントを見てみました。

ファイルを分割した時の扱いがよくわからなかったので、これでだいぶ理解が進んだと思います。