All of Cargo’s output should go through the
Shell struct. You can normally
Shell instance from the
Config struct. Do not use the std
Most of Cargo’s output goes to stderr. When running in JSON mode, the output goes to stdout.
It is important to properly handle errors when writing to the console.
Informational commands, like
cargo list, should ignore any errors writing
the output. There are some
drop_print macros that are intended to make
Messages written during compilation should handle errors, and abort the build
if they are unable to be displayed. This is generally automatically handled in
JobQueue as it processes each message.
anyhow for managing errors. This makes it convenient to “chain”
errors together, so that Cargo can report how an error originated, and what it
was trying to do at the time.
Error helpers are implemented in the
errors module. Use the
InternalError error type for errors that are not expected to happen. This
will print a message to the user to file a bug report.
The binary side of Cargo uses the
CliError struct to wrap the process exit
code. Usually Cargo exits with 101 for an error, but some commands like
cargo test will exit with different codes.
Some guidelines for Cargo’s output:
- Keep the normal output brief. Cargo is already fairly noisy, so try to keep the output as brief and clean as possible.
- Good error messages are very important! Try to keep them brief and to the point, but good enough that a beginner can understand what is wrong and can figure out how to fix. It is a difficult balance to hit! Err on the side of providing extra information.
- When using any low-level routines, such as
std::fs, always add error context about what it is doing. For example, reading from a file should include context about which file is being read if there is an error.
- Cargo’s error style is usually a phrase, starting with a lowercase letter. If there is a longer error message that needs multiple sentences, go ahead and use multiple sentences. This should probably be improved sometime in the future to be more structured.