# pacman

The official package manager for Arch Linux. Written in C, it uses libalpm for all package operations.

**Repository**: https://gitlab.archlinux.org/pacman/pacman
**License**: GPL-2.0
**Build System**: Meson

## Project Structure

```mermaid
flowchart TB
    subgraph pacman_repo["pacman repository"]
        subgraph lib["lib/"]
            libalpm["libalpm/<br/>(core library)"]
        end

        subgraph src["src/"]
            pacman_src["pacman/<br/>(CLI frontend)"]
        end

        subgraph scripts["scripts/"]
            makepkg["makepkg"]
            repo_add["repo-add"]
            pacman_key["pacman-key"]
            vercmp["vercmp"]
        end

        subgraph etc["etc/"]
            conf["pacman.conf.in<br/>makepkg.conf.in"]
        end
    end

    pacman_src --> libalpm
```

## libalpm

The Arch Linux Package Management library. All package operations go through this library.

**Location**: `lib/libalpm/`

### Core Source Files

| File | Purpose |
|------|---------|
| `alpm.c` / `alpm.h` | Main API entry points |
| `handle.c` | Handle management (root, dbpath, config) |
| `db.c` | Database operations |
| `package.c` | Package struct and operations |
| `trans.c` | Transaction management |
| `add.c` | Package installation |
| `remove.c` | Package removal |
| `sync.c` | Database synchronization |
| `deps.c` | Dependency resolution |
| `conflict.c` | Conflict detection |
| `dload.c` | Download handling |
| `signing.c` | PGP signature verification |

### Backend Files

| File | Purpose |
|------|---------|
| `be_local.c` | Local database backend (`/var/lib/pacman/local/`) |
| `be_sync.c` | Sync database backend (`/var/lib/pacman/sync/`) |
| `be_package.c` | Package file backend (`.pkg.tar.*` files) |

### Data Flow

```mermaid
sequenceDiagram
    participant User
    participant pacman
    participant libalpm
    participant LocalDB
    participant SyncDB
    participant Mirror

    User->>pacman: pacman -Syu
    pacman->>libalpm: alpm_db_update()
    libalpm->>Mirror: Download DB files
    Mirror-->>libalpm: core.db, extra.db, ...
    libalpm->>SyncDB: Write to /var/lib/pacman/sync/
    libalpm-->>pacman: DB updated
    pacman->>libalpm: alpm_sync_sysupgrade()
    libalpm->>SyncDB: Compare versions
    libalpm->>LocalDB: Check installed
    libalpm-->>pacman: Upgrade list
    pacman->>libalpm: alpm_trans_commit()
    libalpm->>Mirror: Download packages
    libalpm->>LocalDB: Install packages
    libalpm-->>pacman: Complete
    pacman-->>User: Done
```

## pacman CLI

The command-line frontend to libalpm.

**Location**: `src/pacman/`

### Operations

| Flag | Operation | Description |
|------|-----------|-------------|
| `-S` | Sync | Install/upgrade from repositories |
| `-R` | Remove | Uninstall packages |
| `-Q` | Query | Query local database |
| `-U` | Upgrade | Install from package file |
| `-F` | Files | Query files database |
| `-D` | Database | Modify database entries |

### Common Options

| Option | Description |
|--------|-------------|
| `-y` | Refresh package database |
| `-u` | System upgrade |
| `-s` | Search |
| `-i` | Info |
| `-c` | Clean cache |
| `--needed` | Skip if already installed |
| `--noconfirm` | No prompts |

## Scripts

Shell scripts distributed with pacman.

### makepkg

Builds packages from PKGBUILDs.

```bash
makepkg -si  # Build and install
makepkg -src # Build with source, clean
```

### repo-add / repo-remove

Manage custom package repositories.

```bash
repo-add /path/to/repo.db.tar.gz package.pkg.tar.zst
repo-remove /path/to/repo.db.tar.gz packagename
```

### pacman-key

Manage the pacman keyring.

```bash
pacman-key --init              # Initialize keyring
pacman-key --populate archlinux # Add Arch packager keys
pacman-key -r <keyid>          # Receive key
pacman-key --lsign-key <keyid> # Locally sign key
```

### vercmp

Compare version strings.

```bash
vercmp 1.0 2.0   # Returns -1
vercmp 2.0 1.0   # Returns 1
vercmp 1.0 1.0   # Returns 0
```

## Configuration

### /etc/pacman.conf

Main configuration file.

```ini
[options]
RootDir     = /
DBPath      = /var/lib/pacman/
CacheDir    = /var/cache/pacman/pkg/
LogFile     = /var/log/pacman.log
GPGDir      = /etc/pacman.d/gnupg/
HookDir     = /etc/pacman.d/hooks/
HoldPkg     = pacman glibc
Architecture = auto
SigLevel    = Required DatabaseOptional

[core]
Include = /etc/pacman.d/mirrorlist

[extra]
Include = /etc/pacman.d/mirrorlist
```

### Database Paths

| Path | Contents |
|------|----------|
| `/var/lib/pacman/local/` | Installed package metadata |
| `/var/lib/pacman/sync/` | Repository database cache |
| `/var/cache/pacman/pkg/` | Downloaded package cache |

## Building

```bash
meson setup build
meson compile -C build
meson install -C build
```

## See Also

- [[Arch Package Management Ecosystem]] - Overview
- [[alpm.rs]] - Rust bindings to libalpm
- [[pacmanconf.rs]] - Configuration file parser
- [[pacman-key.rs]] - Rust keyring management