Skip to content

Development Setup

Jump to bottom
Matthew Barker edited this page Aug 3, 2026 · 6 revisions

Development Setup

This page walks you through a working A3SQL development environment: build the extension, build the addons, and test in-game with file patching so SQF changes apply on the next mission restart instead of a full PBO rebuild. If you only want to use A3SQL inside your own mod, you don't need any of this. See the Module Guide.

Prerequisites

  • Rust stable, at or above the rust-version declared in extension/Cargo.toml
  • HEMTT
  • UV (recommended for Python tools)
  • Arma 3 (for in-game testing)
  • CBA_A3 (workshop or source)
  • Wine / Proton (Linux) — optional, for code signing

Quick Start

# 1. Clone
git clone https://github.com/lErrorl404l/a3sql.git
cd a3sql

# 2. Build the Rust DLL (Linux native)
cargo build --release --manifest-path extension/Cargo.toml

# 3. Build the addon PBOs
hemtt build

# 4. Setup file patching
uv run python3 tools/setup.py

# 5. Launch (builds + copies + starts Arma 3)
bash tools/launch.sh
# Or: hemtt launch

Python Tooling (UV)

All development tools use UV for dependency management:

# Run any tool
uv run python3 tools/sqf_validator.py addons/

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

File Patching

File patching allows SQF changes to take effect by simply restarting the mission (no PBO rebuild needed):

# Setup symlink (auto-detects Arma 3 via Steam VDF)
uv run python3 tools/setup.py

# Launch with file patching
hemtt launch

CBA function caching must be disabled for file patching to work. This is already configured in script_component.hpp:

#define DISABLE_COMPILE_CACHE

Code Signing

Generate a local signing key with HEMTT:

hemtt keys generate

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

Testing

Rust tests (CI — fastest feedback)

cargo test --manifest-path extension/Cargo.toml   # full test suite
cargo clippy --manifest-path extension/Cargo.toml --all-targets -- -D warnings
cargo fmt --check                                  # formatting

SQF validation (static analysis, no game needed)

uv run python3 tools/sqfvmChecker.py
uv run python3 tools/sqf_validator.py addons/
uv run python3 tools/config_style_checker.py

In-game smoke test

// Run from Arma 3 debug console (server only)
execVM "tests/a3sql_smoke_test.sqf";
// Check RPT log for "A3SQL Smoke Test" results

Project Structure

a3sql/
├── extension/           # Rust extension (cdylib + rlib)
│   └── src/
│       ├── ffi/         # C ABI (RVExtension, RVExtensionArgs, RVExtensionVersion)
│       ├── dispatch/    # Command routing (SQL + control commands)
│       ├── engine/      # In-memory database engine
│       ├── parser/      # SQL parser (sqlparser-rs dialect)
│       ├── server.rs    # TCP listener
│       └── bin/         # a3sql-server (standalone TCP)
├── addons/
│   ├── main/            # Core addon (CfgPatches, macros)
│   ├── database/        # SQL engine SQF API (CfgFunctions)
│   ├── admin/           # Server command execution + player tracking
│   ├── analytics/       # Kill/shoot analytics snapshots
│   ├── loadouts/        # Loadout templates
│   ├── persistence/     # Player state save/restore
│   ├── progression/     # Rank/score tracking
│   ├── patch_core/      # Dynamic patching engine
│   ├── patch_editor/    # In-game rule editor UI
│   └── patch_operators/ # Value transformer operators
├── include/             # CBA build-time includes
├── tools/               # Python dev tools (UV-managed)
├── .hemtt/              # HEMTT build config + hooks
├── .editorconfig        # Editor consistency (tab=SQF, space=Rust)
├── .gitattributes       # linguist-language=SQF
└── pyproject.toml        # UV configuration

Clone this wiki locally