davide/palladiumcore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(docker-build): rewrite README with complete build matrix and technical troubleshooting

Browse Source
This commit is contained in:
davide3011
2026-02-06 08:42:53 +01:00
parent 3bc7cff5ba
commit de0ef2ec7a
1 changed files with 163 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

236
docker-build/README.md
View File

@@ -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/<host>/bin` to `PATH`
- pass `--with-qt-bindir=$PWD/depends/<host>/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/<host>`
- 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`