yap

<div align="center">

# YAP — Yet Another Packager

<img src="assets/images/logo.png" alt="yap-logo" width="240">

<br><br>

[![report card](https://img.shields.io/badge/report%20card-a%2B-ff3333.svg?style=flat-square)](http://goreportcard.com/report/M0Rf30/yap)
[![View examples](https://img.shields.io/badge/learn%20by-examples-0077b3.svg?style=flat-square)](examples)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg?style=flat-square)](https://www.gnu.org/licenses/gpl-3.0)
[![GitHub release](https://img.shields.io/github/release/M0Rf30/yap.svg?style=flat-square)](https://github.com/M0Rf30/yap/releases/latest)

</div>

YAP builds native packages for multiple GNU/Linux distributions from a single PKGBUILD specification. Write your package once; get `.deb`, `.rpm`, `.apk`, and `.pkg.tar.zst` out. All builds run in isolated OCI containers (Docker or Podman).

## Features

- **Multi-format output**: DEB (Debian/Ubuntu), RPM (Fedora/RHEL/Rocky/openSUSE), APK (Alpine), TAR.ZST (Arch)
- **Container isolation**: reproducible builds, no host contamination, Docker and Podman supported
- **PKGBUILD-based**: familiar Arch Linux syntax extended with distribution and architecture overrides
- **Cross-compilation**: build for a different architecture than your host
- **Dependency-aware builds**: sequential by default; opt-in parallel topo-sort via `--parallel`
- **Package signing**: APK RSA + DEB/RPM/Pacman GPG (no `gpg` binary required)
- **SBOM generation**: CycloneDX 1.5 and SPDX 2.3 sidecars
- **Per-format compression**: `zstd`/`gzip`/`xz` for DEB and RPM
- **Changelog support**: `changelog` PKGBUILD field renders to native format per distro
- **Pacman scriptlets**: full 6-hook lifecycle (pre/post install/upgrade/remove)
- **Structured logging**: slog-based, tree rendering for long lines, zero external UI deps

## Installation

One-liner (Linux/macOS, amd64/arm64):

```bash
curl -fsSL https://raw.githubusercontent.com/M0Rf30/yap/main/scripts/install.sh | sh
```

Pin a version or install only one tool:

```bash
curl -fsSL https://raw.githubusercontent.com/M0Rf30/yap/main/scripts/install.sh \
  | sh -s -- --version v2.1.3 --tool yap
```

Manual download:

```bash
wget https://github.com/M0Rf30/yap/releases/latest/download/yap_Linux_x86_64.tar.gz
tar -xzf yap_Linux_x86_64.tar.gz
sudo mv yap /usr/local/bin/
yap version
```

### Build from source

```bash
git clone https://github.com/M0Rf30/yap.git
cd yap
make build
sudo mv yap /usr/local/bin/
```

Requires Docker or Podman:

```bash
# Docker
sudo systemctl enable --now docker && sudo usermod -aG docker $USER

# Podman
sudo systemctl enable --now podman
```

## Quick start

### 1. Project structure

Create `yap.json`:

```json
{
  "name": "My Package",
  "description": "A sample package built with YAP",
  "buildDir": "/tmp/yap-build",
  "output": "artifacts",
  "projects": [
    { "name": "my-package" }
  ]
}
```

### 2. PKGBUILD

Create `my-package/PKGBUILD`:

```bash
pkgname=my-package
pkgver=1.0.0
pkgrel=1
pkgdesc="My awesome application"
arch=('x86_64')
license=('GPL-3.0')
url="https://github.com/user/my-package"
makedepends=('gcc' 'make')
source=("https://github.com/user/my-package/archive/v${pkgver}.tar.gz")
sha256sums=('SKIP')

build() {
    cd "${srcdir}/${pkgname}-${pkgver}"
    make
}

package() {
    cd "${srcdir}/${pkgname}-${pkgver}"
    install -Dm755 my-package "${pkgdir}/usr/bin/my-package"
    install -Dm644 README.md "${pkgdir}/usr/share/doc/${pkgname}/README.md"
}
```

### 3. Build

```bash
# Auto-detect host distro from /etc/os-release
yap build .

# Specific distribution
yap build ubuntu-jammy .
yap build fedora-38 /path/to/project
yap build --cleanbuild --no-makedeps ubuntu-jammy .
```

### 4. Output

```
artifacts/
├── my-package_1.0.0-1_amd64.deb
├── my-package-1.0.0-1.x86_64.rpm
├── my-package-1.0.0-r1.apk
└── my-package-1.0.0-1-x86_64.pkg.tar.zst
```

## Project configuration (`yap.json`)

```json
{
  "name": "My Multi-Package Project",
  "description": "Project description",
  "buildDir": "/tmp/yap-builds",
  "output": "dist",
  "projects": [
    { "name": "package-one", "install": true },
    { "name": "package-two" }
  ]
}
```

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `name` | yes | — | Project collection name |
| `description` | yes | — | Project collection description |
| `buildDir` | yes | — | Build/working directory |
| `output` | yes | — | Output directory for built packages |
| `projects` | yes | — | Ordered array of packages to build |
| `projects[].name` | yes | — | Sub-directory containing the package's PKGBUILD |
| `projects[].install` | no | `false` | Install immediately after build so later packages can depend on it |
| `compressionDeb` / `compressionRpm` | no | `zstd` | Per-format compression: `zstd`/`gzip`/`xz` |
| `signing` | no | — | Signing config (see [Package signing](#package-signing)) |
| `repos` | no | — | Extra package repositories to configure before resolving deps |
| `skipDeps` | no | — | Package names to omit from makedepends |
| `targetArch` | no | host | Cross-compilation target architecture |
| `parallel` | no | `false` | Build independent packages in parallel (topo-sort) |
| `sbom` | no | `false` | Generate SBOM sidecars |
| `sbomFormat` | no | `both` | `cyclonedx`/`spdx`/`both` |

Build ordering between packages comes from the `install` flag and each
PKGBUILD's `depends`/`makedepends` — there is no `yap.json`-level `depends`
field. See [`yap.schema.json`](./yap.schema.json) for the complete spec.

### Editor validation (JSON Schema)

A JSON Schema for `yap.json` ships at the repo root: [`yap.schema.json`](./yap.schema.json).
It documents every supported field (compression, signing, repos, SBOM,
cross-compilation, etc.). Reference it from your `yap.json` for autocomplete and
inline validation in editors that support JSON Schema:

```json
{
  "$schema": "https://www.schemastore.org/yap.json",
  "name": "My Multi-Package Project",
  "...": "..."
}
```

The schema is published on [SchemaStore](https://www.schemastore.org/json/),
so editors (VS Code, JetBrains, Neovim, …) validate any `yap.json` by filename
automatically — no `$schema` line required.

## PKGBUILD extensions

### Distribution-specific variables

Use `__` (double underscore) to override any variable per distribution. Priority (highest wins):

| Priority | Syntax | Example |
|----------|--------|---------|
| 4+ | arch + distro | `depends_x86_64__ubuntu_noble` |
| 4 | arch only | `depends_x86_64` |
| 3 | distro + codename | `depends__ubuntu_noble` |
| 2 | distro | `depends__ubuntu` |
| 1 | package manager | `depends__apt` |
| 0 | base (fallback) | `depends` |

```bash
pkgdesc="My application"
pkgdesc__debian="My application for Debian/Ubuntu"
pkgdesc__ubuntu_noble="My application optimized for Ubuntu 24.04"

makedepends=('gcc' 'make')
makedepends__apt=('build-essential' 'cmake')
makedepends__yum=('gcc-c++' 'cmake3')
makedepends__ubuntu_noble=('build-essential' 'cmake' 'pkg-config' 'libtool')
```

### Architecture-specific variables

```bash
depends=('glibc' 'gcc')
depends_x86_64=('glibc' 'gcc' 'lib32-glibc')
depends_aarch64=('glibc' 'gcc' 'aarch64-linux-gnu-gcc')

source=('https://example.com/generic-source.tar.gz')
source_x86_64=('https://example.com/x86_64-optimized.tar.gz')
source_aarch64=('https://example.com/aarch64-source.tar.gz')

sha256sums=('generic_hash')
sha256sums_x86_64=('x86_64_specific_hash')
sha256sums_aarch64=('aarch64_specific_hash')
```

Supported architectures: `x86_64`, `i686`, `aarch64`, `armv7h`, `armv6h`, `armv5`, `ppc64`, `ppc64le`, `s390x`, `mips`, `mipsle`, `riscv64`, `pentium4`, `any`.

### Checksum types

Supported (strongest to fastest): `b2sums`, `sha512sums`, `sha384sums`, `sha256sums`, `sha224sums`, `cksums`.

```bash
# BLAKE2b (recommended)
b2sums=('2f240f2a3d2f8d8f...')

# CRC32 (format: checksum filesize)
cksums=('1234567890 2048576')
```

### Changelog

```bash
changelog=CHANGELOG.md
```

- **DEB**: `usr/share/doc/<pkgname>/changelog.Debian.gz` (Lintian-compliant)
- **RPM**: native `%changelog` entries embedded in package metadata
- **Pacman**: `.CHANGELOG` in the archive
- **APK**: ignored (no Alpine convention)

### Pacman scriptlets

```bash
pre_install()  { echo "Before install"; }
post_install() { systemctl daemon-reload; }
pre_upgrade()  { systemctl stop myservice; }
post_upgrade() { systemctl start myservice; }
pre_remove()   { systemctl disable myservice; }
post_remove()  { systemctl daemon-reload; }
```

Emitted to `<pkgname>.install` only when at least one hook is defined. `pre/post_upgrade` fall back to `pre/post_install` when absent.

### Package manager-specific fields

```bash
# DEB
section=utils
priority=optional

# RPM
group="Applications/System"
requires_pre=('shadow-utils')

# APK
maintainer="John Doe <john@example.com>"
```

## Supported distributions

| Distribution ID | Format | Package Manager |
|-----------------|--------|-----------------|
| `almalinux` | `.rpm` | yum |
| `alpine` | `.apk` | apk |
| `amzn` | `.rpm` | yum |
| `arch` | `.pkg.tar.zst` | pacman |
| `centos` | `.rpm` | yum |
| `debian` | `.deb` | apt |
| `fedora` | `.rpm` | yum |
| `linuxmint` | `.deb` | apt |
| `opensuse-leap` | `.rpm` | zypper |
| `opensuse-tumbleweed` | `.rpm` | zypper |
| `ol` | `.rpm` | yum |
| `pop` | `.deb` | apt |
| `rhel` | `.rpm` | yum |
| `rocky` | `.rpm` | yum |
| `ubuntu` | `.deb` | apt |

## Model Context Protocol (MCP)

YAP ships a companion `yap-mcp` binary that exposes the same build pipeline
over the [Model Context Protocol](https://modelcontextprotocol.io), so any
MCP-compatible LLM client (Claude Desktop, opencode, Cursor, Zed, Continue,
Goose, …) can drive yap directly.

Quickstart (release binary):

```sh
curl -fsSL https://raw.githubusercontent.com/M0Rf30/yap/main/scripts/install.sh | sh
# then add { "mcpServers": { "yap": { "command": "yap-mcp" } } } to your client config
```

Or pull the standalone OCI image (also listed on