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

docs(docker-build): simplify and restructure docker build documentation

Browse Source 
- Condensed lengthy documentation into more concise sections
- Removed redundant troubleshooting and implementation details
- Organized content by architecture with clear command/output sections
- Maintained all essential information while improving readability
This commit is contained in:
Davide Grilli
2025-11-01 19:12:03 +01:00
parent dbaa10a848
commit 6ccf7ead4b
1 changed files with 56 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

302
docker-build/README.md
View File

@@ -1,281 +1,91 @@
# Docker Build System for Palladium Core
Docker-based build system for creating Palladium Core binaries using Ubuntu 20.04+ containers on x86_64 architecture.
## System Requirements
## Build Environment
- **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
All builds use:
- **Base OS**: Ubuntu 20.04 or newer
- **Container Platform**: Docker
- **Host Architecture**: x86_64 (AMD64)
- **Build Method**: Cross-compilation for target platforms
## Linux x86_64
## Supported Target Architectures
Creates native Linux 64-bit binaries using a Docker container based on Ubuntu 20.04.
- **Linux x86_64**: Native Linux 64-bit binaries
- **Linux aarch64**: ARM64 binaries for Raspberry Pi 4+ and modern ARM devices
- **Linux ARMv7l**: 32-bit ARM binaries for Raspberry Pi 2/3, Pi Zero, and older ARM devices
- **Windows x86_64**: Windows executables via MinGW-w64 cross-compilation
## Linux x86_64 Build
### Overview
This build creates native Linux x86_64 binaries using a Docker container based on Ubuntu 20.04. The build process:
1. **Builds a Docker image** (`palladium-builder:linux-x86_64-ubuntu20.04`) containing all build dependencies
2. **Copies the entire repository** into the container during image build
3. **Runs the build process** entirely inside the container using the `depends` system
4. **Outputs binaries** to a mounted volume for host access
### Quick Start
### Commands
```bash
cd docker-build
chmod +x build-linux-x86_64.sh
./build-linux-x86_64.sh
cd docker-build # Navigate to the docker-build directory
chmod +x build-linux-x86_64.sh # Make the build script executable
./build-linux-x86_64.sh # Run the build script
```
Binaries will be available in `../build/linux-x86_64/` directory.
### Output
### Prerequisites
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
- Docker installed and running ([installation guide](https://docs.docker.com/get-docker/))
- Sufficient disk space for the build process (at least 10 GB free)
- Internet connection for downloading dependencies
## Linux aarch64 (ARM64)
### Produced Binaries
Creates ARM64 binaries for devices like Raspberry Pi 4+ through cross-compilation.
The following binaries are built and copied to the output directory:
- `palladiumd`: Main daemon
- `palladium-cli`: Command-line client
- `palladium-tx`: Transaction utility
- `palladium-wallet`: Wallet utility
- `palladium-qt`: GUI application (if Qt dependencies are available)
### Output Directory
Binaries are placed in: `../build/linux-x86_64/` (relative to the docker-build directory)
### Troubleshooting
**Permission errors:** The build script automatically handles file permissions using host UID/GID
**Build failed:** Run interactive container for debugging:
```bash
docker run --rm -it -v "$(pwd)/../build/linux-x86_64":/out palladium-builder:linux-x86_64-ubuntu20.04 bash
```
**Docker build issues:** Ensure Docker has sufficient resources and the daemon is running
**Missing dependencies:** The Dockerfile installs all required build dependencies automatically
## Linux aarch64 Build
### Overview
This build creates Linux aarch64 (ARM64) binaries specifically designed for single board computers like the popular Raspberry Pi and other ARM-based devices. The build process uses cross-compilation in a Docker container:
1. **Builds a Docker image** (`palladium-builder:linux-aarch64-ubuntu20.04`) containing ARM64 cross-compilation toolchain
2. **Copies the entire repository** into the container during image build
3. **Cross-compiles for ARM64** using the `depends` system with `aarch64-linux-gnu` target
4. **Outputs binaries** to a mounted volume for host access
### Quick Start
### Commands
```bash
cd docker-build
chmod +x build-linux-aarch64.sh
./build-linux-aarch64.sh
cd docker-build # Navigate to the docker-build directory
chmod +x build-linux-aarch64.sh # Make the build script executable
./build-linux-aarch64.sh # Run the cross-compilation build script
```
ARM64 binaries will be available in `../build/linux-aarch64/` directory.
### Output
### Prerequisites
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
- Docker installed and running ([installation guide](https://docs.docker.com/get-docker/))
- Sufficient disk space for the build process (at least 12 GB free)
- Internet connection for downloading dependencies and ARM64 cross-compilation toolchain
## Linux ARMv7l (ARM 32-bit)
### Target Devices
Creates ARM 32-bit binaries for older devices like Raspberry Pi 2/3 and Pi Zero.
This build is optimized for:
- **Raspberry Pi 4** and newer models
- **Raspberry Pi 3** (64-bit mode)
- Other ARM64-based single board computers
- ARM64 Linux servers and workstations
### Produced Binaries
The following ARM64 binaries are built and copied to the output directory:
- `palladiumd`: Main daemon
- `palladium-cli`: Command-line client
- `palladium-tx`: Transaction utility
- `palladium-wallet`: Wallet utility
- `palladium-qt`: GUI application (if Qt dependencies are available)
### Output Directory
Binaries are placed in: `../build/linux-aarch64/` (relative to the docker-build directory)
### Cross-Compilation Details
- **Target Triple**: `aarch64-linux-gnu`
- **Toolchain**: GCC ARM64 cross-compiler
- **Dependencies**: Built using the `depends` system for ARM64 target
- **Configuration**: Uses `CONFIG_SITE` for proper cross-compilation setup
### Troubleshooting
**Permission errors:** The build script automatically handles file permissions using host UID/GID
**Build failed:** Run interactive container for debugging:
```bash
docker run --rm -it -v "$(pwd)/../build/linux-aarch64":/out palladium-builder:linux-aarch64-ubuntu20.04 bash
```
**Cross-compilation issues:** Ensure the ARM64 cross-compilation toolchain is properly installed in the container
**Missing binaries:** Check that the configure script detected the ARM64 target correctly
**Docker build issues:** Ensure Docker has sufficient resources and the daemon is running
## Linux ARMv7l Build
### Overview
This build creates Linux ARMv7l (32-bit ARM) binaries specifically designed for older ARM-based devices and single board computers. The build process uses cross-compilation in a Docker container:
1. **Builds a Docker image** (`palladium-builder:linux-armv7l-ubuntu20.04`) containing ARMv7l cross-compilation toolchain
2. **Copies the entire repository** into the container during image build
3. **Cross-compiles for ARMv7l** using the `depends` system with `arm-linux-gnueabihf` target
4. **Outputs binaries** to a mounted volume for host access
### Quick Start
### Commands
```bash
cd docker-build
chmod +x build-linux-armv7l.sh
./build-linux-armv7l.sh
cd docker-build # Navigate to the docker-build directory
chmod +x build-linux-armv7l.sh # Make the build script executable
./build-linux-armv7l.sh # Run the ARMv7l cross-compilation build script
```
ARMv7l binaries will be available in `../build/armv7l/` directory.
### Output
### Prerequisites
Binaries will be available in `../build/armv7l/`:
- `palladiumd` - Main daemon
- `palladium-cli` - Command-line client
- `palladium-tx` - Transaction utility
- `palladium-wallet` - Wallet utility
- `palladium-qt` - GUI application
- Docker installed and running ([installation guide](https://docs.docker.com/get-docker/))
- Sufficient disk space for the build process (at least 12 GB free)
- Internet connection for downloading dependencies and ARMv7l cross-compilation toolchain
## Windows x86_64
### Target Devices
Creates Windows executables through cross-compilation with MinGW-w64.
This build is optimized for:
- **Raspberry Pi 2** and **Raspberry Pi 3** (32-bit mode)
- **Raspberry Pi Zero** and **Zero W**
- Older ARM-based single board computers (BeagleBone, etc.)
- ARMv7l Linux embedded devices
- 32-bit ARM servers and workstations
### Produced Binaries
The following ARMv7l binaries are built and copied to the output directory:
- `palladiumd`: Main daemon
- `palladium-cli`: Command-line client
- `palladium-tx`: Transaction utility
- `palladium-wallet`: Wallet utility
- `palladium-qt`: GUI application (if Qt dependencies are available)
### Output Directory
Binaries are placed in: `../build/armv7l/` (relative to the docker-build directory)
### Cross-Compilation Details
- **Target Triple**: `arm-linux-gnueabihf`
- **Toolchain**: GCC ARM cross-compiler with hard-float ABI
- **Dependencies**: Built using the `depends` system for ARMv7l target
- **Configuration**: Uses `CONFIG_SITE` for proper cross-compilation setup
- **ABI**: Hard-float (gnueabihf) for better performance on modern ARM devices
### Troubleshooting
**Permission errors:** The build script automatically handles file permissions using host UID/GID
**Build failed:** Run interactive container for debugging:
```bash
docker run --rm -it -v "$(pwd)/../build/armv7l":/out palladium-builder:linux-armv7l-ubuntu20.04 bash
```
**Cross-compilation issues:** Ensure the ARM cross-compilation toolchain is properly installed in the container
**Missing binaries:** Check that the configure script detected the ARMv7l target correctly
**Docker build issues:** Ensure Docker has sufficient resources and the daemon is running
**Performance considerations:** ARMv7l builds may take longer to execute on target devices compared to ARM64 builds
## Windows x86_64 Build
### Overview
This build creates Windows x86_64 executables using cross-compilation in a Docker container based on Ubuntu 20.04. The build process:
1. **Builds a Docker image** (`palladium-builder:windows-ubuntu20.04`) containing MinGW-w64 cross-compilation toolchain
2. **Copies the entire repository** into the container during image build
3. **Cross-compiles for Windows** using the `depends` system with `x86_64-w64-mingw32` target
4. **Outputs .exe files** to a mounted volume for host access
### Quick Start
### Commands
```bash
cd docker-build
chmod +x build-windows.sh
./build-windows.sh
cd docker-build # Navigate to the docker-build directory
chmod +x build-windows.sh # Make the build script executable
./build-windows.sh # Run the Windows cross-compilation build script
```
Windows executables will be available in `../build/windows/` directory.
### Output
### Prerequisites
- Docker installed and running ([installation guide](https://docs.docker.com/get-docker/))
- Sufficient disk space for the build process (at least 12 GB free)
- Internet connection for downloading dependencies and MinGW-w64 toolchain
### Produced Executables
The following Windows executables are built and copied to the output directory:
- `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 (if Qt dependencies are available)
### Output Directory
Executables are placed in: `../build/windows/` (relative to the docker-build directory)
### Cross-Compilation Details
- **Target Triple**: `x86_64-w64-mingw32`
- **Toolchain**: MinGW-w64 cross-compiler
- **Dependencies**: Built using the `depends` system for Windows target
- **Configuration**: Uses `CONFIG_SITE` for proper cross-compilation setup
### Troubleshooting
**Permission errors:** The build script automatically handles file permissions using host UID/GID
**Build failed:** Run interactive container for debugging:
```bash
docker run --rm -it -v "$(pwd)/../build/windows":/out palladium-builder:windows-ubuntu20.04 bash
```
**Cross-compilation issues:** Ensure the MinGW-w64 toolchain is properly installed in the container
**Missing .exe files:** Check that the configure script detected the Windows target correctly
**Docker build issues:** Ensure Docker has sufficient resources and the daemon is running
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