# paru

Feature-rich AUR (Arch User Repository) helper written in Rust. Wraps pacman functionality and provides extensive AUR package management capabilities.

**Repository**: https://github.com/Morganamilo/paru
**License**: GPL-3.0
**Version**: 2.1.0
**Rust Version**: 1.87+

## Overview

Paru automates the process of building and installing packages from the AUR:
1. Search and select AUR packages
2. Resolve dependencies (AUR and official repos)
3. Download PKGBUILDs from AUR
4. Build packages with makepkg
5. Install with pacman

```mermaid
flowchart TB
    subgraph user["User"]
        cmd["paru -S package"]
    end

    subgraph paru["paru"]
        config["Config<br/>(parse paru.conf, pacman.conf)"]
        resolver["Resolver<br/>(dependency resolution)"]
        download["Download<br/>(fetch PKGBUILDs)"]
        build["Build<br/>(makepkg)"]
        install["Install<br/>(pacman -U)"]
    end

    subgraph external["External Services"]
        aur["AUR RPC API"]
        git["AUR Git repos"]
        mirrors["Arch Mirrors"]
    end

    cmd --> config
    config --> resolver
    resolver --> aur
    resolver --> download
    download --> git
    download --> build
    build --> install
    install --> mirrors
```

## Dependencies

| Crate | Purpose |
|-------|---------|
| `alpm` | libalpm bindings |
| `alpm-utils` | Configuration utilities |
| `pacmanconf` | Parse pacman.conf |
| `raur` | AUR RPC API client |
| `srcinfo` | PKGBUILD/SRCINFO parsing |
| `aur-depends` | AUR dependency resolution |
| `aur-fetch` | Git-based PKGBUILD fetching |

## Usage

### Sync Operations (like pacman -S)

```bash
paru -S package         # Install package (searches AUR too)
paru -Syu               # Full system upgrade (repos + AUR)
paru -Ss query          # Search repos and AUR
paru package            # Shorthand for -S
```

### Query Operations

```bash
paru -Qu                # List upgradable packages
paru -Qua               # List upgradable AUR packages
paru -Qi package        # Package info
```

### AUR-Specific

```bash
paru -a                 # AUR-only operations
paru -Sua               # Upgrade AUR packages only
paru --devel            # Check -git packages for updates
```

### Build Operations

```bash
paru -G package         # Download PKGBUILD without building
paru -Bi .              # Build and install from local PKGBUILD
```

### Interactive Search

```bash
paru                    # Interactive search (no args)
paru query              # Search and select interactively
```

## Module Structure

```mermaid
flowchart TB
    subgraph entry["Entry"]
        main["main.rs"]
        lib["lib.rs<br/>run()"]
    end

    subgraph config_mod["Configuration"]
        config["config.rs<br/>Config struct"]
        command_line["command_line.rs"]
        args["args.rs"]
    end

    subgraph ops["Package Operations"]
        install["install.rs<br/>Installer"]
        download["download.rs"]
        upgrade["upgrade.rs"]
        sync["sync.rs"]
        remove["remove.rs"]
        query["query.rs"]
    end

    subgraph aur["AUR Management"]
        pkgbuild["pkgbuild.rs<br/>PkgbuildRepo"]
        repo["repo.rs"]
        devel["devel.rs<br/>-git packages"]
        resolver["resolver.rs"]
    end

    subgraph ui["User Interface"]
        search["search.rs"]
        fmt["fmt.rs"]
        info["info.rs"]
        news["news.rs"]
    end

    subgraph build_exec["Build/Execution"]
        exec["exec.rs<br/>Command execution"]
        chroot["chroot.rs"]
    end

    main --> lib
    lib --> config_mod
    lib --> ops
    ops --> aur
    ops --> build_exec
    lib --> ui
```

## Configuration

### paru.conf

Located at `/etc/paru.conf` or `~/.config/paru/paru.conf`.

```ini
[options]
BottomUp                # Show search results bottom-up
SudoLoop               # Keep sudo alive during builds
CleanAfter             # Clean build dir after install
Devel                  # Check -git packages for updates
ProvideFlags = --provides # Additional flags

[bin]
Makepkg = /usr/bin/makepkg
Pacman = /usr/bin/pacman
Git = /usr/bin/git
```

### Key Options

| Option | Description |
|--------|-------------|
| `BottomUp` | Search results with numbers at bottom |
| `SudoLoop` | Keep sudo session alive |
| `CleanAfter` | Remove build files after install |
| `Devel` | Check VCS packages for updates |
| `ProvideFlags` | Makepkg flags for provides |
| `SkipReview` | Don't prompt for PKGBUILD review |
| `BatchInstall` | Install all built packages at once |
| `ChrootDir` | Use chroot for builds |

## Build Flow

```mermaid
sequenceDiagram
    participant User
    participant paru
    participant AUR
    participant makepkg
    participant pacman

    User->>paru: paru -S aur-package
    paru->>AUR: Query RPC API
    AUR-->>paru: Package metadata
    paru->>paru: Resolve dependencies
    paru->>AUR: Clone git repo
    AUR-->>paru: PKGBUILD
    paru->>User: Show PKGBUILD for review
    User-->>paru: Approve
    paru->>makepkg: Build package
    makepkg-->>paru: Built .pkg.tar.zst
    paru->>pacman: Install package
    pacman-->>paru: Installed
    paru-->>User: Complete
```

## Features

| Feature | Description |
|---------|-------------|
| `git` | Target libalpm-git API |
| `generate` | Generate libalpm bindings at build time |
| `static` | Static linking with libalpm |
| `mock` | Enable mock testing |
| `mock_chroot` | Mock with chroot support |

## Building

```bash
# Standard build
cargo build

# With binding generation (requires clang)
cargo build --features generate

# For libalpm-git
cargo build --features git

# Run tests
cargo test --features mock
```

## Development Package Tracking

Paru tracks VCS packages (`-git`, `-svn`, etc.) and checks for upstream updates:

```bash
paru -Sua --devel      # Check and upgrade -git packages
```

Stores last-seen commit hashes in `~/.local/share/paru/devel.json`.

## Chroot Builds

Build packages in a clean chroot environment:

```bash
paru -S package --chroot
```

Requires `devtools` package and configured chroot directory.

## See Also

- [[Arch Package Management Ecosystem]] - Overview
- [[alpm.rs]] - libalpm bindings used by paru
- [[pacmanconf.rs]] - Configuration parsing
- [[pacman]] - Underlying package manager