Running generator

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 ritual::cli::run_from_args. 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

The -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 '[rust_generator..)'.

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.