165 lines
2.7 KiB
Markdown
165 lines
2.7 KiB
Markdown
# Clap Quick Start Guide
|
|
|
|
This guide will help you build your first Clap CLI application in minutes.
|
|
|
|
## Prerequisites
|
|
|
|
- Rust installed (1.70.0 or newer)
|
|
- Cargo (comes with Rust)
|
|
|
|
## Step 1: Create a New Project
|
|
|
|
```bash
|
|
cargo new my-cli
|
|
cd my-cli
|
|
```
|
|
|
|
## Step 2: Add Clap Dependency
|
|
|
|
Edit `Cargo.toml`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
clap = { version = "4.5", features = ["derive"] }
|
|
```
|
|
|
|
## Step 3: Write Your First CLI
|
|
|
|
Replace `src/main.rs` with:
|
|
|
|
```rust
|
|
use clap::Parser;
|
|
|
|
/// Simple program to greet a person
|
|
#[derive(Parser)]
|
|
#[command(author, version, about, long_about = None)]
|
|
struct Args {
|
|
/// Name of the person to greet
|
|
#[arg(short, long)]
|
|
name: String,
|
|
|
|
/// Number of times to greet
|
|
#[arg(short, long, default_value_t = 1)]
|
|
count: u8,
|
|
}
|
|
|
|
fn main() {
|
|
let args = Args::parse();
|
|
|
|
for _ in 0..args.count {
|
|
println!("Hello {}!", args.name)
|
|
}
|
|
}
|
|
```
|
|
|
|
## Step 4: Build and Run
|
|
|
|
```bash
|
|
# Build the project
|
|
cargo build --release
|
|
|
|
# Run with arguments
|
|
./target/release/my-cli --name Alice --count 3
|
|
|
|
# Check help output
|
|
./target/release/my-cli --help
|
|
```
|
|
|
|
## Expected Output
|
|
|
|
```
|
|
$ ./target/release/my-cli --name Alice --count 3
|
|
Hello Alice!
|
|
Hello Alice!
|
|
Hello Alice!
|
|
```
|
|
|
|
## Help Output
|
|
|
|
```
|
|
$ ./target/release/my-cli --help
|
|
Simple program to greet a person
|
|
|
|
Usage: my-cli --name <NAME> [--count <COUNT>]
|
|
|
|
Options:
|
|
-n, --name <NAME> Name of the person to greet
|
|
-c, --count <COUNT> Number of times to greet [default: 1]
|
|
-h, --help Print help
|
|
-V, --version Print version
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
1. **Add Subcommands**: See `subcommands.rs` template
|
|
2. **Add Validation**: See `value-parser.rs` template
|
|
3. **Environment Variables**: See `env-variables.rs` template
|
|
4. **Type-Safe Options**: See `value-enum.rs` template
|
|
|
|
## Common Patterns
|
|
|
|
### Optional Arguments
|
|
|
|
```rust
|
|
#[arg(short, long)]
|
|
output: Option<String>,
|
|
```
|
|
|
|
### Multiple Values
|
|
|
|
```rust
|
|
#[arg(short, long, num_args = 1..)]
|
|
files: Vec<PathBuf>,
|
|
```
|
|
|
|
### Boolean Flags
|
|
|
|
```rust
|
|
#[arg(short, long)]
|
|
verbose: bool,
|
|
```
|
|
|
|
### With Default Value
|
|
|
|
```rust
|
|
#[arg(short, long, default_value = "config.toml")]
|
|
config: String,
|
|
```
|
|
|
|
### Required Unless Present
|
|
|
|
```rust
|
|
#[arg(long, required_unless_present = "config")]
|
|
database_url: Option<String>,
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "Parser trait not found"
|
|
|
|
Add the import:
|
|
```rust
|
|
use clap::Parser;
|
|
```
|
|
|
|
### "derive feature not enabled"
|
|
|
|
Update `Cargo.toml`:
|
|
```toml
|
|
clap = { version = "4.5", features = ["derive"] }
|
|
```
|
|
|
|
### Help text not showing
|
|
|
|
Add doc comments above fields:
|
|
```rust
|
|
/// This shows up in --help output
|
|
#[arg(short, long)]
|
|
```
|
|
|
|
## Resources
|
|
|
|
- Full templates: `skills/clap-patterns/templates/`
|
|
- Helper scripts: `skills/clap-patterns/scripts/`
|
|
- Official docs: https://docs.rs/clap/latest/clap/
|