RedBear-OS/docs/_CUB_RBPKGBUILD_IMPL_PLAN.md

Red Bear OS Packaging System — Formal Spec v0.1

0. Guiding Principles Native-first All builds target: x86_64-unknown-redox All install artifacts: pkgar packages Cookbook is the build engine RBPKGBUILD = thin wrapper over Cookbook recipe PKGBUILD is input, not execution Never execute arbitrary PKGBUILD on host Always convert → RBPKGBUILD → Cookbook Single tool cub = one CLI binary with subcommands/flags Deterministic builds Controlled env No implicit host dependencies Security-first Sandbox builds Review BUR packages before install

1. RBPKGBUILD Specification

1.1 File Format Format: TOML Filename: RBPKGBUILD Versioned schema format = 1

1.2 Top-Level Sections format = 1

[package] [source] [dependencies] [build] [install] [patches] [compat] [policy]

1.3 [package] [package] name = "ripgrep" version = "14.1.0" release = 1 description = "Fast recursive search tool" homepage = "https://github.com/BurntSushi/ripgrep" license = ["MIT", "Unlicense"] architectures = ["x86_64-unknown-redox"] maintainers = ["name "] Rules name: lowercase, [a-z0-9-_]+ version: upstream version release: integer (Red Bear-specific revision) architectures: must include x86_64-unknown-redox

1.4 [source] [source] sources = [ { type = "tar", url = "...", sha256 = "..." }, { type = "git", url = "...", rev = "..." } ] Supported types tar git Rules All sources must be verifiable (hash or commit) No implicit downloads during build

1.5 [dependencies] [dependencies] build = ["cargo", "rust"] runtime = [] check = [] optional = [] provides = [] conflicts = [] Rules Names must resolve via system mapping Must not reference Arch package names directly

1.6 [build]

Maps directly to Cookbook templates.

[build] template = "cargo" # or configure, cmake, meson, custom Optional fields cargo [build] template = "cargo" release = true features = [] configure [build] template = "configure" args = ["--prefix=/usr"] cmake [build] template = "cmake" build_dir = "build" custom [build] template = "custom"

prepare = [ "patch -p1 < patches/fix.patch" ]

build = [ "make -j$CORES" ]

check = [ "make test" ]

install = [ "make DESTDIR=$DESTDIR install" ]

1.7 [install]

Declarative install mapping.

[install] bins = [ { from = "target/.../rg", to = "/usr/bin/rg" } ]

libs = [] headers = [] docs = ["README.md"] man = [] Rules All paths relative to build output Must install into staged root (DESTDIR)

1.8 [patches] [patches] files = [ "patches/0001-fix-redox.patch" ]

1.9 [compat]

Tracks conversion origin.

[compat] imported_from = "aur" original_pkgbuild = "PKGBUILD" conversion_status = "partial" # full | partial | manual target = "x86_64-unknown-redox"

1.10 [policy] [policy] allow_network = false allow_tests = true review_required = true

2. .RBSRCINFO (Metadata Cache) Purpose Fast search/index No recipe parsing needed Format (INI-like) pkgname = ripgrep pkgver = 14.1.0 pkgrel = 1 pkgdesc = Fast recursive search tool arch = x86_64-unknown-redox

depends = makedepends = cargo rust

source = https://... sha256sums = ...

provides = conflicts =

3. BUR Repository Spec Structure ripgrep/ RBPKGBUILD .RBSRCINFO patches/ import/ PKGBUILD report.txt

4. cub CLI Specification

4.1 General Single binary: cub Rust implementation Subcommands via flags (not separate tools)

4.2 Core Commands Search cub -Ss Install cub -S

Resolution order:

official repo BUR (RBPKGBUILD) AUR import (optional flag) Build local cub -B . Fetch recipe cub -G Inspect cub -Pi <package|RBPKGBUILD> Update system cub -Sua Clean cache cub -Sc Convert AUR cub --import-aur <url|name>

Outputs:

RBPKGBUILD patches/ report.txt

5. PKGBUILD → RBPKGBUILD Conversion

5.1 Conversion Stages

Stage 1 — Parse

Extract:

pkgname pkgver depends source functions

Stage 2 — Normalize Resolve arrays Expand variables Strip bash constructs

Stage 3 — Map

PKGBUILD RBPKGBUILD pkgname package.name pkgver package.version depends dependencies.runtime makedepends dependencies.build source source.sources

Stage 4 — Detect build system

Patterns:

Pattern Template cargo build cargo ./configure configure cmake cmake meson meson none custom

Stage 5 — Generate RBPKGBUILD Fill required fields Insert detected template Add compat section

Stage 6 — Patch generation

If:

/usr/lib/systemd /proc systemctl

→ generate:

patch stub warning entry Stage 7 — Report

report.txt

Conversion: PARTIAL

Warnings:

• Uses systemd
• Hardcoded /usr/lib

Actions required:

• Patch install paths
• Remove systemctl usage

5.2 Conversion Modes Mode Description full fully automated partial needs patches manual user intervention

6. Build Execution Environment TARGET=x86_64-unknown-redox GNU_TARGET=x86_64-redox

DESTDIR=/build/stage PREFIX=/usr

CORES=8 Sandbox Rules No network after fetch Isolated filesystem No host writes Controlled PATH Execution Flow cub → parse RBPKGBUILD → generate Cookbook recipe → run build → stage files → create pkgar → install

7. Dependency Mapping Mapping file [mapping] glibc = "relibc-compat" base-devel = "build-base"

8. Error Handling Hard Fail Missing source hash Unknown build template Unsupported architecture Soft Fail (warn) Linux-specific paths missing tests partial conversion

9. Security Model BUR = untrusted Require review on first install Signed packages preferred Build sandbox enforced

10. MVP Scope MUST implement RBPKGBUILD parser Cookbook adapter pkgar integration cub CLI core commands basic AUR conversion dependency mapping sandbox build MUST NOT implement yet full PKGBUILD shell compatibility split packages pacman compatibility hook system

11. Final Definition

RBPKGBUILD is a declarative Red Bear build wrapper over Cookbook recipes. cub is a Rust CLI tool that manages installation, building, and conversion from AUR PKGBUILD into RBPKGBUILD, using BUR as the community repository. All builds target x86_64-unknown-redox and produce pkgar packages.