Skip to content

Building

Jump to bottom
Matthew Barker edited this page Jul 31, 2026 · 8 revisions

Building

A3SQL has two build steps: the Rust extension (native DLL/SO) and the Arma 3 addon (PBO files via HEMTT).

Prerequisites

  • Rust 1.80+ (stable)
  • HEMTT 1.20+ — Arma addon build tool
  • CBA_A3 — for addon compilation (HEMTT dev dependencies)
  • UV (recommended) — Python tooling runner
  • Wine or Proton (optional) — for code signing on Linux (see Code Signing below)

Quick Build

# 1. Build the Rust extension
cargo build --release --manifest-path extension/Cargo.toml

# 2. Copy to Arma 3 directory
cp extension/target/release/liba3sql.so "/path/to/Arma 3/@a3sql/a3sql_x64.so"
# or for Windows cross-compile:
cp extension/target/x86_64-pc-windows-gnu/release/a3sql.dll "/path/to/Arma 3/@a3sql/a3sql_x64.dll"

# 3. Build addon PBOs
hemtt build

# 4. Result in .hemttout/build/

Cross-compilation

The extension targets 4 architectures via rust-toolchain.toml:

# Linux x86_64 (native)
cargo build --release --target x86_64-unknown-linux-gnu --manifest-path extension/Cargo.toml

# Linux 32-bit
cargo build --release --target i686-unknown-linux-gnu --manifest-path extension/Cargo.toml

# Windows x86_64 (MinGW cross)
cargo build --release --target x86_64-pc-windows-gnu --manifest-path extension/Cargo.toml

# Windows 32-bit
cargo build --release --target i686-pc-windows-gnu --manifest-path extension/Cargo.toml

Testing

cargo test --manifest-path extension/Cargo.toml   # 524 tests
cargo clippy --manifest-path extension/Cargo.toml --all-targets -- -D warnings
cargo fmt --check                                  # formatting
hemtt check -p -e                                  # SQF + config validation

Developer Tooling

Python tools (UV)

All development Python scripts are in tools/. Run with UV:

# Environment report
uv run python3 tools/setup.py --report

# SQF validation
uv run python3 tools/sqfvmChecker.py
uv run python3 tools/sqf_validator.py addons/

# Config style check
uv run python3 tools/config_style_checker.py

Code Signing (HEMTT)

A3SQL signs addons with HEMTT. Generate a local key once:

hemtt keys generate

Keep a3sql.hemttprivatekey out of version control (already gitignored) and never commit private_key_hash. HEMTT signs automatically during hemtt release; signed zips go to releases/. Signing is configured in .hemtt/project.toml → [signing] authority = "a3sql". CI signs each release with a per-release ephemeral key.

Steam Library Discovery

tools/proton.py automatically finds Arma 3 via Steam VDF (libraryfolders.vdf), including Wine prefix and workshop paths. Used by tools/setup.py for file patching symlink setup.

CI/CD

GitHub Actions (.github/workflows/ci.yml) runs on push/PR to main:

  1. validate — SQF syntax validation + config style check + HEMTT check + BOM check
  2. test — cargo test + clippy + rustfmt on ubuntu-latest
  3. build-linux — cross-compile for x86_64 and i686 Linux
  4. build-windows — cross-compile for x86_64 and i686 Windows (MinGW)
  5. build-addon — downloads all artifacts, runs hemtt build, outputs PBOs
  6. workshop — publish to Steam Workshop (on release)

On a release publish, it creates a3sql-release.zip with the full addon.

Standalone Server

The a3sql-server binary is part of the extension workspace:

cargo run --manifest-path extension/Cargo.toml --bin a3sql-server -- --port 33307
cargo build --release --manifest-path extension/Cargo.toml --bin a3sql-server

Arma 3 Installation

Deploy the addon to your Arma 3 directory:

# Linux (native)
cp extension/target/release/a3sql_x64.so ~/.local/share/Steam/steamapps/common/Arma\ 3/@a3sql/

# Windows (cross-compiled via MinGW)
cp extension/target/x86_64-pc-windows-gnu/release/a3sql.dll "/path/to/Arma 3/@a3sql/a3sql_x64.dll"

The HEMTT-built PBOs go in the same @a3sql directory alongside the DLLs.

Clone this wiki locally