Skip to content

Commit 0c2de88

Browse files
thanosthanos
committed
Add cross-platform build scripts and infrastructure
This commit adds comprehensive cross-platform build and testing infrastructure for rust-bottle, enabling automated builds across all supported platforms from a single macOS/ARM development machine. New Features: - Cross-platform build scripts for macOS/ARM, macOS/x86_64, Linux/x86_64, and Linux/ARM64 - Docker and Podman support for Linux builds with automatic runtime detection - Dockerfiles for Linux x86_64 and ARM64 builds using latest Rust - Prerequisites checking script to verify build environment setup - Quick build test script for fast compilation verification - Alternative build script using cross tool for efficient cross-compilation - Comprehensive build documentation in scripts/README_BUILD.md Infrastructure: - Added .cargo/config.toml for cross-compilation linker configuration - Updated .gitignore to allow .cargo/config.toml while ignoring other cargo files - Docker images use rust:latest to support Cargo.lock v4 format - All scripts are bash 3.2+ compatible for macOS compatibility Build Scripts: - build-all-platforms.sh: Orchestrates builds for all platforms - build-macos-arm.sh: Native macOS/ARM builds - build-macos-x86_64.sh: macOS/x86_64 builds using Rosetta 2 - build-linux-x86_64.sh: Linux/x86_64 builds using Docker/Podman - build-linux-arm64.sh: Linux/ARM64 builds using Docker/Podman - build-using-cross.sh: Alternative using cross tool - check-prerequisites.sh: Verify required tools and setup - quick-build-test.sh: Quick compilation test without full test suite Docker Support: - Dockerfile.linux-x86_64: Linux x86_64 build environment - Dockerfile.linux-arm64: Linux ARM64 build environment with cross-compilation - .dockerignore: Excludes unnecessary files from Docker builds - Automatic detection of Docker vs Podman (prefers Podman if available) Documentation: - scripts/README_BUILD.md: Complete guide for cross-platform builds - Includes troubleshooting, prerequisites, and usage examples - Documents Docker vs Podman differences and usage This infrastructure enables: - Automated testing across all target platforms - CI/CD integration for multi-platform builds - Easy verification of cross-compilation setup - Consistent build environments across development machines
1 parent 7716e96 commit 0c2de88

14 files changed

Lines changed: 1328 additions & 0 deletions

‎.cargo/config.toml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Cargo configuration for cross-compilation
2+
# This file helps configure cross-compilation targets
3+
4+
[target.x86_64-apple-darwin]
5+
# macOS x86_64 (Intel) - uses native toolchain or Rosetta 2
6+
7+
[target.aarch64-apple-darwin]
8+
# macOS ARM64 (Apple Silicon) - native
9+
10+
[target.x86_64-unknown-linux-gnu]
11+
# Linux x86_64 - for Docker builds
12+
linker = "x86_64-linux-gnu-gcc"
13+
14+
[target.aarch64-unknown-linux-gnu]
15+
# Linux ARM64 - for Docker builds with cross-compilation
16+
linker = "aarch64-linux-gnu-gcc"
17+
18+
# Build configuration
19+
[build]
20+
# Uncomment to set default target
21+
# default-target = "aarch64-apple-darwin"
22+

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@
33
**/*.rs.bk
44
Cargo.lock
55

6+
# Cargo configuration
7+
# Allow .cargo/config.toml (project settings) but ignore other files
8+
.cargo/*
9+
!.cargo/config.toml
10+
611
# Coverage reports
712
coverage/
813
*.profraw

‎scripts/.dockerignore‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Docker ignore file for rust-bottle builds
2+
target/
3+
.git/
4+
.gitignore
5+
*.md
6+
!README.md
7+
coverage/
8+
.vscode/
9+
.idea/
10+
*.swp
11+
*.swo
12+
*~
13+
.DS_Store
14+
Cargo.lock
15+

‎scripts/Dockerfile.linux-arm64‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Dockerfile for building rust-bottle on Linux/ARM64
2+
# This can use native ARM64 Docker or QEMU emulation
3+
# Using latest stable Rust to support Cargo.lock v4
4+
FROM rust:latest
5+
6+
# Install required dependencies
7+
RUN apt-get update && apt-get install -y \
8+
build-essential \
9+
pkg-config \
10+
libssl-dev \
11+
ca-certificates \
12+
gcc-aarch64-linux-gnu \
13+
libc6-dev-arm64-cross \
14+
&& rm -rf /var/lib/apt/lists/*
15+
16+
# Install cross-compilation target
17+
RUN rustup target add aarch64-unknown-linux-gnu
18+
19+
# Set up cross-compilation linker
20+
ENV CC_aarch64_unknown_linux_gnu=aarch64-linux-gnu-gcc
21+
ENV CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc
22+
23+
# Set working directory
24+
WORKDIR /workspace
25+
26+
# Pre-create target directory to avoid permission issues
27+
RUN mkdir -p /workspace/target
28+
29+
# Default command
30+
CMD ["bash"]
31+

‎scripts/Dockerfile.linux-x86_64‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Dockerfile for building rust-bottle on Linux/x86_64
2+
# Using latest stable Rust to support Cargo.lock v4
3+
FROM rust:latest
4+
5+
# Install required dependencies
6+
RUN apt-get update && apt-get install -y \
7+
build-essential \
8+
pkg-config \
9+
libssl-dev \
10+
ca-certificates \
11+
&& rm -rf /var/lib/apt/lists/*
12+
13+
# Install cross-compilation target (native for x86_64, but good to be explicit)
14+
RUN rustup target add x86_64-unknown-linux-gnu
15+
16+
# Set working directory
17+
WORKDIR /workspace
18+
19+
# Pre-create target directory to avoid permission issues
20+
RUN mkdir -p /workspace/target
21+
22+
# Default command
23+
CMD ["bash"]
24+

‎scripts/README_BUILD.md‎

Lines changed: 284 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,284 @@
1+
# Cross-Platform Build Scripts
2+
3+
This directory contains scripts for building and testing `rust-bottle` on multiple platforms from a macOS/ARM (Apple Silicon) machine.
4+
5+
## Supported Platforms
6+
7+
- **macOS/ARM** (Apple Silicon) - Native build
8+
- **macOS/x86_64** (Intel) - Using Rosetta 2
9+
- **Linux/x86_64** - Using Docker or Podman
10+
- **Linux/ARM64** - Using Docker or Podman with cross-compilation
11+
12+
## Prerequisites
13+
14+
### Check Prerequisites
15+
16+
Before running build scripts, check if all prerequisites are met:
17+
18+
```bash
19+
./scripts/check-prerequisites.sh
20+
```
21+
22+
This will verify:
23+
- Rust and Cargo installation
24+
- Platform information
25+
- Rosetta 2 availability (for macOS/x86_64)
26+
- Docker or Podman installation and status
27+
- Required Rust targets
28+
- Optional `cross` tool
29+
30+
### For All Builds
31+
- Rust toolchain installed (`rustup`)
32+
- Cargo installed
33+
34+
### For macOS/x86_64 Builds
35+
- Rosetta 2 installed (usually pre-installed on Apple Silicon Macs)
36+
- If not installed: `softwareupdate --install-rosetta`
37+
38+
### For Linux Builds
39+
- **Docker** or **Podman** installed and working
40+
- **Docker Desktop**: https://www.docker.com/products/docker-desktop
41+
- **Podman**: https://podman.io/getting-started/installation
42+
- Scripts automatically detect and use whichever is available (Podman is preferred if both are installed)
43+
- Ensure Docker daemon is running (if using Docker) before executing Linux build scripts
44+
- Podman doesn't require a daemon
45+
46+
## Quick Start
47+
48+
### Build All Platforms
49+
50+
Run the main script to build for all platforms:
51+
52+
```bash
53+
./scripts/build-all-platforms.sh
54+
```
55+
56+
This will:
57+
1. Build for macOS/ARM (native)
58+
2. Build for macOS/x86_64 (using Rosetta 2)
59+
3. Build for Linux/x86_64 (using Docker or Podman)
60+
4. Build for Linux/ARM64 (using Docker or Podman)
61+
62+
### Build Individual Platforms
63+
64+
You can also build for individual platforms:
65+
66+
```bash
67+
# macOS/ARM (native)
68+
./scripts/build-macos-arm.sh
69+
70+
# macOS/x86_64 (Rosetta 2)
71+
./scripts/build-macos-x86_64.sh
72+
73+
# Linux/x86_64 (Docker or Podman)
74+
./scripts/build-linux-x86_64.sh
75+
76+
# Linux/ARM64 (Docker or Podman)
77+
./scripts/build-linux-arm64.sh
78+
```
79+
80+
### Quick Build Test (Compilation Only)
81+
82+
For a quick test that only checks compilation (no tests):
83+
84+
```bash
85+
./scripts/quick-build-test.sh
86+
```
87+
88+
### Alternative: Using `cross` Tool
89+
90+
For more efficient cross-compilation, you can use the `cross` tool:
91+
92+
```bash
93+
# Install cross first
94+
cargo install cross --git https://github.com/cross-rs/cross
95+
96+
# Run cross builds
97+
./scripts/build-using-cross.sh
98+
```
99+
100+
**Note**: The `cross` tool is faster for compilation but may not support running tests for all targets. Use container-based scripts (Docker/Podman) for full test coverage.
101+
102+
## How It Works
103+
104+
### macOS/ARM (Native)
105+
- Uses the native Rust toolchain
106+
- No special setup required
107+
- Fastest build option
108+
109+
### macOS/x86_64 (Rosetta 2)
110+
- Uses `arch -x86_64` to run commands in x86_64 mode
111+
- Automatically installs the `x86_64-apple-darwin` target
112+
- All cargo commands run through Rosetta 2
113+
114+
### Linux/x86_64 (Docker/Podman)
115+
- Uses Docker or Podman with the official Rust image
116+
- Automatically detects and uses Podman if available, otherwise falls back to Docker
117+
- Builds in a Linux container environment
118+
- Uses native x86_64 container runtime (or emulation if needed)
119+
120+
### Linux/ARM64 (Docker/Podman)
121+
- Uses Docker or Podman with cross-compilation support
122+
- Automatically detects and uses Podman if available, otherwise falls back to Docker
123+
- Can use native ARM64 container runtime (if available) or QEMU emulation
124+
- Installs cross-compilation toolchain (`gcc-aarch64-linux-gnu`)
125+
126+
## Feature Testing
127+
128+
All scripts test multiple feature combinations:
129+
- Default (no features)
130+
- `ml-kem` only
131+
- `post-quantum` only
132+
- `ml-kem,post-quantum` (all features)
133+
134+
Each feature combination is built and tested.
135+
136+
## Container Images
137+
138+
The container images (Docker/Podman compatible) are built automatically when you run the Linux build scripts. They are based on:
139+
- `rust:latest` - Official Rust Docker image (latest stable version)
140+
- Includes build dependencies (build-essential, pkg-config, libssl-dev)
141+
- Pre-configured with cross-compilation targets
142+
- Supports Cargo.lock v4 format
143+
144+
### Container Image Names
145+
- `rust-bottle-linux-x86_64` - For Linux x86_64 builds
146+
- `rust-bottle-linux-arm64` - For Linux ARM64 builds
147+
148+
### Rebuilding Container Images
149+
150+
Container images are automatically rebuilt if the Dockerfile changes. To force a rebuild:
151+
152+
```bash
153+
# Using Docker
154+
docker build -f scripts/Dockerfile.linux-x86_64 -t rust-bottle-linux-x86_64 .
155+
docker build -f scripts/Dockerfile.linux-arm64 -t rust-bottle-linux-arm64 .
156+
157+
# Using Podman
158+
podman build -f scripts/Dockerfile.linux-x86_64 -t rust-bottle-linux-x86_64 .
159+
podman build -f scripts/Dockerfile.linux-arm64 -t rust-bottle-linux-arm64 .
160+
```
161+
162+
**Note**: The scripts automatically detect whether to use Docker or Podman and use the appropriate command.
163+
164+
## Troubleshooting
165+
166+
### Rosetta 2 Not Available
167+
If you get an error about Rosetta 2:
168+
```bash
169+
softwareupdate --install-rosetta
170+
```
171+
172+
### Container Runtime Not Working
173+
If container commands fail:
174+
175+
**For Docker:**
176+
1. Start Docker Desktop
177+
2. Wait for it to fully start
178+
3. Verify with: `docker info`
179+
180+
**For Podman:**
181+
1. Podman doesn't require a daemon, but verify it's working: `podman info`
182+
2. On macOS, you may need Podman Machine: `podman machine init && podman machine start`
183+
3. Verify with: `podman info`
184+
185+
### Cross-Compilation Issues
186+
If Linux ARM64 builds fail:
187+
1. Ensure your container runtime (Docker/Podman) supports multi-platform builds
188+
2. Check that QEMU is available (usually automatic with Docker Desktop or Podman)
189+
3. Try building the container image manually to see detailed errors
190+
4. For Podman, ensure `podman machine` is configured for multi-arch support
191+
192+
### Rust Target Not Installed
193+
The scripts automatically install required targets, but if you encounter issues:
194+
```bash
195+
# macOS targets
196+
rustup target add aarch64-apple-darwin
197+
rustup target add x86_64-apple-darwin
198+
199+
# Linux targets (for container builds)
200+
# These are installed inside containers automatically
201+
```
202+
203+
### Permission Denied
204+
If scripts are not executable:
205+
```bash
206+
chmod +x scripts/build-*.sh
207+
```
208+
209+
## Build Artifacts
210+
211+
Build artifacts are stored in:
212+
- `target/aarch64-apple-darwin/release/` - macOS/ARM builds
213+
- `target/x86_64-apple-darwin/release/` - macOS/x86_64 builds
214+
- `target/x86_64-unknown-linux-gnu/release/` - Linux/x86_64 builds (in containers)
215+
- `target/aarch64-unknown-linux-gnu/release/` - Linux/ARM64 builds (in containers)
216+
217+
## Performance Notes
218+
219+
- **macOS/ARM**: Fastest (native)
220+
- **macOS/x86_64**: Slower (Rosetta 2 translation overhead)
221+
- **Linux/x86_64**: Medium speed (container overhead, but native architecture)
222+
- **Linux/ARM64**: Slowest (container + cross-compilation or emulation)
223+
224+
## CI/CD Integration
225+
226+
These scripts can be integrated into CI/CD pipelines:
227+
- GitHub Actions
228+
- GitLab CI
229+
- CircleCI
230+
- etc.
231+
232+
Example GitHub Actions workflow:
233+
```yaml
234+
- name: Build all platforms
235+
run: ./scripts/build-all-platforms.sh
236+
```
237+
238+
## Advanced Usage
239+
240+
### Building Specific Features Only
241+
242+
You can modify the scripts to test only specific features by editing the `FEATURES` array in each script.
243+
244+
### Custom Container Images
245+
246+
You can customize the container images (Docker/Podman compatible) by editing the Dockerfiles:
247+
- `scripts/Dockerfile.linux-x86_64`
248+
- `scripts/Dockerfile.linux-arm64`
249+
250+
### Parallel Builds
251+
252+
The scripts run builds sequentially. For faster execution, you could modify them to run in parallel, but be aware of resource constraints (especially with containers).
253+
254+
## Configuration
255+
256+
Cross-compilation settings are configured in `.cargo/config.toml`. You can modify this file to adjust linker settings or add additional targets.
257+
258+
## Podman vs Docker
259+
260+
The scripts automatically detect and use **Podman** if available, otherwise fall back to **Docker**. Both are fully supported:
261+
262+
### Podman Advantages
263+
- No daemon required (rootless by default)
264+
- Better security model (rootless containers)
265+
- Docker-compatible commands
266+
- Works well on macOS with Podman Machine
267+
268+
### Docker Advantages
269+
- More widely used and documented
270+
- Better GUI support (Docker Desktop)
271+
- More mature ecosystem
272+
273+
### Which to Use?
274+
- **Use Podman** if you prefer rootless containers and don't need Docker Desktop
275+
- **Use Docker** if you want Docker Desktop's GUI and ecosystem
276+
- Scripts work with either - they auto-detect what's available
277+
278+
## See Also
279+
280+
- [Rust Cross-Compilation Guide](https://rust-lang.github.io/rustup/cross-compilation.html)
281+
- [Docker Multi-Platform Builds](https://docs.docker.com/build/building/multi-platform/)
282+
- [Podman Documentation](https://docs.podman.io/)
283+
- [Rosetta 2 Documentation](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment)
284+

0 commit comments

Comments
 (0)