Skip to main content
Version: 2.0 (Legacy)

Building an Image

How to build custom OpenHD system images from source.

Overview​

Building custom images allows you to:

  • Custom Hardware: Support new hardware platforms
  • Feature Modifications: Add or remove specific features
  • Optimization: Optimize for specific use cases
  • Development: Create development and testing images

Build Environment Setup​

System Requirements​

  • Linux Distribution: Ubuntu 20.04 LTS or newer
  • Disk Space: Minimum 50GB free space
  • RAM: 8GB RAM recommended
  • CPU: Multi-core processor for faster builds
  • Network: Stable internet connection

Dependencies Installation​

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install build dependencies
sudo apt install -y \
    git \
    build-essential \
    cmake \
    ninja-build \
    pkg-config \
    libssl-dev \
    libusb-1.0-0-dev \
    libpcap-dev \
    libsodium-dev \
    python3-pip \
    python3-setuptools \
    curl \
    wget \
    unzip

# Install cross-compilation tools
sudo apt install -y \
    gcc-arm-linux-gnueabihf \
    g++-arm-linux-gnueabihf \
    gcc-aarch64-linux-gnu \
    g++-aarch64-linux-gnu

Docker Setup (Alternative)​

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Pull build container
docker pull openhd/builder:latest

Source Code Setup​

Repository Cloning​

# Clone main repositories
git clone https://github.com/OpenHD/OpenHD-ImageBuilder.git
cd OpenHD-ImageBuilder

# Initialize submodules
git submodule update --init --recursive

# Clone additional repositories
git clone https://github.com/OpenHD/OpenHD.git
git clone https://github.com/OpenHD/QOpenHD.git
git clone https://github.com/OpenHD/wfb-ng.git

Build Configuration​

# Configure build for target platform
cd OpenHD-ImageBuilder
cp config/rpi4.conf config/custom.conf

# Edit configuration
nano config/custom.conf

Platform-Specific Builds​

Raspberry Pi 4/5​

# Build for Raspberry Pi 4
./build.sh --platform=rpi4 --version=custom

# Build for Raspberry Pi 5
./build.sh --platform=rpi5 --version=custom

# Build for Pi Zero 2W
./build.sh --platform=rpi-zero2w --version=custom

Radxa Platforms​

# Build for Radxa Zero 3W
./build.sh --platform=radxa-zero3w --version=custom

# Build for Rock 5A
./build.sh --platform=rock5a --version=custom

# Build for Rock 5B
./build.sh --platform=rock5b --version=custom

Generic ARM64​

# Generic ARM64 build
./build.sh --platform=generic-arm64 --version=custom

# Custom kernel configuration
./build.sh --platform=custom --kernel-config=custom.config

Build Process​

Full Image Build​

# Start complete build process
./build.sh --platform=rpi4 --clean --verbose

# Monitor build progress
tail -f build.log

# Build with specific features
./build.sh --platform=rpi4 --enable-feature=thermal-camera

Component-Specific Builds​

# Build only OpenHD core
./build-component.sh openhd

# Build only QOpenHD
./build-component.sh qopenhd

# Build WFB-ng
./build-component.sh wfb-ng

# Build kernel modules
./build-component.sh kernel-modules

Cross-Compilation​

# Set cross-compilation environment
export CC=arm-linux-gnueabihf-gcc
export CXX=arm-linux-gnueabihf-g++
export AR=arm-linux-gnueabihf-ar
export STRIP=arm-linux-gnueabihf-strip

# Build with cross-compilation
mkdir build-arm && cd build-arm
cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-linux-gnueabihf.cmake
make -j$(nproc)

Customization Options​

Feature Configuration​

# Edit feature configuration
nano config/features.conf

# Available features:
ENABLE_THERMAL_CAMERA=yes
ENABLE_DUAL_CAMERA=yes
ENABLE_LTE_SUPPORT=yes
ENABLE_AUDIO_SUPPORT=no
ENABLE_RECORDING=yes
ENABLE_STREAMING=yes

Package Selection​

# Customize package list
nano config/packages.list

# Core packages (required):
openhd-core
wfb-ng
libcamera
gstreamer1.0-plugins

# Optional packages:
thermal-camera-support
lte-modem-drivers
additional-codecs
development-tools

Kernel Configuration​

# Custom kernel config
cp kernel/config-rpi4 kernel/config-custom

# Edit kernel configuration
nano kernel/config-custom

# Build with custom kernel
./build.sh --platform=rpi4 --kernel-config=config-custom

Advanced Build Options​

Multi-Stage Build​

# Stage 1: Base system
./build.sh --stage=base --platform=rpi4

# Stage 2: OpenHD installation
./build.sh --stage=openhd --platform=rpi4

# Stage 3: Optimization and cleanup
./build.sh --stage=optimize --platform=rpi4

# Complete build
./build.sh --stage=all --platform=rpi4

Incremental Builds​

# Build only changed components
./build.sh --incremental --platform=rpi4

# Force rebuild of specific component
./build.sh --rebuild=openhd --platform=rpi4

# Clean specific component
./build.sh --clean-component=qopenhd --platform=rpi4

Debug Builds​

# Build with debug symbols
./build.sh --debug --platform=rpi4

# Build with additional logging
./build.sh --verbose --log-level=debug --platform=rpi4

# Build with development tools
./build.sh --development --platform=rpi4

Build Optimization​

Parallel Builds​

# Use all CPU cores
export MAKEFLAGS="-j$(nproc)"

# Limit parallel jobs
export MAKEFLAGS="-j4"

# Ninja build system
./build.sh --generator=ninja --platform=rpi4

Cache Configuration​

# Enable build cache
export CCACHE_DIR=/home/builder/.ccache
export PATH="/usr/lib/ccache:$PATH"

# Configure cache size
ccache -M 20G

# Show cache statistics
ccache -s

Resource Optimization​

# Optimize for build speed
./build.sh --optimize=speed --platform=rpi4

# Optimize for image size
./build.sh --optimize=size --platform=rpi4

# Balance optimization
./build.sh --optimize=balanced --platform=rpi4

Testing Built Images​

QEMU Emulation​

# Install QEMU
sudo apt install qemu-system-arm qemu-user-static

# Emulate ARM image
qemu-system-arm \
  -M versatilepb \
  -cpu arm1176 \
  -m 512 \
  -kernel kernel.img \
  -dtb bcm2708-rpi-b.dtb \
  -sd openhd-custom.img \
  -append "root=/dev/mmcblk0p2 rw"

Hardware Testing​

# Flash image to SD card
sudo dd if=openhd-custom.img of=/dev/sdX bs=4M status=progress

# Verify image integrity
sudo dd if=/dev/sdX bs=4M count=1000 | md5sum

Automated Testing​

# Run test suite
./test/run-tests.sh --image=openhd-custom.img

# Hardware-in-the-loop testing
./test/hil-test.sh --platform=rpi4 --image=openhd-custom.img

Continuous Integration​

GitHub Actions​

# .github/workflows/build.yml
name: Build OpenHD Images

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        platform: [rpi4, rpi5, radxa-zero3w]
    
    steps:
    - uses: actions/checkout@v3
    - name: Setup build environment
      run: ./scripts/setup-ci.sh
    - name: Build image
      run: ./build.sh --platform=${{ matrix.platform }}
    - name: Upload artifacts
      uses: actions/upload-artifact@v3
      with:
        name: openhd-${{ matrix.platform }}.img
        path: images/openhd-${{ matrix.platform }}.img

Local CI​

# Set up local CI
./scripts/setup-local-ci.sh

# Run CI pipeline locally
./scripts/run-ci-locally.sh --platform=all

Troubleshooting​

Common Build Issues​

# Out of disk space
df -h
sudo apt clean
docker system prune -a

# Permission issues
sudo chown -R $USER:$USER build/
chmod +x build.sh

# Missing dependencies
./scripts/check-dependencies.sh
sudo apt install -f

Debug Failed Builds​

# Check build logs
less build.log
grep -i error build.log

# Verbose build output
./build.sh --verbose --debug --platform=rpi4

# Interactive debugging
./build.sh --interactive --platform=rpi4

Memory Issues​

# Monitor memory usage
watch free -h

# Increase swap space
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Distribution​

Image Compression​

# Compress final image
gzip -9 openhd-custom.img

# Create torrent file
mktorrent -a udp://tracker.openhd.app:8080 openhd-custom.img.gz

Checksums and Signatures​

# Generate checksums
sha256sum openhd-custom.img.gz > openhd-custom.img.gz.sha256

# Sign with GPG
gpg --armor --detach-sign openhd-custom.img.gz
Build Time

Full image builds can take 2-6 hours depending on hardware. Plan accordingly and use incremental builds when possible.

Storage Requirements

Building images requires significant disk space. Ensure you have at least 50GB free space before starting.

Love OpenHD?