Build Guide

Most contributors only need to build individual services. Full OS image builds are needed when changing the kernel, Yocto recipes, or base system configuration.

Do you need a full build?
If you're changing a Go service or scootui-qt, you don't need Yocto. Build the binary, copy it to the scooter over SSH, and restart the service. OTA updates handle the rest for end users.

Building a Go Service

Both the MDB and DBC run ARMv7 processors. All Go services cross-compile to the same target.

Build for the scooter (ARMv7)

make build        # → bin/<service-name> (ARM binary)

Build for your machine (development)

make build-host   # → bin/<service-name> (native binary)

Stripped release binary

make dist         # Stripped ARM binary for distribution

Other targets

make test         # Run unit tests
make lint         # golangci-lint
make fmt          # gofmt
make deps         # go mod tidy + download

Manual cross-compilation

CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 \
  go build -ldflags "-w -s" -o bin/my-service ./cmd/my-service

All services use static linking (CGO_ENABLED=0) so no shared libraries are needed on the target.

Building scootui-qt

scootui-qt is a Qt 6/QML application. For development you can build and run it natively on Linux; cross-compilation for the i.MX6 DBC uses Docker.

# Run on desktop with built-in simulator (no hardware needed)
./run-desktop.sh

# Or manually:
cmake -B build -DDESKTOP_MODE=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j$(nproc)
SCOOTUI_REDIS_HOST=none ./build/bin/scootui

# Cross-compile for ARM (i.MX6)
./cross-build.sh Release

Desktop mode includes a simulator panel — set SCOOTUI_REDIS_HOST=none to bypass Redis and drive the UI from the simulator. The cross-build produces a deploy-armhf/ directory with the binary, Qt plugins, and a launcher script ready to deploy via scp.

Full OS Image (Yocto)

Full image builds use Docker to provide a reproducible Yocto build environment. The librescoot/librescoot meta-repo contains the build script.

Setup

git clone https://github.com/librescoot/librescoot
cd librescoot

Build a full image

./build.sh

This launches a Docker container, checks out all required Yocto layers (including meta-librescoot), and runs bitbake. Build output is placed in the deploy/ directory.

Build a single package

PACKAGE=alarm-service ./build.sh

Sstate cache

Yocto uses a shared state cache to avoid rebuilding unchanged packages. First builds are slow (hours); subsequent builds of individual packages are fast (minutes). Mount the sstate cache directory as a Docker volume to persist it across builds.

Two targets

Target	Hardware	Image name
MDB	Middle Driver Board (main controller)	`librescoot-mdb`
DBC	Dashboard Computer (imx6DL, display)	`librescoot-dbc`

Both are ARMv7 (Cortex-A series) with musl libc.

Deploying a built image

Images are packaged as Mender .mender artifacts and can be installed via OTA:

lsc ota install /path/to/image.mender

Or transferred directly to the scooter and applied with mender-update install.

Kernel & U-Boot

Kernel and U-Boot changes require a full Yocto build. The DBC uses a downstream linux-fslc kernel (NXP i.MX6 BSP). MDB kernel details are in the meta-librescoot recipes.

Kernel configuration fragments live in meta-librescoot/recipes-kernel/linux/. Add or modify .cfg fragments rather than editing the full defconfig where possible.

← Contributing Redis API →