RedBear-OS/local/docs/CUB-PACKAGE-MANAGER.md

Cub — Red Bear OS Package Manager

Status: Active (redesign complete 2026-05) Location: local/recipes/system/cub/ Type: Runtime package manager (runs inside Red Bear OS) Dependencies: pkgutils (redox-pkg), pkgar

Overview

Cub is the Red Bear OS package manager — an AUR-inspired tool for searching, fetching, building, installing, and managing packages. It serves as the bridge between Red Bear OS and the Arch Linux AUR ecosystem, converting PKGBUILD recipes into Red Bear OS recipe.toml files and producing pkgar packages.

Cub runs as a regular user inside Red Bear OS, managing packages in ~/.cub/ and installing them via the pkgar system.

Architecture

cub (workspace)
├── cub-lib/          ← Core library (13 modules)
│   ├── aur.rs        ← AUR RPC v5 client (search, info)
│   ├── storage.rs    ← ~/.cub/ user-local storage manager
│   ├── cook.rs       ← recipe cooking (shells out to repo cook)
│   ├── pkgbuild.rs   ← Enhanced AUR PKGBUILD parser
│   ├── recipe.rs     ← Unified recipe.toml generation
│   ├── converter.rs  ← Legacy PKGBUILD converter (preserved)
│   ├── cookbook.rs   ← recipe.toml generation from RBPKGBUILD
│   ├── rbpkgbuild.rs ← RBPKGBUILD TOML type definitions
│   ├── package.rs    ← pkgar archive creation
│   ├── sandbox.rs    ← Build sandbox environment
│   ├── deps.rs       ← Arch Linux → Redox dependency name mapping
│   ├── rbsrcinfo.rs  ← .RBSRCINFO metadata format
│   └── error.rs      ← CubError enum (11 variants)
├── cub-tui/          ← Terminal UI (ratatui 0.30 + termion)
│   ├── app.rs        ← TUI app struct and event loop
│   ├── theme.rs      ← Red Bear color theme
│   ├── views/        ← search, info, install, build, query
│   └── widgets/      ← Reusable TUI components
└── cub-cli/          ← CLI binary entry point
    └── main.rs       ← 14 Arch-style switches + TUI launcher

CLI Reference

Operation Modes

Cub supports three operation modes mirroring pacman:

Mode	Flag	Description
Sync	-S	Install, search, refresh, upgrade packages
Query	-Q	Manage locally installed packages
Remove	-R	Uninstall packages

Sync Operations (-S)

cub -S <pkg>         # Install from official repo or BUR/AUR
cub -Ss <query>      # Search official repo + cached BUR + AUR
cub -Si <pkg>        # Show AUR package info (description, deps, votes)
cub -Sy              # Refresh BUR cache + verify AUR connectivity
cub -Syu             # Full system upgrade (sync + update all)
cub -Sua             # Update AUR packages only
cub -Sc              # Clean package caches

Build Operations (-B, -G)

cub -B <dir>         # Build local RBPKGBUILD directory → pkgar + install
cub -G <pkg>         # Fetch AUR PKGBUILD, convert to recipe, save to ~/.cub/

Query Operations (-Q)

cub -Q               # List all installed packages
cub -Qi <pkg>        # Show installed package details (version, deps, size)
cub -Ql <pkg>        # List files installed by a package

Remove Operations (-R)

cub -R <pkg>         # Uninstall a package

Other Commands

cub -Pi <target>     # Inspect installed package or local RBPKGBUILD
cub --import-aur <target>  # Import AUR package (clone + convert PKGBUILD)
cub -T, --no-tui     # Disable TUI mode (use CLI directly)
cub                  # No subcommand: launch TUI

User Storage (~/.cub/)

Cub maintains all user-local data in ~/.cub/ with four subdirectories:

~/.cub/
├── recipes/          # Converted recipe.toml + RBPKGBUILD + patches
│   └── <pkgname>/
│       ├── recipe.toml    ← Generated cookbook recipe
│       ├── RBPKGBUILD     ← Red Bear PKGBUILD (TOML format)
│       ├── .RBSRCINFO     ← Metadata for dependency resolution
│       └── patches/       ← Local patches
├── sources/          # Cached source tarballs and git clones
├── repo/             # Built pkgar packages organized by target
│   └── x86_64-unknown-redox/
│       ├── <pkg>.pkgar    ← Signed package archive
│       └── <pkg>.toml     ← Package metadata
└── config/           # Cub configuration and keyring

AUR Integration

Cub accesses the Arch User Repository via the AUR RPC v5 API:

Endpoint	Method	Cub Function
/rpc?v=5&type=search&arg=<q>	GET	AurClient::search(query)
/rpc?v=5&type=info&arg[]=<pkg>	GET	AurClient::info(pkgs)
https://aur.archlinux.org/<pkg>.git	git clone	-G <pkg> (import)

PKGBUILD Conversion

When importing from AUR (-G or --import-aur):

1. Clone the AUR git repository
2. Parse PKGBUILD bash script — extracts pkgname, pkgver, pkgrel, depends, makedepends, source, sha256sums, optdepends
3. Detect build template (cargo, cmake, meson, configure, custom)
4. Map Arch dependencies to Redox equivalents (glibc→relibc, openssl→openssl3, systemd→removed, etc.)
5. Generate RBPKGBUILD (TOML format) and .RBSRCINFO
6. Generate recipe.toml compatible with the Red Bear cookbook
7. Save all files to ~/.cub/recipes/<pkgname>/

Dependency Mapping

Cub maintains a 44-entry mapping table (deps.rs) translating Arch Linux package names to their Redox/Red Bear equivalents:

Arch Package	Redox Mapping	Notes
glibc	relibc	Redox uses relibc instead of glibc
openssl	openssl3	Version-specific mapping
gcc, make	build-base	Meta-package for build tools
systemd	(removed)	Unavailable on Redox — warning issued
libx11, libxcb	(mapped)	X11 unavailable — manual port needed
linux-api-headers	(removed)	Linux-specific — not applicable
wayland	wayland	Direct 1:1 mapping when available
qt6-base	qtbase	Qt 6 base libraries
dbus	dbus	Direct 1:1 mapping

Unknown dependencies are passed through unchanged with a warning.

Build Flow

cub -B <dir>                    # Build local RBPKGBUILD
  │
  ├─ 1. Parse RBPKGBUILD        ← Validate TOML format
  ├─ 2. Create sandbox          ← .cub-sandbox/{build,stage,sysroot}
  ├─ 3. Generate recipe.toml    ← cookbook::generate_recipe()
  ├─ 4. repo cook <recipe_dir>  ← Shell out to cookbook (cook.rs)
  ├─ 5. Locate stage directory  ← Find populated stage dir
  ├─ 6. Create pkgar archive    ← pkgar::create_with_flags()
  ├─ 7. Generate .toml metadata ← Package name, version, deps
  └─ 8. Install via pkgutils    ← library.install() + apply()

Sandbox Environment

The build sandbox sets these environment variables for repo cook:

Variable	Value
COOKBOOK_SOURCE	Source directory path
COOKBOOK_STAGE	Stage (install) directory
COOKBOOK_SYSROOT	Sysroot with built dependencies
COOKBOOK_TARGET	x86_64-unknown-redox
COOKBOOK_HOST_TARGET	x86_64-unknown-linux-gnu
COOKBOOK_MAKE_JOBS	CPU core count
DESTDIR	Alias for COOKBOOK_STAGE
TARGET	x86_64-unknown-redox
GNU_TARGET	x86_64-redox

TUI (Terminal UI)

Cub launches a ratatui-based TUI by default when run without a subcommand. Use --no-tui / -T for direct CLI operation.

Views

View	Description	Key Bindings
Search	Search AUR by name/description	Type query, Enter to search
Info	Detailed package view	Shows deps, version, votes, description
Install	Install progress with log output	Shows command output in real-time
Build	Build progress for local recipes	Shows stage/progress indicators
Query	Browse locally installed packages	Arrows to navigate, Enter for details

Global Keys

Key	Action
q / Esc	Quit TUI
/	Focus search bar
Tab	Cycle between views
↑ ↓	Navigate lists
Enter	Select / confirm

Theme

Red Bear color theme:

• Background: dark (terminal default)
• Accent: red (#CC0000)
• Text: white
• Selected: red highlight on white text
• Borders: gray

Configuration

Environment Variables

Variable	Default	Description
CUB_BUR_REPO_URL	https://gitlab.redox-os.org/redox-os/bur.git	BUR repository URL
CUB_PKGAR_SECRET_KEY	(auto-detected)	Path to pkgar secret key
CUB_PKGAR_PUBKEY_DIR	(auto-detected)	Directory containing public key

Key Locations

Path	Purpose
~/.pkg/id_ed25519.toml	Secret key (pkgar signing)
/etc/pkg/id_ed25519.toml	System secret key fallback
/pkg/id_ed25519.toml	System secret key fallback 2
~/.cub/config/	Cub-specific configuration

Recipe Format

Cub generates standard Red Bear OS recipe.toml files compatible with the repo cook command:

[source]
git = "https://github.com/user/repo.git"
branch = "main"
rev = "abc123"

[build]
template = "cargo"
dependencies = ["cargo", "pkg-config"]

[package]
dependencies = ["relibc", "openssl3"]
version = "1.0.0-1"
description = "Example package converted from AUR"

Template Detection

Cub auto-detects the correct build template from PKGBUILD build() contents:

PKGBUILD pattern	recipe.toml template
cargo build, cargo install	cargo
cmake	cmake
meson setup, meson	meson
./configure, configure	configure
Other	custom

Linuxism Detection

During PKGBUILD conversion, cub detects Linux-specific patterns and issues warnings for manual intervention:

Pattern	Warning
systemctl	systemctl not available on Redox
/usr/lib/systemd	Linux-specific paths
systemd as dependency	Dependency removed (unavailable)
/proc references	May require Redox-specific adaptation

Build Recipe

Cub is built as a standard Cargo workspace:

# local/recipes/system/cub/recipe.toml
[source]
path = "source"

[build]
template = "cargo"
cargopath = "cub-cli"

[package]
dependencies = ["pkgutils"]

The recipe builds cub-cli which depends on cub-lib and optionally cub-tui. The default-members of the workspace is cub-cli (the binary).

Protected Recipe

Cub is listed as a protected recipe in src/cook/fetch.rs — it cannot be re-fetched online. Sources are archived in sources/redbear-0.1.0/.

Error Handling

Cub uses an 11-variant CubError enum via thiserror:

Variant	Description
Io	Filesystem errors
TomlParse	recipe.toml parse failures
TomlSerialize	recipe.toml serialization failures
InvalidPkgbuild	Malformed RBPKGBUILD
BuildFailed	repo cook or build failures
PackageNotFound	Missing package in repo/BUR
Conversion	PKGBUILD conversion errors
Dependency	Dependency resolution failures
Aur	AUR RPC errors (HTTP, parse, rate limit)
Storage	~/.cub/ storage errors
Network	General network failures
Sandbox	Build sandbox errors

Limitations

1. Build tools required: repo cook requires the build toolchain (cross-compiler, host tools) which is not yet available inside Red Bear OS. Until build tools are ported, cub build (cooking) only works on build hosts. Runtime-only operations (search, install, query, remove) work inside Red Bear OS.

2. Single source support: recipe.toml generation currently supports only one primary source per recipe (AUR packages with multiple sources need manual adjustment).

3. No binary repository: cub currently fetches from AUR (source-based) and BUR (Red Bear package recipes). There is no binary package repository — all packages must be built from source.

4. AUR JSON parsing: The AUR module uses a hand-written JSON parser to avoid adding serde_json as a dependency. This works for the AUR RPC response format but is less robust than serde_json.

5. TUI test coverage: The cub-tui crate has no unit tests. Views are rendering-only and verified via cargo build.

Future Work

• Port build tools inside Red Bear OS to enable full cooking at runtime
• Add binary package repository support for pre-built packages
• Implement serde_json dependency for robust AUR JSON parsing
• Add TUI unit tests for view rendering
• Support multi-source PKGBUILDs in recipe.toml generation
• Add package signing verification on install
• Implement delta updates for large packages