# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
uutils coreutils is a cross-platform reimplementation of the GNU coreutils in Rust. It provides Unix command-line utilities like `ls`, `cat`, `mv`, `cp`, etc. The project aims to be a drop-in replacement for GNU coreutils while being cross-platform, reliable, performant, and well-tested.
**Important:** This project cannot contain any code from GNU or other GPL implementations. Never reference GNU source code directly.
## Build and Development Commands
### Building
```bash
# Build all utilities (multicall binary)
cargo build --features unix
# The binary can be found in
./target/debug/coreutils <program>
# Build specific utilities as individual binaries
cargo build -p uu_cat -p uu_ls -p uu_mv
# Build with platform-specific features
cargo build --features unix # Unix platforms
cargo build --features macos # macOS specific
cargo build --features windows # Windows specific
```
Don't hesitate to run cargo fmt after writing code.
### Testing
```bash
# Run tests for all utilities
cargo test --features unix
# Test specific utilities
cargo test --features unix test_<program>
# Run with nextest (faster parallel execution)
cargo nextest run --features unix --no-fail-fast
# Run GNU test suite comparison
bash util/build-gnu.sh && DEBUG=1 bash util/run-gnu-test.sh tests/touch/not-owner.sh
```
### Code Quality
```bash
# Format code
cargo fmt --all
# Lint with clippy
cargo +stable clippy --allow-dirty --workspace --all-targets --all-features --fix -- -D warnings
# Check with cargo-deny (licenses, security, etc.)
cargo deny --all-features check all
# Spell checking with cspell
# Add spell-checker:ignore comments for words to ignore
# Run pre-commit hooks
pre-commit install # Setup
# Commits will automatically run checks
```
## Architecture and Code Organization
### Project Structure
- **`src/uu/`** - Each utility implemented as separate crate (e.g., `src/uu/cat/`, `src/uu/ls/`)
- **`src/uucore/`** - Shared library code between utilities (parsing, file ops, etc.)
- **`src/bin/coreutils.rs`** - Multicall binary that can invoke any utility
- **`tests/by-util/`** - Integration tests for each utility
- **`tests/uutests/`** - Test framework and utilities
### Utility Structure
Each utility follows this pattern:
```
src/uu/<utility>/
├── Cargo.toml # Dependencies and metadata
├── LICENSE # MIT license
├── locales/ # Internationalization files (.ftl)
│ ├── en-US.ftl
│ └── fr-FR.ftl
└── src/
├── main.rs # Entry point (usually just macro call)
└── <utility>.rs # Main implementation
```
### Key Architectural Patterns
1. **Multicall Binary**: The main `coreutils` binary can function as any utility based on how it's invoked (like busybox)
2. **Platform Abstraction**: Many utilities have `platform/` subdirectories with OS-specific implementations:
```
src/platform/
├── mod.rs
├── unix.rs
├── windows.rs
└── macos.rs
```
3. **Shared Core**: `uucore` provides common functionality:
- Argument parsing utilities
- File system operations
- Cross-platform compatibility layers
- Error handling patterns
- Formatting and display utilities
4. **Feature Flags**: Extensive use of Cargo features for:
- Platform-specific utilities (`feat_os_unix`, `feat_os_windows`)
- Optional functionality (`feat_acl`, `feat_selinux`)
- Utility groupings (`feat_common_core`, `feat_Tier1`)
### Internationalization (i18n)
- Uses Fluent localization system
- Locale files in `locales/` directories as `.ftl` files
- Build process copies locales to target directory
- Supports multiple languages (en-US, fr-FR, etc.)
## Development Guidelines
### Code Style (from CONTRIBUTING.md)
- **Never `panic!`** - Use proper error handling instead of `.unwrap()` or `panic!`
- **Never `exit`** - Use `Result` types for error handling; don't call `std::process::exit`
- **Minimal `unsafe`** - Only for FFI calls, with `// SAFETY:` comments
- **Use `OsStr`/`Path`** - For file paths, not `String`/`str` (supports invalid UTF-8)
- **Avoid macros** - Use simpler alternatives when possible
### Error Handling Patterns
- Return `Result` types rather than exiting
- Use `uucore::error` utilities for consistent error messages
- Handle invalid UTF-8 in paths and arguments gracefully
### Testing Strategy
- Integration tests in `tests/by-util/test_<utility>.rs`
- Always write a unit test when touching the behavior
- Unit tests within utility source files
- GNU compatibility tests via `util/run-gnu-test.sh`
- Cross-platform testing in CI
### Performance Considerations
We use codspeed for benchmarking:
To build the benchmark:
```bash
cargo codspeed build -p uu_<program>
```
To run the benchmark:
```bash
cargo codspeed run -p uu_<program>
```
- Individual benchmark should take between 100 to 500 ms to run
- Use efficient algorithms for large file operations
- Platform-specific optimizations where appropriate (e.g., splice on Linux)
### Performance Profiling
We use hyperfine for performance comparisons between different versions and against GNU:
```bash
# Build release version and create reference copy
cargo build --release --features unix
cp target/release/coreutils target/release/coreutils.ref
# After making changes, build again
cargo build --release --features unix
# Compare performance: reference vs patched vs GNU
hyperfine \
'target/release/coreutils.ref <utility> <args>' \
'target/release/coreutils <utility> <args>' \
'/usr/bin/<utility> <args>'
```
This allows you to:
- Compare performance before/after your changes
- Identify performance regressions
- Benchmark against GNU implementation
- Validate that optimizations provide real improvements
### Fuzzing
We use cargo-fuzz for finding bugs and ensuring GNU compatibility. Fuzzers are located in `fuzz/fuzz_targets/`.
To run fuzzing:
```bash
cargo +nightly fuzz run fuzz_<FUZZER> -- -max_total_time=50 -print_final_stats=1
```
When the fuzzer finds an issue, it should be reported in this format:
**title:** `<utility>` - handles `<input>` input differently from GNU (`<description>`)
**Rust (incorrect - returns error)**
```bash
$ TZ=America/New_York cargo run -p uu_<utility> -- -d '<input>'
# Error: <error_message>
# Exit code: <code>
```
**GNU (correct)**
```bash
$ TZ=America/New_York /usr/bin/<utility> -d '<input>'
# Output: <expected_output>
# Exit code: 0
```
Bug Found by Fuzzer
### Documentation Generation
We generate multiple types of documentation:
**Man Pages**
```bash
# Generate man pages for specific utilities
cargo run --features uudoc --bin uudoc manpage <utility>
# Example: Generate man page for ls
cargo run --features uudoc --bin uudoc manpage ls
# Man pages are output to stdout, redirect to save
cargo run --features uudoc --bin uudoc manpage ls > ls.1
```
**Help Text**
- Help text is defined in each utility's argument parser (clap)
- Uses localized strings from .ftl files in `locales/` directories
- Test help output with: `./target/debug/coreutils <utility> --help`
**API Documentation**
```bash
# Generate Rust documentation
cargo doc --features unix --no-deps --open
# Documentation for uucore shared library
cargo doc -p uucore --no-deps --open
```
**Updating Documentation**
- Help text: Update clap argument definitions and corresponding .ftl locale files
- Man pages: Regenerate after changing command-line interface
- Code docs: Add /// comments for public APIs in uucore
- Always verify docs build without warnings: `cargo doc --features unix`
## Common Development Tasks
### Debugging Utilities
```bash
# Debug a specific utility
rust-gdb --args target/debug/coreutils ls
(gdb) b ls.rs:79
(gdb) run
# Run single utility with debugging
cargo run --bin <utility> -- <args>
cargo run --features cat -p uu_cat -- file.txt
```
### Platform-Specific Development
- Use `#[cfg(unix)]`, `#[cfg(windows)]` for conditional compilation
- Implement in `platform/` subdirectories when needed
- Test on multiple platforms via CI or local VMs
### Working with GNU Test Suite
- Install `quilt` for patch management
- Follow instructions from `util/build-gnu.sh` for first-time setup
- Use `util/remaining-gnu-error.py` to see failing tests
- GNU tests require individual utility binaries (not multicall)
### Committing Changes
When creating commits:
- Run `cargo fmt` before committing to format code
- Don't reference Code Claude
- Use concise one-line commit messages prefixed with the program name
- Don't write long commit message. Don't add "code claude" to the commit message
* I don't want to see Generated with [Claude Code](https://claude.ai/code)
- Format: `<program>: <description>` (e.g., `join: add benchmarks`)
- Focus on what was changed rather than why
- Don't reference code claude at all in the commit message
Remember: This project maintains strict compatibility with GNU coreutils behavior while improving cross-platform support and code safety through Rust.