docs(docker-build): rewrite README with complete build matrix and technical troubleshooting
This commit is contained in:
@@ -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
|
Builds are executed entirely inside containers. Only the output directory is mounted back to the host (`build/...`).
|
||||||
- **Docker**: Installed and running ([installation guide](https://docs.docker.com/get-docker/))
|
|
||||||
- **Disk Space**: At least 15 GB free
|
|
||||||
|
|
||||||
## 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
|
```bash
|
||||||
cd docker-build
|
cd docker-build
|
||||||
./build-menu.sh
|
./build-menu.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
You will be prompted to select the target platforms:
|
Menu options:
|
||||||
- `1`: Linux x86_64
|
- `1`: Linux `x86_64`
|
||||||
- `2`: Linux aarch64
|
- `2`: Linux `aarch64` (ARM64)
|
||||||
- `3`: Linux ARMv7l
|
- `3`: Linux `armv7l` (ARM 32-bit)
|
||||||
- `4`: Windows x86_64
|
- `4`: Windows `x86_64`
|
||||||
- `5`: Build ALL targets
|
- `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.
|
### Linux x86_64
|
||||||
|
|
||||||
### Commands
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd docker-build # Navigate to the docker-build directory
|
cd docker-build
|
||||||
./build-linux-x86_64.sh # Run the build script
|
./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/`:
|
### Linux aarch64
|
||||||
- `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
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd docker-build # Navigate to the docker-build directory
|
cd docker-build
|
||||||
./build-linux-aarch64.sh # Run the cross-compilation build script
|
./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/`:
|
### Linux armv7l
|
||||||
- `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
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd docker-build # Navigate to the docker-build directory
|
cd docker-build
|
||||||
./build-linux-armv7l.sh # Run the ARMv7l cross-compilation build script
|
./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/`:
|
### Windows x86_64
|
||||||
- `palladiumd` - Main daemon
|
|
||||||
- `palladium-cli` - Command-line client
|
|
||||||
- `palladium-tx` - Transaction utility
|
|
||||||
- `palladium-wallet` - Wallet utility
|
|
||||||
- `palladium-qt` - GUI application
|
|
||||||
|
|
||||||
## Windows x86_64
|
Binaries:
|
||||||
|
|
||||||
Creates Windows executables through cross-compilation with MinGW-w64.
|
|
||||||
|
|
||||||
### Commands
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd docker-build # Navigate to the docker-build directory
|
cd docker-build
|
||||||
./build-windows.sh # Run the Windows cross-compilation build script
|
./build-windows.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
### Output
|
Binaries + installer:
|
||||||
|
|
||||||
Executables will be available in `../build/windows/`:
|
```bash
|
||||||
- `palladiumd.exe` - Main daemon
|
cd docker-build
|
||||||
- `palladium-cli.exe` - Command-line client
|
./build-windows.sh --installer
|
||||||
- `palladium-tx.exe` - Transaction utility
|
```
|
||||||
- `palladium-wallet.exe` - Wallet utility
|
|
||||||
- `palladium-qt.exe` - GUI application
|
|
||||||
|
|
||||||
### 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
|
```bash
|
||||||
cd docker-build
|
cd docker-build
|
||||||
chmod +x *.sh
|
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`
|
||||||
|
|||||||
Reference in New Issue
Block a user