From de0ef2ec7af5d89ac50d10d1c3ba5095a4622497 Mon Sep 17 00:00:00 2001 From: davide3011 Date: Fri, 6 Feb 2026 08:42:53 +0100 Subject: [PATCH] docs(docker-build): rewrite README with complete build matrix and technical troubleshooting --- docker-build/README.md | 236 ++++++++++++++++++++++++++++------------- 1 file changed, 163 insertions(+), 73 deletions(-) diff --git a/docker-build/README.md b/docker-build/README.md index 02cc55c..b6b9b5b 100644 --- a/docker-build/README.md +++ b/docker-build/README.md @@ -1,114 +1,204 @@ -# Docker Build System for Palladium Core +# Palladium Core Docker Build System -## System Requirements +This directory contains Docker-based build scripts for: +- Linux `x86_64` +- Linux `aarch64` +- Linux `armv7l` +- Windows `x86_64` (`.exe` binaries, optional NSIS installer) -- **Host System**: Ubuntu 20.04+ on x86_64 architecture -- **Docker**: Installed and running ([installation guide](https://docs.docker.com/get-docker/)) -- **Disk Space**: At least 15 GB free +Builds are executed entirely inside containers. Only the output directory is mounted back to the host (`build/...`). -## Unified Build Menu (Recommended) +## Prerequisites -The easiest way to build binaries for one or multiple platforms is using the interactive menu script. +- Docker installed and running +- Access to Docker daemon (`docker build` / `docker run`) +- Recommended free disk space: 15+ GB +- Linux host recommended (Ubuntu 20.04+) -### Usage +Platform note: +- Scripts use `--platform=linux/amd64`. +- On `amd64` hosts this runs natively. +- On non-`amd64` hosts, compatible emulation (`qemu`/`binfmt`) is required and builds are slower. + +## Quick Start (Interactive Menu) ```bash cd docker-build ./build-menu.sh ``` -You will be prompted to select the target platforms: -- `1`: Linux x86_64 -- `2`: Linux aarch64 -- `3`: Linux ARMv7l -- `4`: Windows x86_64 -- `5`: Build ALL targets +Menu options: +- `1`: Linux `x86_64` +- `2`: Linux `aarch64` (ARM64) +- `3`: Linux `armv7l` (ARM 32-bit) +- `4`: Windows `x86_64` +- `4a`: Windows `x86_64` (Installer) +- `5`: Build all targets (binaries + Windows installer) +- `6`: Build all installers +- `0`: Exit -You can also select multiple targets by separating them with spaces (e.g., `1 4`). +You can select multiple entries, for example `1 4a`. -## Linux x86_64 +## Build Targets -Creates native Linux 64-bit binaries using a Docker container based on Ubuntu 20.04. - -### Commands +### Linux x86_64 ```bash -cd docker-build # Navigate to the docker-build directory -./build-linux-x86_64.sh # Run the build script +cd docker-build +./build-linux-x86_64.sh ``` -### Output +Output: `build/linux-x86_64/` +- `palladiumd` +- `palladium-cli` +- `palladium-tx` +- `palladium-wallet` +- `palladium-qt` -Binaries will be available in `../build/linux-x86_64/`: -- `palladiumd` - Main daemon -- `palladium-cli` - Command-line client -- `palladium-tx` - Transaction utility -- `palladium-wallet` - Wallet utility -- `palladium-qt` - GUI application - -## Linux aarch64 (ARM64) - -Creates ARM64 binaries for devices like Raspberry Pi 4+ through cross-compilation. - -### Commands +### Linux aarch64 ```bash -cd docker-build # Navigate to the docker-build directory -./build-linux-aarch64.sh # Run the cross-compilation build script +cd docker-build +./build-linux-aarch64.sh ``` -### Output +Output: `build/linux-aarch64/` +- `palladiumd` +- `palladium-cli` +- `palladium-tx` +- `palladium-wallet` +- `palladium-qt` -Binaries will be available in `../build/linux-aarch64/`: -- `palladiumd` - Main daemon -- `palladium-cli` - Command-line client -- `palladium-tx` - Transaction utility -- `palladium-wallet` - Wallet utility -- `palladium-qt` - GUI application - -## Linux ARMv7l (ARM 32-bit) - -Creates ARM 32-bit binaries for older devices like Raspberry Pi 2/3 and Pi Zero. - -### Commands +### Linux armv7l ```bash -cd docker-build # Navigate to the docker-build directory -./build-linux-armv7l.sh # Run the ARMv7l cross-compilation build script +cd docker-build +./build-linux-armv7l.sh ``` -### Output +Output: `build/linux-armv7l/` +- `palladiumd` +- `palladium-cli` +- `palladium-tx` +- `palladium-wallet` +- `palladium-qt` -Binaries will be available in `../build/linux-armv7l/`: -- `palladiumd` - Main daemon -- `palladium-cli` - Command-line client -- `palladium-tx` - Transaction utility -- `palladium-wallet` - Wallet utility -- `palladium-qt` - GUI application +### Windows x86_64 -## Windows x86_64 - -Creates Windows executables through cross-compilation with MinGW-w64. - -### Commands +Binaries: ```bash -cd docker-build # Navigate to the docker-build directory -./build-windows.sh # Run the Windows cross-compilation build script +cd docker-build +./build-windows.sh ``` -### Output +Binaries + installer: -Executables will be available in `../build/windows/`: -- `palladiumd.exe` - Main daemon -- `palladium-cli.exe` - Command-line client -- `palladium-tx.exe` - Transaction utility -- `palladium-wallet.exe` - Wallet utility -- `palladium-qt.exe` - GUI application +```bash +cd docker-build +./build-windows.sh --installer +``` -### Troubleshooting +Output: `build/windows/` +- `palladiumd.exe` +- `palladium-cli.exe` +- `palladium-tx.exe` +- `palladium-wallet.exe` +- `palladium-qt.exe` +- Installer (if requested): `palladium-*-win64-setup.exe` + +## Technical Build Flow + +Each build script does the following: +1. Builds a Docker image from the current repository (`COPY . /src`). +2. Starts a container and runs the build in `/src`. +3. Performs an aggressive cleanup to avoid stale host artifacts. +4. Builds `depends` for the target host triple. +5. Runs `autogen.sh`, `configure`, `make -j$(nproc)`. +6. Copies final binaries into `/out` (host-mounted output directory). +7. Applies host UID/GID ownership to output files. + +Key details: +- Linux targets use host triples: + - `x86_64-pc-linux-gnu` + - `aarch64-linux-gnu` + - `arm-linux-gnueabihf` +- Windows target uses: + - `x86_64-w64-mingw32` +- Windows installer generation uses `make deploy` when `--installer` is passed. + +## Qt Toolchain Notes + +To avoid Qt tool mismatch issues, Linux scripts force Qt tools from `depends`: +- prepend `depends//bin` to `PATH` +- pass `--with-qt-bindir=$PWD/depends//bin` to `configure` + +Qt version used by `depends` is defined in `depends/packages/qt.mk`: +- currently `5.9.8` + +## Cleanup Strategy (Stale Artifact Protection) + +Scripts run cleanup inside the container before building: +- `make distclean` (if available) +- remove `depends/` +- remove `config.cache` +- Windows script also cleans `univalue` build/caches explicitly: + - `univalue/.libs` + - `univalue/lib/.libs` + - `univalue/config.cache` + - `univalue/config.status` + +This prevents ABI/toolchain mixing between host-compiled and container-compiled objects. + +## Troubleshooting + +### `QT_INIT_METAOBJECT` errors + +Symptom: +- compile errors in generated `.moc` files + +Typical cause: +- `moc` from system Qt mixed with headers/libs from `depends` Qt + +Mitigation already in scripts: +- force `depends` Qt tools (`PATH` + `--with-qt-bindir`) + +### Linker errors such as `__isoc23_strtol` or missing UniValue symbols + +Examples: +- `__isoc23_strtol` +- `UniValue::setBool(bool)` +- `UniValue::getValues() const` + +Typical cause: +- stale host-built objects reused in container link stage + +Mitigation already in scripts: +- pre-build cleanup, including dedicated `univalue` cleanup for Windows builds + +### Executable bit issues ```bash cd docker-build chmod +x *.sh ``` + +### Force a clean host-side output + +Usually not required, but useful after interrupted builds: + +```bash +rm -rf build/linux-* build/windows +``` + +## Main Files + +- `docker-build/build-menu.sh` +- `docker-build/build-linux-x86_64.sh` +- `docker-build/build-linux-aarch64.sh` +- `docker-build/build-linux-armv7l.sh` +- `docker-build/build-windows.sh` +- `docker-build/Dockerfile.linux-x86_64` +- `docker-build/Dockerfile.linux-aarch64` +- `docker-build/Dockerfile.linux-armv7l` +- `docker-build/Dockerfile.windows`