Module determinator::rules

source ·
Expand description

Custom rules for the target determinator.

By default, the target determinator follows a simple set of rules:

  • Every changed path is matched to its nearest package, and that package is marked changed.
  • Cargo builds are simulated against the old and new package graphs, and any packages with different results are marked changed.
  • The affected set is found through observing simulated Cargo builds and doing a reverse map.

However, there is often a need to customize these rules, for example to:

  • ignore certain files
  • build everything if certain files or packages have changed
  • add virtual dependencies that Cargo may not know about: if a package changes, also consider certain other packages as changed.

These custom behaviors can be specified through determinator rules.

There are two sorts of determinator rules:

  • Path rules match on changed paths, and are applied in order, before regular matches.
  • Package rules match based on changed packages, and are applied as required until exhausted (i.e. a fixpoint is reached).

Determinator rules are a configuration file format and can be read from a TOML file.

§Default path rules

The determinator ships with a set of default path rules for common files such as .gitignore and Cargo.lock. These rules are applied after custom rules, so custom rules matching the same paths can override them.

The default rules can be viewed here.

To disable default rules entirely, set at the top level:

use-default-rules = false

§Examples for path rules

To ignore all files named README.md and README.tpl, and skip all further processing:

[[path-rule]]
# Globs are implemented using globset: https://docs.rs/globset/0.4
globs = ["**/README.md", "**/README.tpl"]
mark-changed = []
# "skip" is the default for post-rule, so it can be omitted.
post-rule = "skip"

To mark a package changed if a file in a different directory changes, but also continue to use the standard algorithm to match paths to their nearest package:

[[path-rule]]
# Note that globs are relative to the root of the workspace.
globs = ["cargo-guppy/src/lib.rs"]
# Workspace packages are specified through their names.
mark-changed = ["cargo-compare"]
# "skip-rules" means that cargo-guppy/src/lib.rs will also match cargo-guppy.
post-rule = "skip-rules"

To build everything if a special file changes:

[[path-rule]]
name = "rust-toolchain"
mark-changed = "all"

To apply multiple rules to a file, say CODE_OF_CONDUCT.md:

[[path-rule]]
globs = ["CODE_OF_CONDUCT.md", "CONTRIBUTING.md"]
mark-changed = ["cargo-guppy"]
# "fallthrough" means further rules are applied as well.
post-rule = "fallthrough"

[[path-rule]]
globs = ["CODE_OF_CONDUCT.md"]
mark-changed = ["guppy"]

§Examples for package rules

To add a “virtual dependency” that Cargo may not know about:

[[package-rule]]
on-affected = ["fixtures"]
mark-changed = ["guppy-cmdlib"]

To build everything if a package changes.

[[package-rule]]
on-affected = ["guppy-benchmarks"]
mark-changed = "all"

Structs§

Enums§