Skip to content

Commit b280747

Browse files
alies-devalies-dev
committed
Expand Rust documentation with comprehensive command examples and AI-friendly flags
Enhance Rust tool usage guidance with extensive command references and AI-friendly flag suggestions for common tasks. Update AGENTS.md/CLAUDE.md template accordingly.
1 parent 2ac9583 commit b280747

1 file changed

Lines changed: 194 additions & 2 deletions

File tree

‎rust.md‎

Lines changed: 194 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,197 @@
11
# Rust
22

3-
Contributions welcome! See [contributing guidelines](CONTRIBUTING.md).
3+
## Quick Reference
44

5-
Tools to cover (draft list): cargo build, cargo test, cargo clippy, cargo fmt, cargo doc, cargo install, rustc, cargo-nextest.
5+
| Tool | AI-Friendly Flags |
6+
|--------------------|---------------------------------------------------------------------------------|
7+
| cargo build | `--color=never -q` (progress bar auto-disables in non-TTY) |
8+
| cargo check | `--color=never -q --message-format=short` |
9+
| cargo test | `--color=never -q -- --color=never` |
10+
| cargo clippy | `--color=never -q --message-format=short` |
11+
| cargo clippy --fix | `--allow-dirty --color=never` |
12+
| cargo fmt --check | `--message-format=short -- --color=never` |
13+
| cargo fmt | No flags needed (formats in place, no output on success) |
14+
| cargo nextest run | `--color=never --cargo-quiet --failure-output=immediate --success-output=never` |
15+
| cargo audit | `--format=json --color=never` |
16+
| cargo deny check | `--format=json --color=never` |
17+
18+
## Environment Variables
19+
20+
These apply to all `cargo` subcommands:
21+
22+
| Variable | Values | Effect |
23+
|----------------------------|---------------------------|------------------------------------------|
24+
| `NO_COLOR=1` | Any non-empty value | Disables ANSI colors (since Rust 1.74.0) |
25+
| `CARGO_TERM_COLOR` | `auto`, `always`, `never` | Controls Cargo's color output |
26+
| `CARGO_TERM_PROGRESS_WHEN` | `auto`, `always`, `never` | Controls progress bar display |
27+
| `CARGO_TERM_QUIET` | `true` / `false` | Equivalent to `-q` |
28+
| `CI` | Any value (presence-only) | Disables progress bar in `auto` mode |
29+
| `TERM=dumb` | — | Disables progress bar in `auto` mode |
30+
31+
Cargo auto-detects non-TTY environments: colors are stripped and the progress bar is disabled when stderr is not a terminal. Explicit flags are safer, but in many cases no flags are needed when piping output.
32+
33+
## cargo build
34+
35+
```bash
36+
cargo build --color=never -q
37+
```
38+
39+
- `--color=never` — disables ANSI colors (`auto` strips colors in non-TTY but explicit is safer)
40+
- `-q` / `--quiet` — suppresses Compiling, Downloading, and Finished status lines (errors still print)
41+
- `--message-format=json` — structured JSON to stdout, one object per line (`compiler-message`, `compiler-artifact`, `build-script-executed`, `build-finished`) — very verbose
42+
43+
## cargo check
44+
45+
```bash
46+
cargo check --color=never -q --message-format=short
47+
```
48+
49+
- `--message-format=short` — one-line-per-error format: `file:line:col: severity[code]: message`
50+
- `--message-format=json` — structured JSON to stdout (same format as `cargo build`)
51+
- `--color=never` — disables colors
52+
- `-q` / `--quiet` — suppresses "Checking..." status lines
53+
54+
`cargo check` is faster than `cargo build` — it skips code generation and only runs the compiler frontend.
55+
56+
## cargo test
57+
58+
```bash
59+
# Default — only failures and summary
60+
cargo test --color=never -q -- --color=never
61+
62+
# Single test
63+
cargo test --color=never -q test_name -- --color=never
64+
65+
# Exact match
66+
cargo test --color=never -q test_name -- --color=never --exact
67+
```
68+
69+
- `--color=never` — disables colors for Cargo output
70+
- `-- --color=never` — disables colors for the test harness (libtest). **Must be passed separately after `--`** — Cargo's `--color` does not propagate to the test binary
71+
- `-q` / `--quiet` — suppresses compilation status lines and shows one character per test instead of one line
72+
- `-- --no-capture` — shows stdout/stderr from tests in real time (useful for debugging). `--nocapture` is a deprecated alias
73+
- `-- --show-output` — shows stdout/stderr of passing tests after all tests complete
74+
- `-- --test-threads=1` — serial execution for tests with shared state
75+
- `--no-fail-fast` — continue running all test executables even if one fails
76+
77+
`--message-format=json` (Cargo flag) works on stable but only covers compilation messages. The test-results JSON format (`-- --format=json -Z unstable-options`) is unstable and requires nightly.
78+
79+
## cargo clippy
80+
81+
```bash
82+
# Compact one-line-per-warning
83+
cargo clippy --color=never -q --message-format=short
84+
85+
# Treat warnings as errors (common CI pattern)
86+
cargo clippy --color=never -q --message-format=short -- -Dwarnings
87+
88+
# Auto-fix (--allow-dirty needed if working tree has uncommitted changes)
89+
cargo clippy --fix --allow-dirty --color=never
90+
```
91+
92+
- `--message-format=short` — one-line-per-diagnostic format (biggest token savings vs default)
93+
- `--color=never` — disables colors
94+
- `-q` / `--quiet` — suppresses "Checking..." status lines
95+
- `-- -Dwarnings` — treats all warnings as errors (non-zero exit on any lint)
96+
- `-- -Aclippy::lint_name` — suppress a specific lint
97+
- `--fix` — automatically applies Clippy suggestions. Requires `--allow-dirty` if the working tree has uncommitted changes (common for AI agents)
98+
- `--message-format=json` — structured JSON diagnostics
99+
100+
Default output includes multi-line code snippets with underlines and suggestions — significantly more verbose than `short`. The `short` format is 3-5x more token-efficient.
101+
102+
## cargo fmt
103+
104+
```bash
105+
# Check which files need formatting (most token-efficient)
106+
cargo fmt --check --message-format=short -- --color=never
107+
108+
# Fix formatting
109+
cargo fmt
110+
```
111+
112+
- `--check` — exits 1 if files need formatting, 0 if already formatted. Without `--message-format=short`, prints diffs of unformatted code
113+
- `--message-format=short` — lists only file paths that need formatting, one per line (maps to rustfmt's `-l` flag)
114+
- `--message-format=json` — JSON output via rustfmt (cannot be combined with `--check`)
115+
- `-- --color=never` — disables colors. `--color` is a rustfmt flag, not a cargo-fmt flag — must be passed after `--`
116+
- `-q` / `--quiet` — suppresses output
117+
118+
`cargo fmt` with no flags formats all files in place and produces no output on success.
119+
120+
## cargo nextest run
121+
122+
[cargo-nextest](https://nexte.st) is a popular third-party test runner with better output control than the built-in test harness.
123+
124+
```bash
125+
# Failures only, no pass output, suppress compilation noise
126+
cargo nextest run --color=never --cargo-quiet --failure-output=immediate --success-output=never
127+
128+
# Single test
129+
cargo nextest run --color=never -E 'test(test_name)'
130+
```
131+
132+
- `--color=never` — disables colors
133+
- `--failure-output=immediate` — show failure output as it happens (also: `final`, `immediate-final`, `never`)
134+
- `--success-output=never` — suppress output from passing tests (also: `immediate`, `final`, `immediate-final`)
135+
- `--status-level=fail` — only show failed tests during execution (values: `none`, `fail`, `retry`, `slow`, `leak`, `pass`, `skip`, `all`)
136+
- `--final-status-level=fail` — only show failures in the summary (values: `none`, `fail`, `flaky`, `slow`, `skip`, `pass`, `all`)
137+
- `--cargo-quiet` — suppress Cargo compilation messages (repeat twice for full suppression)
138+
- `--no-output-indent` — disable indentation of captured test output
139+
140+
nextest auto-detects non-TTY: in non-TTY mode, the progress bar switches to a line counter.
141+
142+
JUnit XML output is configured via `nextest.toml`, not CLI flags:
143+
144+
```toml
145+
[profile.ci.junit]
146+
path = "junit.xml"
147+
store-success-output = false
148+
store-failure-output = true
149+
```
150+
151+
Run with `cargo nextest run --profile ci` to generate the report.
152+
153+
## cargo audit
154+
155+
```bash
156+
cargo audit --format=json --color=never
157+
```
158+
159+
- `--format=json` — structured JSON output (also accepts `sarif` for security tool integration)
160+
- `--color=never` — disables colors
161+
- `-q` / `--quiet` — suppresses non-essential output
162+
163+
Legacy shorthand: `--json` is equivalent to `--format=json`
164+
165+
## cargo deny
166+
167+
```bash
168+
cargo deny --format=json --color=never check
169+
```
170+
171+
Note: `--format` and `--color` are global flags and must appear before the `check` subcommand. Flags like `--hide-inclusion-graph` and `-s` belong to `check` and go after it.
172+
173+
- `--format=json` — each diagnostic as a single-line JSON object (also accepts `sarif` for security tool integration)
174+
- `--color=never` — disables colors (no effect when `--format=json`)
175+
- `--hide-inclusion-graph` — suppresses verbose inverse dependency graph in diagnostics (significant savings in human format)
176+
- `-L error` / `--log-level=error` — only show errors (values: `off`, `error`, `warn`, `info`, `debug`, `trace`)
177+
- `-s` / `--show-stats` — show statistics for all checks
178+
179+
## AGENTS.md / CLAUDE.md Template
180+
181+
Copy this into your project's AGENTS.md or CLAUDE.md:
182+
183+
```markdown
184+
## Running Tools
185+
186+
- Build: `cargo build --color=never -q`
187+
- Check: `cargo check --color=never -q --message-format=short`
188+
- Tests: `cargo test --color=never -q -- --color=never`
189+
- Tests (single): `cargo test --color=never -q test_name -- --color=never`
190+
- Tests (nextest): `cargo nextest run --color=never --cargo-quiet --failure-output=immediate --success-output=never`
191+
- Lint: `cargo clippy --color=never -q --message-format=short -- -Dwarnings`
192+
- Lint fix: `cargo clippy --fix --allow-dirty --color=never`
193+
- Format check: `cargo fmt --check --message-format=short -- --color=never`
194+
- Format fix: `cargo fmt`
195+
- Audit: `cargo audit --format=json --color=never`
196+
- Deny: `cargo deny --format=json --color=never check`
197+
```

0 commit comments

Comments
 (0)