cargo generate を触ってみた¶

Git リポジトリをひな形にして Rust プロジェクトを作るcargo generateを試した。テンプレートの作り方、入力項目の定義方法、複数テンプレートの切り替え方を紹介する。

cargo generate とは¶

cargo-generate は、既存の git リポジトリをテンプレートとして利用することで、新しい Rust プロジェクトを迅速に起動して実行できるようにする開発者ツールです。

Cargo-generate は Shopify の Liquid テンプレート言語、フックスクリプトには Rhai 、プレースホルダーには正規表現を使用します。

setup¶

1	`cargo install cargo-generate`

usage¶

cargo generate username-on-github/mytemplate
# is the same as
cargo generate gh:username-on-github/mytemplate
# is the same as
cargo generate --git https://github.com/username-on-github/mytemplate.git
# for gitlab.com
cargo generate gl:username-on-gitlab/mytemplate

テンプレートレポジトリにサブディレクトリを作成し、サブディレクトリ配下にテンプレートを配置すると、複数のテンプレートから使うものを選べる。

cargo-generate.toml
[template]
sub_templates = ["folder1", "folder2"]

さらに、--initフラグを使うとカレントディレクトリにテンプレートを展開できる。--path LOCAL_PATH/mytemplateのように指定すれば、ローカルのテンプレートも指定できる。

template の記述¶

Liquid テンプレート言語を使ってテンプレートを記述する。テンプレートの中で{{variable}}のように記述すると、cargo generateの実行時にユーザー入力を求めることができる。また、{{variable}}.rsのようなファイルを作るとテンプレート生成時に入力値を適用したファイルが生成される。 if 分岐や for 文による繰り返しもでき、hooksでinit、pre、postのフックを設定できる。

例¶

組み込みとカスタムのプレースホルダーがある。カスタムのプレースホルダーは次のように使う。

cargo-generate.toml
[placeholders.hypervisor]
type = "string"
prompt = "What hypervisor to use?"
choices = ["uhyve", "qemu"]
default = "qemu"

[placeholders.network_enabled]
type = "bool"
prompt = "Want to enable network?"
default = true

src/main.rs
{% if network_enabled %}
use std::net::TcpListener;

fn main() {
    let listener = TcpListener::bind("0.0.0.0:8080").unwrap();
    loop {
        let (conn, addr) = listener.accept().unwrap();
        println!("Incoming Connection from {}", addr);
        std::io::copy(&mut &conn, &mut &conn).unwrap();
    }
}
{% else %}
fn main() {
    println!("Hello Rusty Hermit 🦀");
}
{% endif %}

Cargo.tomlの中でも、同じプレースホルダーを使える。

Cargo.toml
[package]
# the usual stuff

[dependencies]
{% if crate_type == "bin" %}
structopt = "0.3.21"
{% endif %}
# other general dependencies

{% if crate_type == "bin" %}
[[bin]]
path = "src/main.rs"
name = "{{crate_name}}-cli"
{% endif %}

使ってみた感想¶

プロジェクトテンプレートには Cookiecutter や copier があるが、cargo generate は Cookiecutter や copier の Rust 版に近い。テンプレートエンジンに Liquid、フックスクリプトに Rhai を採用している点も、他のツールと比べて特徴的だと感じた。

参考¶

Introduction - Cargo Generate Documentation