repository·master·Indexed 21 days ago
https://github.com/rust-cli/bookA resource maintained by the Rust CLI working group for learning how to build command-line tools in Rust. The book covers everything from a beginner tutorial building a grep clone (grrs) to advanced topics including argument parsing with clap, configuration management with confy, error handling with anyhow, and user-friendly panic handling with human-panic.
fs::read_to_string() reads the entire file into memory at once. For large files, this is inefficient. To optimize memory usage, use std::io::BufReader to read the file line-by-line instead of loading the whole content into a string.To use testing time efficiently, follow these guidelines:
--help text. Instead, assert that specific required elements are present.proptest if you find yourself writing many manual unit tests for complex input permutations.When designing CLI tools for composition, providing a structured format like JSON is superior to plain text or TSV for complex data.
A common and effective pattern is to use Line-delimited JSON (also known as JSON Lines). Instead of emitting one large JSON array, emit one complete JSON object per message, each on a new line. This allows consumers to parse messages one by one as they are emitted (streaming), which is useful for long-running processes.
You can use the serde_json crate and its json! macro to construct these messages easily.
// Example of emitting line-delimited JSON
// Output: {"content":"Hello world","type":"message"}
println!("{}", serde_json::json!({
"content": "Hello world",
"type": "message"
}));By default, the operating system handles signals (like Ctrl+C) by terminating the process immediately. This is sufficient if your application does not require a graceful shutdown.
You should implement custom signal handling if your application needs to perform cleanup tasks before exiting, such as:
There are two primary ways to test application functionality:
To allow users to control the amount of information displayed (via --verbose flags or the RUST_LOG environment variable), use consistent log levels. The log crate defines levels in increasing order of severity:
tracedebuginfo (Recommended as the default level for informative output)warningerrorEnsure messages provide enough context to be useful when filtered (e.g., via grep) without being excessively verbose.
Instead of manually parsing a list of strings, it is a best practice in Rust to represent CLI arguments as a custom struct. This allows you to define the expected types (e.g., String for patterns or PathBuf for file paths) and requirements (e.g., which arguments are mandatory) upfront.
Using std::path::PathBuf is recommended for file system paths as it provides cross-platform compatibility compared to a standard String.
use std::path::PathBuf;
struct Cli {
pattern: String,
path: PathBuf,
}When an application is running normally, use informative and concise messages to tell a story about what the application is doing and how it impacts the user.
Key principles:
=> Downloading repository index
=> Downloading packages...Users often press Ctrl+C multiple times if the application does not respond immediately to the first press.
Recommended Behavior: If the application receives a second Ctrl+C while it is already attempting to handle the first one (e.g., during a graceful shutdown phase), it should quit immediately to avoid frustrating the user.
When distributing a new Rust-based command-line tool, do not rely on a single method. Instead, follow a tiered approach to maximize accessibility:
cargo install: This is the easiest way for Rust users to get your tool.brew, apt, etc.) to reach a wider audience.The tutorial is written for Rust 2018. To ensure compatibility with the code examples, you must use Rust version 1.31.0 or later and specify the 2018 edition in your Cargo.toml file.
[package]
edition = "2018"