Skip to content

README.md

Latest commit

 

History

History
135 lines (102 loc) · 3.66 KB

README.md

File metadata and controls

135 lines (102 loc) · 3.66 KB

uConsole Image Builder Scripts

This directory contains scripts to build Debian and Ubuntu rootfs images for the uConsole CM4.

Scripts

build-image.sh

Main build script that creates a base rootfs using debootstrap.

Usage:

SUITE=trixie ARCH=arm64 ./scripts/build-image.sh [output-directory]

Environment Variables:

  • SUITE: Distribution suite (default: trixie)
    • trixie - Debian 13
    • bookworm - Debian 12
    • jammy - Ubuntu 22.04
  • ARCH: Target architecture (default: arm64)
  • First positional argument: Output directory (default: output)

What it does:

  1. Runs debootstrap to create a minimal rootfs
  2. Sets up QEMU for cross-architecture support
  3. Configures apt sources for the selected distribution
  4. Installs minimal base packages
  5. Leaves the rootfs ready for customization

setup-suite.sh

Unified customization script for all supported distributions (jammy, trixie, bookworm, popos).

Usage:

# Using environment variables
SUITE=trixie ./scripts/setup-suite.sh [output-directory]

# Using positional arguments
./scripts/setup-suite.sh [output-directory] [suite]

Environment Variables / Arguments:

  • SUITE / arg 2: Distribution to configure (jammy, trixie, bookworm, or popos)
  • First positional argument: Output directory (default: output)

What it does:

  1. Creates uconsole user with sudo privileges
  2. Installs distribution-specific packages
  3. Configures system for uConsole hardware
  4. Installs prebuilt kernel from ClockworkPi repository

Custom Kernel Builds: To build a custom kernel, use the Docker-based build script:

./scripts/build_clockworkpi_kernel.sh

Complete Build Examples

Building Debian trixie image:

# Build base rootfs
SUITE=trixie ./scripts/build-image.sh my-build

# Apply trixie customizations with prebuilt kernel
SUITE=trixie ./scripts/setup-suite.sh my-build

# Create tarball
cd my-build
tar -czf uconsole-trixie-arm64.tar.gz rootfs-trixie-arm64

Building Debian bookworm image:

# Build base rootfs
SUITE=bookworm ./scripts/build-image.sh my-build

# Apply bookworm customizations with prebuilt kernel
SUITE=bookworm ./scripts/setup-suite.sh my-build

# Create tarball
cd my-build
tar -czf uconsole-bookworm-arm64.tar.gz rootfs-bookworm-arm64

Building Ubuntu jammy image:

# Build base rootfs
SUITE=jammy ./scripts/build-image.sh my-build

# Apply jammy customizations with prebuilt kernel
SUITE=jammy ./scripts/setup-suite.sh my-build

# Create tarball
cd my-build
tar -czf uconsole-jammy-arm64.tar.gz rootfs-jammy-arm64

Building Pop!_OS image:

# Build base rootfs (uses jammy as base)
SUITE=jammy ./scripts/build-image.sh my-build

# Apply Pop!_OS customizations
SUITE=popos ./scripts/setup-suite.sh my-build

# Create tarball
cd my-build
tar -czf uconsole-popos-arm64.tar.gz rootfs-jammy-arm64

Building a custom kernel:

# Build kernel .deb packages using Docker (outputs to artifacts/kernel-debs/)
./scripts/build_clockworkpi_kernel.sh

# Then install manually on target device or integrate into image

Requirements

  • Debian or Ubuntu host system
  • Root privileges (sudo)
  • Packages: debootstrap, qemu-user-static, binfmt-support
  • For custom kernel builds: Docker (all build dependencies managed in container)

Notes

  • Default credentials: username uconsole, password uconsole
  • The user has passwordless sudo enabled
  • Rootfs images use prebuilt kernel packages from ClockworkPi repository
  • Custom kernel builds use Docker for reproducible, isolated builds: ./scripts/build_clockworkpi_kernel.sh
  • Docker kernel builds take 1-2 hours but provide consistent, reproducible results