Creating the generator
Create a new binary Rust crate and add
ritual as a dependency. In the
main function, you need to construct a
ritual::config::GlobalConfig and pass it to
GlobalConfig allows you to process multiple libraries (or parts of a library as separate crates) in a single run, but in the simple case it just contains a function that creates a
Config for your library.
Config is the main way of configuring ritual. You can use it to set up every property the generator supports. It also allows you to set up hooks that run in particular points of the processing and allow you to filter or alter the results programmatically. See the documentation of
Config and this example for more information.
Running the generator
Ritual needs a workspace to work. Workspace is a directory that contains ritual’s databases, generated crates, logs, and temporary files. You should use the same workspace for consecutive runs of the same generator.
You can run the generator like this:
cargo run -- ~/clipper/workspace -c clipper -o main
-o flag specifies the operations to run. Ritual’s processing consists of multiple steps.
main is an alias for the main sequence of operations that produce a complete crate from scratch. You can also specify a specific operation (e.g.
rust_generator) or resume the main sequence from a certain point with
If everything is successful, the generated crate will appear in the
out subdirectory of the workspace.
Adding tests and custom Rust code
In addition to
Config, you can also specify a crate template to be used. Crate template is a directory normally placed in the repository of your generator. You can supply a crate template with
Config::set_crate_template_path. It may contain tests, examples, extra source code, and any other files. These files are merged into the files generated by ritual. It’s recommended to have some tests in your crate template. At the end of the main sequence, ritual will run these tests.