james.maes
f751b2eb4e
- Move design docs to docs/ - Move packaging files to packaging/ - Create GitHub issues and milestones for tracking - Update workflow and README references
190 lines
4.4 KiB
Markdown
190 lines
4.4 KiB
Markdown
# Native Build Guide
|
|
|
|
This document explains how to build `qctl` as a native executable using GraalVM.
|
|
|
|
## Quick Start
|
|
|
|
### Option 1: Automated Build Script (Recommended)
|
|
```bash
|
|
./scripts/build-native.sh
|
|
```
|
|
|
|
### Option 2: Manual Maven Command
|
|
```bash
|
|
# Check environment first
|
|
mvn -Pnative-check validate
|
|
|
|
# Build native executable (target qctl-core and dependencies)
|
|
mvn -Pnative -DskipTests -pl qctl-shared,qctl-core -am package
|
|
```
|
|
|
|
### Option 3: Environment Check Only
|
|
```bash
|
|
./scripts/validate-graalvm.sh
|
|
# or
|
|
./scripts/check-native-build-env.sh
|
|
```
|
|
|
|
## Prerequisites
|
|
|
|
### 1. GraalVM Installation
|
|
|
|
Download and install GraalVM 21+ from:
|
|
- **Official**: https://www.graalvm.org/downloads/
|
|
- **Oracle GraalVM**: https://www.oracle.com/downloads/graalvm-downloads.html
|
|
- **SDKMAN**: `sdk install java 21.0.1-graal`
|
|
|
|
### 2. Native Image Tool
|
|
|
|
If not included with your GraalVM distribution:
|
|
```bash
|
|
gu install native-image
|
|
```
|
|
|
|
### 3. Environment Setup
|
|
|
|
Set one of the following:
|
|
```bash
|
|
# Option A: Set JAVA_HOME to GraalVM
|
|
export JAVA_HOME=/path/to/graalvm
|
|
|
|
# Option B: Set GRAALVM_HOME
|
|
export GRAALVM_HOME=/path/to/graalvm
|
|
export PATH=$GRAALVM_HOME/bin:$PATH
|
|
```
|
|
|
|
### 4. Platform-Specific Requirements
|
|
|
|
#### Linux
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo apt-get install build-essential zlib1g-dev
|
|
|
|
# For static builds (recommended)
|
|
sudo apt-get install musl-tools
|
|
|
|
# RHEL/CentOS
|
|
sudo yum groupinstall 'Development Tools'
|
|
sudo yum install zlib-devel musl-gcc
|
|
```
|
|
|
|
#### macOS
|
|
```bash
|
|
# Xcode command line tools (usually already installed)
|
|
xcode-select --install
|
|
```
|
|
|
|
#### Windows
|
|
- Install Visual Studio Build Tools or Visual Studio Community
|
|
- Ensure Windows SDK is available
|
|
|
|
## Build Configuration
|
|
|
|
The native build is configured with:
|
|
|
|
- **Static linking** (`--static --libc=musl`) for maximum portability on Linux
|
|
- **HTTP/HTTPS support** for API communication
|
|
- **Resource inclusion** for configuration files (`.properties`, `.xml`, `.json`, `.yaml`)
|
|
- **Optimized logging** initialization at build time
|
|
- **CLI-friendly** error reporting and stack traces
|
|
|
|
## Output
|
|
|
|
The native executable will be created at:
|
|
```
|
|
qctl-core/target/qctl
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **"native-image is not installed"**
|
|
- Install GraalVM native-image: `gu install native-image`
|
|
- Verify installation: `native-image --version`
|
|
|
|
2. **"JAVA_HOME is not a GraalVM distribution"**
|
|
- Set `JAVA_HOME` to point to GraalVM installation
|
|
- Or set `GRAALVM_HOME` environment variable
|
|
|
|
3. **Build fails with memory errors**
|
|
- Increase memory: `export MAVEN_OPTS="-Xmx4g"`
|
|
- Or add to build: `mvn -Pnative -DskipTests -Dgraalvm.native.memory=4g package`
|
|
|
|
4. **Missing build tools on Linux**
|
|
- Install development tools and zlib as shown above
|
|
- For static builds, ensure musl-gcc is available
|
|
|
|
5. **Slow build times**
|
|
- Native compilation can take 5-15 minutes depending on system
|
|
- Use `-DskipTests` to speed up builds during development
|
|
|
|
### Environment Validation
|
|
|
|
Run the validation script to check your setup:
|
|
```bash
|
|
./scripts/validate-graalvm.sh
|
|
```
|
|
|
|
This will check:
|
|
- ✅ Java version (21+)
|
|
- ✅ GraalVM installation
|
|
- ✅ native-image tool availability
|
|
- ✅ Build tools (Linux)
|
|
- ✅ System memory
|
|
- ✅ Maven installation
|
|
|
|
## Advanced Configuration
|
|
|
|
### Custom Build Arguments
|
|
|
|
Modify the native profile in `pom.xml` to add custom GraalVM arguments:
|
|
|
|
```xml
|
|
<buildArgs>
|
|
<buildArg>--your-custom-arg</buildArg>
|
|
</buildArgs>
|
|
```
|
|
|
|
### Profile Activation
|
|
|
|
The build uses Maven profiles:
|
|
- `native`: Builds the native executable
|
|
- `native-check`: Validates environment only
|
|
|
|
### Performance Tuning
|
|
|
|
For faster builds during development:
|
|
```bash
|
|
# Skip validation (if environment is known good)
|
|
mvn -Pnative -DskipTests -Dgraalvm.native.agent=false package
|
|
```
|
|
|
|
For smaller executables:
|
|
```bash
|
|
# Add optimization flags
|
|
mvn -Pnative -DskipTests -Dgraalvm.native.optimize=true package
|
|
```
|
|
|
|
## Integration with CI/CD
|
|
|
|
Example GitHub Actions workflow:
|
|
```yaml
|
|
- name: Setup GraalVM
|
|
uses: graalvm/setup-graalvm@v1
|
|
with:
|
|
version: '21.0.1'
|
|
java-version: '21'
|
|
components: 'native-image'
|
|
|
|
- name: Build Native Executable
|
|
run: ./scripts/build-native.sh
|
|
```
|
|
|
|
## Performance Notes
|
|
|
|
- **Startup time**: Native executables start ~10-50x faster than JVM
|
|
- **Memory usage**: Typically 2-5x lower memory footprint
|
|
- **Runtime performance**: May be slightly slower for long-running processes
|
|
- **Build time**: 5-15 minutes vs ~30 seconds for JVM builds
|