Skip to content

Instantly share code, notes, and snippets.

@binarycraft007
Created April 14, 2026 17:13
Show Gist options
  • Select an option

  • Save binarycraft007/e8ae1ca67bfd7ef35716e0a81d0bfe5c to your computer and use it in GitHub Desktop.

Select an option

Save binarycraft007/e8ae1ca67bfd7ef35716e0a81d0bfe5c to your computer and use it in GitHub Desktop.
zest architecture

Zest: Architecture & Design Philosophy

Zest (Zig-powered Embedded Systems Tool) is a modern, high-performance build system and distribution kit for embedded Linux. It aims to provide the flexibility of OpenWrt and the simplicity of Buildroot, while leveraging the safety and cross-compilation prowess of the Zig toolchain.

1. Core Vision

Traditional embedded build systems often suffer from "Makefile-hell" and global state issues. Zest replaces fragile shell scripting with a strictly typed, declarative build graph in Zig.

The goal is to move from "building a system" to "composing a system" from isolated, reproducible components.


2. Key Architectural Pillars

A. Hermetic Per-Package Sysroots

To ensure absolute reproducibility and prevent "hidden dependency" bugs, Zest implements Isolated Sysroots.

  • Isolation: Each package is built against a unique sysroot containing only its declared dependencies.
  • Mechanism: Using Zig's std.Build graph, Zest constructs a temporary directory tree for each build task.
  • Benefit: A package cannot accidentally link against a library that happened to be on the host or in a global buffer. If it's not in the .zon manifest, the compiler won't see it.

B. The Zig-Native Toolchain Wrapper

Zest treats Zig as a first-class compiler for C/C++ legacy code.

  • The Wrapper: A custom Zig executable wraps zig cc and zig c++, passing the correct --target and --sysroot flags automatically.
  • Transparent Integration: This allows Zest to compile GNU Autotools, Meson, and Kconfig-based projects (like the Linux Kernel and Busybox) with zero changes to upstream source code.

C. APK-Centric Packaging

Zest uses the APK (Alpine Package Keeper) format for its binary distribution.

  • Efficiency: APKs are lightweight, fast to install, and support robust dependency resolution.
  • Metadata: Every package generates a signed .apk artifact, including metadata for architectures, versions, and provides/depends relationships.

D. Device-Aware Image Generation

The final stage of a Zest build is the Image Generation Step, which transforms built packages into a bootable system image.

  • Composition: Instead of a simple tar of a build directory, Zest uses a "Manifest + DeviceInfo" approach.
  • Process:
    1. Dependency Resolution: Collects all required .apk files (base system + device-specific packages).
    2. Rootfs Assembly: Uses apk add --root (using a host-built apk-tools) within a fakeroot environment.
    3. Device Integration: Applies deviceinfo metadata to configure the kernel cmdline and bootloader (e.g., U-Boot, GRUB).
    4. Finalization: Squashes the result into the target format (squashfs, ext4, or initramfs) and handles partitioning (GPT/MBR) for raw disk images.

E. PostmarketOS-Inspired Device Abstraction

To support a wide range of hardware without reinventing the wheel, Zest adopts the postmarketOS (pmOS) deviceinfo format.

  • Declarative Devices: Device-specific metadata (kernel package, architecture, bootloader type) is stored in standardized deviceinfo files.
  • Image Generation: The image generation step uses this metadata to decide which kernel to include and how to partition the final image.
  • Bootloader Integration: Zest automatically handles bootloader configuration (e.g., extlinux.conf, u-boot scripts) based on the target device's requirements.

3. The Build Lifecycle

  1. Fetch: Upstream sources are fetched and verified using Zig's content-addressable cache.
  2. Configure: The package is configured within its private sysroot.
  3. Compile: The Zig wrapper orchestrates the build, ensuring the correct cross-compilation flags are used.
  4. Package: Files are staged into an APK-compliant structure and compressed.
  5. Assemble: A high-level image task selects the desired package set and produces the final firmware binary.

4. Technical Stack

  • Orchestrator: Zig 0.14.0+ Build System
  • Compiler: Zig (zig cc)
  • Standard Library: Musl libc
  • Core Utilities: Busybox
  • Package Manager: APK
  • Host Requirements: Zig Compiler Only. (All necessary host tools like fakeroot, apk-tools, and image generators are built from source as part of the Zest build graph).

5. Why Zest?

  • Developer Experience (DX): Write build logic in a modern, readable language (Zig) instead of obscure M4 macros or complex Makefiles.
  • Performance: Parallelized builds by default, leveraging Zig's efficient build graph.
  • Reliability: Per-package sysroots eliminate the "it works on my machine" syndrome in embedded Linux.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment