# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Paru is a feature-rich AUR (Arch User Repository) helper written in Rust. It wraps pacman functionality and provides extensive AUR package management capabilities including dependency resolution, package building, installation, and upgrades.

## Building and Running

### Build Commands
```bash
cargo build                           # Standard build
cargo build --features generate       # Build with libalpm bindings generation (requires clang)
cargo build --features git            # Build against libalpm-git API
cargo run -- <args>                   # Run paru with arguments
```

### Feature Flags
- `backtrace`: Kept for backwards compatibility (does nothing)
- `git`: Target the libalpm-git API
- `generate`: Generate libalpm bindings at build time (requires clang)
- `static`: Static linking with libalpm
- `mock`: Enable mock testing framework
- `mock_chroot`: Enable mock with chroot support

### Testing
```bash
cargo test --features mock            # Run test suite
cargo fmt -- --check                  # Check formatting
cargo fmt                             # Format code
```

### Custom libalpm
To build against a custom libalpm:
```bash
ALPM_LIB_DIR=/path/to/custom/libalpm cargo build --features generate
LD_LIBRARY_PATH=/path/to/custom/libalpm ./target/debug/paru
```

### Translation Testing
```bash
./scripts/mkmo locale/                # Build translations
LOCALE_DIR=locale/ cargo run -- <args> # Run with local translations
```

## Code Architecture

### Entry Point
- `main.rs`: Minimal entry point that calls `run()` from lib.rs
- `lib.rs`: Main entry point containing the async `run()` function that orchestrates all operations

### Core Modules
- `config.rs`: Configuration parsing from paru.conf and pacman.conf, maintains the global `Config` struct with `Alpm` handle
- `command_line.rs`: Command-line argument parsing
- `args.rs`: Argument structure and utilities

### Package Operations
- `install.rs`: Main installation logic, AUR package building, dependency resolution via the `Installer` struct
- `download.rs`: AUR package downloading and git operations
- `upgrade.rs`: Package upgrade detection and handling
- `sync.rs`: Pacman sync operations
- `remove.rs`: Package removal operations
- `query.rs`: Package query operations
- `search.rs`: Interactive search functionality for packages

### AUR and Repository Management
- `pkgbuild.rs`: PKGBUILD parsing and local repository management via `PkgbuildRepo`
- `repo.rs`: Repository database operations
- `devel.rs`: Development package tracking (e.g., -git packages)
- `resolver.rs`: Dependency resolution logic
- `clean.rs`: Cache and package cleaning

### Build and Execution
- `exec.rs`: External command execution (pacman, makepkg, etc.)
- `chroot.rs`: Chroot build environment support

### User Interface
- `fmt.rs`: Output formatting and colorization
- `info.rs`: Package information display
- `completion.rs`: Shell completion generation
- `help.rs`: Help text generation
- `news.rs`: Arch Linux news fetching and display

### Utilities
- `util.rs`: Miscellaneous utility functions
- `auth.rs`: Authentication handling
- `keys.rs`: PGP key management
- `stats.rs`: Statistics tracking
- `order.rs`: Package ordering
- `mock.rs`: Mock implementations for testing (feature-gated)

### Key Data Flow
1. `main.rs` → `lib.rs::run()` parses args and creates `Config`
2. `Config::new()` initializes pacman/alpm, parses configs
3. Operations route through `lib.rs::run2()` which dispatches to appropriate modules
4. `install.rs` handles complex AUR workflows: dependency resolution, downloading, building, installing
5. `exec.rs` orchestrates external commands (pacman, makepkg, git)

### Important Patterns
- The `Config` struct is passed mutably through most operations and contains the `Alpm` handle
- `RaurHandle` type alias switches between real `raur::Handle` and `mock::Mock` based on features
- Error handling uses anyhow with custom `Status` types for exit codes
- Async/await throughout with tokio runtime
- Translations via the `tr!` macro (tr crate)

## CI/CD

Tests run on GitHub Actions in ArchLinux containers:
- Standard build: `cargo build --locked --features generate`
- Tests: `cargo test --locked --features generate,mock`
- Also tests against pacman-git with `--features git,generate,mock`

## Configuration

- Main config: `paru.conf` (see `paru.conf(5)` manpage)
- Pacman config: Uses system pacman.conf
- Config locations: `$PARU_CONF`, `/etc/paru.conf`, `~/.config/paru/paru.conf`

## Development Notes

- Always run `cargo fmt` before committing
- The codebase uses the `alpm` crate for libalpm bindings
- AUR operations use the `raur` crate for AUR RPC
- PKGBUILD parsing via `srcinfo` crate
- Dependency resolution via `aur-depends` crate