pre-run and post-run hooks for cargo

[bentheiii]

Problem

My original intention, if this feature ever becomes available, is to automatically note dependency changes in a project's changelog with every command.

Proposed Solution

Hi there, coming from the python ecosystem, I'm used to having custom hooks running on dependency changes using poetry's plugin system. I was wondering if we could add the same capability to cargo.

I propose we add a new mapping to Cargo.toml manifests (and workspaces):

[hooks]
before_command="..."
after_command="..."

If these options are specified in Cargo.tomls, then cargo will execute the path specified, with the same arguments provided to cargo, as a child process, before and after any cargo command executes, respectively.

• If the env var CARGO_SKIP_HOOKS is set to "1", cargo will skip running the hooks. Users could use this flag to call cargo from inside their hooks without the risk of infinite recursion.
• If the before_command hook fails (exists with a non-zero status), cargo will not execute the command, and exit with a non-zero code.
• If the cargo command itself fails, the after_command hook will not be called (a special hook for command failures may be considered in the future)
• If the after_command hook fails, cargo will exit with a non-zero code.

Notes

For example, with the Cargo.toml

[package]
...

[hooks]
before_command="foo"
after_command="bar"

Then, when calling cargo add regex, cargo will do the following

• execute a child process with executable foo with arguments add regex
• add the regex crate dependency to the package, as normal
• execute a child process with executable bar with arguments add regex

[epage]

FYI I moved your use case up into the problem section and description of python hooks to the solution. Its important for us to be use case driven as it helps us guide us in choosing a solution, including doing nothing, and in deciding the details of that solution.

[epage]

If we did this, I'm presuming we'd put this in the config, rather than the manifest. All of our other hooks live there (credential provider, target runner, various ways of wrapping rustc). The config is also where we generally put more dynamic config and dev-only settings. We also experiment there before seeing how to put things in manifests.

Command strings have quoting issues, so I assume it would be a list of string arguments.

[epage]

As for the use case of changelog updates

• This could also be handled by a changelog tool that semantically diffs the manifest
• My assumption would be that dependencies are more of an internal detail and wouldn't fit in a changelog, making this use case not very compelling

Also, in thinking about hooks more, I worry about what it means for compatibility.

• we are expecting tools to re-parse our command line, which is generally difficult for any tool due to the context-sensitive nature of most CLIs but that also means adding new features can break these hooks
• Any recursive cargo call (like in build scripts) will need to be updated to disable hooks. Maybe we can do this for any child process we spawn? Unsure if that would break other use cases and the spirit of the hook

[bentheiii]

If we did this, I'm presuming we'd put this in the config, rather than the manifest

Command strings have quoting issues, so I assume it would be a list of string arguments

Sounds good to me

This could also be handled by a changelog tool that semantically diffs the manifest

Our team prefers a live-updating version because it allows us to consciously monitor dependency changes per-PR and per-feature

My assumption would be that dependencies are more of an internal detail and wouldn't fit in a changelog, making this use case not very compelling

In public-facing projects, sure. This is being used in internal projects where such details are important to get at a glance even by non-technical users

we are expecting tools to re-parse our command line, which is generally difficult for any tool due to the context-sensitive nature of most CLIs but that also means adding new features can break these hooks

It will be up to the creators of the hooks to be strict with their parsing and what they accept, and to ignore all unrecognized command-line arguments. Unless it introduces ambiguity with current usages, I don't expect a feature to be capable of breaking a future-compatible hook.

Any recursive cargo call (like in build scripts) will need to be updated to disable hooks. Maybe we can do this for any child process we spawn? Unsure if that would break other use cases and the spirit of the hook

I'm not sure I understand the reasoning behind this. It could be up to the developer of the hook to ensure it doesn't cause an infinite recursion (similar to how git hooks work). If there's something I'm missing then yes, we can simply set all cargo child processes with the env var CARGO_SKIP_HOOKS set to 1, and users will be able to re-enable recursive hooks by changing it to 0 in their own cargo calls.

[epage]

This is being used in internal projects where such details are important to get at a glance even by non-technical users

Could you expand on this? I can't think of a situation where active monitoring by non-technical users of direct dependencies mattered. The main situation I've dealt with is legal audits which involved the transitive dependency tree and usually involves dedicated tools.

It will be up to the creators of the hooks to be strict with their parsing and what they accept, and to ignore all unrecognized command-line arguments. Unless it introduces ambiguity with current usages, I don't expect a feature to be capable of breaking a future-compatible hook.

As I said, CLIs tend to be context-sensitive. Is --foo bar the same as bar --foo or --foo=bar? Ignoring unknown arguments is generally not sufficient.

Any recursive cargo call (like in build scripts) will need to be updated to disable hooks. Maybe we can do this for any child process we spawn? Unsure if that would break other use cases and the spirit of the hook

I'm not sure I understand the reasoning behind this. It could be up to the developer of the hook to ensure it doesn't cause an infinite recursion (similar to how git hooks work). If there's something I'm missing then yes, we can simply set all cargo child processes with the env var CARGO_SKIP_HOOKS set to 1, and users will be able to re-enable recursive hooks by changing it to 0 in their own cargo calls.

If I run

$ cargo check

that may invoke a build script that might do

cargo build

Should the hook run for these by default or not? I feel like this is hook dependent on whether you care about every cargo invocation or only the top-level cargo invocation.

[weihanglo]

At work, we have a cargo wrapper that acts as a pre/post-hook whenever you do cargo <cmd>. It sometimes ran into problems with nested Cargo calls and like different RUSTUP_TOOLCHAIN setting from rust-analyzer. Or , in dependency's build script it may call cargo metadata and you don't even know they're working on a dependency not a local package. They are exactly what Ed talked about.

[weihanglo]

My original intention, if this feature ever becomes available, is to automatically note dependency changes in a project's changelog with every command.

Do we want to talk about more on your original intention, instead of jumping straight into a solution? I feel like there might be something Cargo can do without introduction a new hook mechanism, maybe a new lint? Would you mind sharing a bit more about your scenario or what the potential hook will do?

Our team prefers a live-updating version because it allows us to consciously monitor dependency changes per-PR and per-feature

if it were per-PR, githooks should be sufficient if you're using git, no? It is also language agnostic, so you can do it without Cargo/Rust support.

[bentheiii]

Could you expand on this? I can't think of a situation where active monitoring by non-technical users of direct dependencies mattered. The main situation I've dealt with is legal audits which involved the transitive dependency tree and usually involves dedicated tools

The users reading the change entries might be developers from other teams in R&D. They'd need to proactively know when a version of some language-agnostic dependency (onnx-runtime, protobuf, as well as common org schemas and constants delivered via crates) changes, but might not be familiar with rust, or even the concept of lockfiles.

As I said, CLIs tend to be context-sensitive. Is --foo bar the same as bar --foo or --foo=bar? Ignoring unknown arguments is generally not sufficient.

In truth, I expect most hooks to mainly concern themselves with only the first cargo subcommand (i.e. update or build). For this usage, there's no context-sensitivity AFAICT. Perhaps the hooks should only receive that?

Should the hook run for these by default or not? I feel like this is hook dependent on whether you care about every cargo invocation or only the top-level cargo invocation.

I tend towards "yes", and it will be up to the tool's developer to do nothing on build (or, to only do something if you're in the commands you care about). Maybe there should be a an env var (CARGO_CHILD?) that would indicate that the process was spawned by cargo, and let tools exit on their own if it's set?

[bentheiii]

if it were per-PR, githooks should be sufficient if you're using git, no? It is also language agnostic, so you can do it without Cargo/Rust support.

theoretically yes, the difference is that githooks are opt-in. Every developer of a repository would have to enable the githooks (and AFAICT, re-enable them per repo). The feature I'm suggesting is opt-out, and is easier to configure for new users.

Do we want to talk about more on your original intention, instead of jumping straight into a solution?

In our org, we've already began to solve the need on our end with a cargo wrapper similar to what you've described. I'd have liked to solve it in a similar way to our poetry solution (i.e plugins and hooks), and so I suggested it here.

If we want to only discuss the original requirement, then it is simply to call a process when cargo decides to change a dependency's version (including adding and removing dependencies)

[epage]

If we want to only discuss the original requirement, then it is simply to call a process when cargo decides to change a dependency's version (including adding and removing dependencies)

To be clear, that is not a requirement but proposed solution.