build_scripts User Guide

This project contains the scripts that are required to build, lint, test, and run projects in this repository. The scripts are also used by the CI workflows and define what gets run under CI.

Generally, the scripts are run with the following command template: cargo run -p build_scripts -- $build_args.... The $build_args are the arguments passed to the build_scripts binary.

The list of supported actions can be seen using: cargo run -p build_scripts -- --help

Modifying build_scripts

Adding top-level actions

The top level of the tool is defined using proc-macros from the clap crate. Our top level actions are defined in enum SubCommand in main.rs.

1. Create a function like fn my_build_action(root: &Path) that performs the action. The root argument will be the path to the root directory of the project.
2. Add an entry to SubCommand in main.rs. The doc comment will be the --help info. See the clap documentation on how to define additional arguments or flags.
3. Create a handler in fn main() that matches the new subcommand and calls the function defined in step 1.
4. Add any additional cleanup required by the action to fn clean_everything(root: &Path) in main.rs.
5. (optional) Consider adding the action to CI by adding a call to the function from fn verify_ci in main.rs.

Motivation

Cargo is not a suitable tool for managing our various build configurations nor is it meant to build non-Rust libraries. Since our repository contains binaries requiring various feature-sets and libraries in many non-Rust languages, we needed a common place to define how the project is built. This package is that common place. Additionally, by writing this in Rust we can run these scripts on multiple platforms without the need for additional external dependencies.