Blueprint

Blueprint is the package management and build backend of Compass, a Funtoo-inspired Linux package management ecosystem written in Rust.

Blueprint is responsible for package metadata, dependency resolution, build execution, compiler and build-system abstraction, package state, and communication with frontends such as Calque.

Status: Early development (0.0.x)

Architecture

Blueprint is designed as a backend rather than a monolithic package management application.

                         Compass
                            │
             ┌──────────────┼──────────────┐
             │              │              │
          Calque          Aqua         Blueprint
         frontend       system admin     backend
                            │              │
                            │        ┌─────┴─────┐
                            │        │           │
                         system    packages    builds
                                      │
                         ┌────────────┼────────────┐
                         │            │            │
                       Kits         .cpkg       .bspec
                                      │            │
                                      │         build systems
                                      │
                                    .cspec
                                      │
                                  compilers

Components

• Blueprint. Package and build backend, daemon, dependency resolver, and package database.
• Calque. Terminal package management frontend.
• Kits. Curated collections of package definitions.
• .cpkg. Package recipe and manifest format.
• .bspec. Build-system specification format.
• .cspec. Compiler and toolchain specification format.

Goals

Blueprint aims to provide:

• Funtoo-style package management
• USE flags
• Slots and simultaneous package versions
• Granular profiles
• Configurable toolchains
• Compiler abstraction through CSpecs
• Build-system abstraction through BSpecs
• Package recipes through CPKGs
• Kit-based package distribution
• Dependency resolution
• Reproducible and configurable builds
• A daemon-based backend
• A clean IPC interface for package-management frontends
• Native Rust performance and concurrency

Blueprint is intended to retain the useful ideas and workflow of Gentoo and Funtoo while providing a more modular architecture.

Packages

Packages are described using .cpkg files.

A package manifest can describe information such as:

[package]
name = "curl"
category = "net-misc"
version = "8.16.0"
license = "curl"

[use.ssl]
description = "Enable SSL/TLS support"
default = true

[use.http2]
description = "Enable HTTP/2 support"
default = true

[dependencies]
build = [
    "sys-libs/glibc"
]

runtime = [
    "sys-libs/glibc"
]

The .cpkg format is declarative. Packages describe what they are and what they require. Blueprint determines how they are resolved and built.

USE Flags

USE flags are a first-class part of Blueprint.

System-wide USE configuration lives under:

/etc/blueprint/use/

For example:

[use]
ssl = true
http2 = true
wayland = true
X = false
systemd = false
pipewire = true

Package-specific configuration can override normal defaults according to Blueprint's configuration precedence rules.

USE flags can affect both dependencies and build configuration.

Calque will provide familiar Gentoo-style CLI operations for manipulating USE flags.

Profiles

Profiles provide system-wide policy.

Profiles can control things such as:

• Default USE flags
• Architecture
• Toolchain
• Package policies
• Enabled kits
• System configuration
• Supported features

Profiles are intended to be composable and granular rather than being one monolithic configuration.

make.conf

Local system configuration is provided through:

/etc/make.conf

Among other things, make.conf can define the system's compiler and global build flags.

For example:

[toolchain]
compiler = "clang"

[build]
jobs = 16

CFLAGS = ["-O2", "-pipe"]
CXXFLAGS = ["-O2", "-pipe"]
LDFLAGS = []

The selected compiler is then resolved through a CSpec.

CSpecs

A CSpec describes a compiler and toolchain.

This allows packages to remain independent of a specific compiler.

For example, a system may select:

clang

through make.conf, causing Blueprint to use the corresponding CSpec.

Another system can select:

gcc

without changing the package recipe.

Conceptually:

make.conf
    │
    ▼
selected compiler
    │
    ▼
CSpec
    │
    ▼
concrete compiler environment

CSpecs are intended to abstract:

• C compiler
• C++ compiler
• Linker
• Assembler
• Archiver
• Compiler flags
• Language standards
• Target configuration
• Toolchain capabilities

BSpecs

A BSpec describes how a build system should be used.

Blueprint will provide built-in BSpecs for common build systems, including:

• Make
• CMake
• Meson
• Autotools
• Cargo
• Shell-based builds

The package recipe can declare its build system without embedding all of the implementation details itself.

Conceptually:

.cpkg
  │
  ▼
BSpec
  │
  ▼
build system
  │
  ▼
CSpec
  │
  ▼
compiler/toolchain

Build Process

Blueprint uses a phased build model:

fetch
  ↓
unpack
  ↓
prepare
  ↓
configure
  ↓
compile
  ↓
install
  ↓
package

Build systems can implement or participate in these phases through BSpecs.

Blueprint creates a working environment containing values such as:

WORKDIR
DESTDIR
PREFIX
SYSROOT

Kits

Compass uses kits as its primary curated package collections.

A kit is more than simply a Git repository. It represents a managed, versioned collection of package definitions.

Blueprint stores locally managed kits under:

/var/lib/blueprint/kits/

For example:

/var/lib/blueprint/kits/
├── core/
├── desktop/
└── lang/

Meta-Repo

Compass uses a meta-repository for discovering kits, repositories, profiles, and other ecosystem components.

The meta-repo contains metadata describing where these resources can be obtained.

Conceptually:

meta-repo
    │
    └── index.json
          │
          ├── kits
          ├── repositories
          ├── profiles
          └── specs

This allows a Blueprint installation to bootstrap and discover the rest of the Compass ecosystem from a single source of metadata.

Slots

Blueprint supports multiple versions of a package being installed simultaneously through slots.

For example:

dev-libs/foo
├── 1.x
└── 2.x

Both versions can coexist when their slots permit it.

Daemon

Blueprint runs as a daemon:

blueprintd

The daemon communicates with clients through a Unix socket:

/run/blueprint.sock

This allows Calque to act as a frontend without implementing package resolution or build logic itself.

Conceptually:

Calque
   │
   │ Unix IPC
   ▼
blueprintd
   │
   ├── package database
   ├── dependency resolver
   ├── USE configuration
   ├── kit management
   ├── build system
   ├── compiler selection
   └── package operations

Calque Integration

Calque is the terminal user interface for Blueprint.

Its command-line interface is intentionally familiar to Gentoo users.

For example:

calque --ask --update --changed-use

Short options will follow familiar Gentoo conventions where appropriate.

Calque is responsible for presenting operations to the user. Blueprint is responsible for executing them.

Development

Build Blueprint with Cargo:

cargo build

Run the daemon:

cargo run --bin blueprintd

Run tests:

cargo test

Build an optimized release:

cargo build --release