Building from Source

Building from Source

GuppyScreen uses a plain Makefile. There are three practical targets: the SDL simulator (x86 desktop), the MIPS/mipsel build (the Ender-3 V3 KE hardware), and an aarch64 build (other boards; produced by CI). Dependencies are git submodules plus a vendored wpa_supplicant.

Prerequisites

• A C++17 toolchain (GCC/G++ 7.2+), make, and cmake
• Git (the project uses submodules)
• For the simulator: SDL2 development headers
• For the MIPS/aarch64 cross-builds: Docker (uses a prebuilt toolchain image — see below)

1. Clone with submodules

git clone --recurse-submodules https://github.com/coreflake1/NebulaOS-guppyscreen.git
cd NebulaOS-guppyscreen

Submodules: lvgl (LVGL v8), lv_drivers, libhv, spdlog. wpa_supplicant is vendored in-tree.

2. Apply submodule patches

(cd lv_drivers && git apply ../patches/0001-lv_driver_fb_ioctls.patch)
(cd spdlog     && git apply ../patches/0002-spdlog_fmt_initializer_list.patch)
(cd lvgl       && git apply ../patches/0003-lvgl-dpi-text-scale.patch)

Patch	Purpose
0001-lv_driver_fb_ioctls.patch	Framebuffer ioctls the KE display needs
0002-spdlog_fmt_initializer_list.patch	spdlog/fmt compatibility fix
0003-lvgl-dpi-text-scale.patch	DPI text-scaling adjustment

3. Build the bundled libraries

make wpaclient
make libhv.a
make libspdlog.a

4a. Simulator build (x86 desktop)

Install SDL2 headers, then build with the simulator flags (no CROSS_COMPILE):

# Fedora / Nobara:   sudo dnf install sdl2-compat-devel
# Debian / Ubuntu:   sudo apt install libsdl2-dev
# Arch:              sudo pacman -S sdl2

make -j"$(nproc)" \
  CFLAGS="-O3 -g0 -MD -MP -I./ -I./lvgl/ -I/usr/include/SDL2 -D_GNU_SOURCE=1 -Wno-incompatible-pointer-types" \
  LDFLAGS="-lm -Llibhv/lib -Lspdlog/build -l:libhv.a -latomic -lpthread -Lwpa_supplicant/wpa_supplicant/ -l:libwpa_client.a -lstdc++fs -l:libspdlog.a"

-Wno-incompatible-pointer-types is required on GCC 14+ due to an upstream strictness issue in lv_touch_calibration; it is unrelated to this fork's changes.

To build the small-screen layout in the simulator, add GUPPY_SMALL_SCREEN=1 to the make invocation.

Output: build/bin/guppyscreen. See Development and Simulator to run it.

4b. Cross-compile for the Ender-3 V3 KE (MIPS)

Quick note before you start: this section is for standalone development. Neither this repo's CI nor a normal NebulaOS build use the guppydev image below anymore — both moved to NebulaOS-firmware's unified build image (see its Build Environment doc and CI). guppydev still works fine for local, standalone iteration if you'd rather not pull the full unified image.

The MIPS toolchain ships in a container image. This repo provides its own toolchain image via docker/Dockerfile, published as ghcr.io/coreflake1/guppydev. Run the provided script inside that container; it rebuilds each dependency for MIPS and then builds GuppyScreen with GUPPY_SMALL_SCREEN=1:

docker run --rm -it -v "$PWD":/work -w /work ghcr.io/coreflake1/guppydev:latest \
  bash scripts/build-mips.sh

To build the toolchain image yourself instead of pulling it:

docker build -t ghcr.io/coreflake1/guppydev:latest docker/

• scripts/build-mips.sh defaults CROSS_COMPILE to mipsel-linux- (matches the toolchain on the image's PATH). CI uses the fuller triple mipsel-buildroot-linux-musl-.
• The script backs up any existing native dependency archives, rebuilds libhv, spdlog, and libwpa_client for MIPS, then restores the native archives on exit.
• Output: build/bin/guppyscreen, verified as ELF 32-bit LSB executable, MIPS, MIPS32 version 1 (SYSV), statically linked (~6.5 MB, no NEEDED entries).

The toolchain image

Docker is used only to provide the cross-compilation toolchain (the app itself is built by make, not in a container). The image is defined by docker/Dockerfile:

• Base: Ubuntu 22.04 + build-essential, cmake, git.
• MIPS: Bootlin mips32el--musl--stable-2024.02-1 (gcc 12.3.0) — provides both the mipsel-buildroot-linux-musl- and mipsel-linux- prefixes.
• aarch64: Arm GNU gcc-arm-10.2-2020.11 (aarch64-none-linux-gnu-, gcc 10.2.1).
• Both toolchains are downloaded from their official sources and verified by SHA256 at build time.

It is published to ghcr.io/coreflake1/guppydev (:latest and the pinned :2024.02). This is a from-source replacement for the upstream ballaswag/guppydev image, which it reproduces faithfully (same base, toolchains, paths, and PATH ordering).

Build internals (reference)

• make build runs the full sequence: clean + rebuild wpaclient, libhv.a, libspdlog.a, then the app.
• make clean removes build/.
• For native (non-cross) builds the Makefile auto-adds -DSIMULATOR and links -lSDL2. Defining CROSS_COMPILE switches to a static cross build (-static).
• The GUPPY_SMALL_SCREEN define selects the material_46 asset set and the small-screen layout paths.

See Releases and Deployment for packaging the result into a release tarball.