はじめに
これはRust その2 Advent Calendar 2016の7日目の記事です。
Rustプロジェクトを新規作成するときcargo newを使うと以下のようなファイルが生成されます。
Cargo.toml
▾ src/
lib.rs
大抵の場合これで十分なのですが、公式ドキュメントを見るとオプション扱いのディレクトリがいくつかあるようです。
このあたりに関するまとまった記事はなさそうだったので、今回はcargoが特別扱いするディレクトリを全て使ったサンプルプロジェクトを作って簡単に解説します。
リポジトリはこちらです。
dalance/sample-rs
ディレクトリ構成
サンプルプロジェクトの構成は以下の通りです。
▾ src/ # ソースファイル
lib.rs # ライブラリ用のエントリ・ポイント
hello.rs
world.rs
▾ bin/ # (オプション) 追加の実行可能形式
hello.rs
world.rs
▾ examples/ # (オプション) 使用例
hello_world.rs
▾ tests/ # (オプション) 統合テスト
hello_world.rs
▾ benches/ # (オプション) ベンチマーク
hello.rs
world.rs
src直下は見たままなので特にいうことはありません。
オプションになっているディレクトリが本題です。
src/bin：追加の実行可能形式
バイナリ用のプロジェクトの場合、デフォルトではプロジェクト名と同じ名前のバイナリがsrc/main.rsをエントリ・ポイントとして生成されます。
もし1プロジェクトで複数のバイナリを生成したい場合、src/bin以下にhoge.rsなどとすることでバイナリhogeを生成できます。
これはライブラリのプロジェクトあっても有効なので、そのライブラリを使った簡易フロントエンドも付けたい、といった場合にも使えます。
このサンプルプロジェクトはライブラリですが、src/bin/hello.rsとsrc/bin/world.rsがあるので
> cargo build
> ls target/debug
build deps examples hello libsample.rlib native world
というように通常生成されるlibsample.rlibの他に、helloとworldもそれぞれ生成されます。
examples：使用例
こちらはライブラリ向けですが、examples/hoge.rsに
extern crate hoge
fn main() {
// ライブラリhogeの使用例
}
としてcargo run --example hogeとするとhoge.rsが実行されます。ライブラリ作成者の方は使用例をREADME.mdに書く代わりにこちらを使うようにすると、実行して確認するといった作業が楽になりそうです。
サンプルプロジェクトでは
> cargo run --example hello_world
Hello World!
となります。
tests：統合テスト
ユニットテストは各ソースファイルの末尾などに書くと思いますが、ファイルをまたいだ統合テストはこちらに置きます。
ちなみにcargoがテストとして認識するのはtestsの直下だけです。なので、以下のような構成にしておくと各テストファイルからmod commonとして共通のソースを呼び出すことができます。
▾ tests/
test1.rs
test2.rs
▾ common/
mod.rs
benches：ベンチマーク
#[bench]を含んだベンチマーク用のファイルをここに置きます。このディレクトリは結構重要で、#[bench]を含んだファイルをsrcなどに置いてしまうとstableでコンパイルできなくなってしまいます。（ベンチマーク機能は現状unstableなので）
このディレクトリに置かれたファイルは、cargo buildやcargo testでは参照されず、cargo benchの時だけ参照されるので、テストやバイナリのリリースはstableで行い、ベンチマークだけnightlyで行う、といったことが出来るようになります。
ちなみにrustup runコマンドを使うと以下のように通常はstableを使いつつ、ベンチマーク時だけnightlyを使うようにできます。
> rustc --version
rustc 1.13.0 (2c6933acc 2016-11-07)
> rustup run nightly rustc --version
rustc 1.15.0-nightly (28d6623bc 2016-12-03)
> rustup run nightly cargo bench
まとめ
Rustプロジェクトのディレクトリ構成のうちオプション部分を簡単に解説しました。
ちなみにcargo newで生成されるディレクトリ構成についてはResubmission of templating PR (#1747)なるPRが出ていて
cargo new --template https://rustrepos.org/mytemplate foo
というようなことが出来るようになるかもしれません。
結構気になっている機能なので入ったら試してみようと思います。