---
since: 1.0.0
---

# Binary Distribution

Comprehensive operational reference for compiling, packaging, and releasing astwire as a native standalone binary across four platforms, via GitLab CI/CD and Cloudflare R2.

## Distribution Architecture

```mermaid
flowchart TD

    REPO["📦 Source Repository<br/><small>GitLab: clizero/astwire (private)</small>"]

    CI["⚙️ GitLab CI/CD<br/><small>test → secret-detection → build → release</small>"]

    NUITKA["🔨 Nuitka Compilation<br/><small>--standalone --onefile</small>"]

    BUILDS["🖥️ Platform Binaries<br/><small>darwin-arm64 · linux-amd64<br/>linux-arm64 · windows-amd64</small>"]

    REGISTRY["📥 GitLab Generic Package Registry<br/><small>versioned + latest per asset</small>"]

    R2["☁️ Cloudflare R2<br/><small>/astwire/installers/</small>"]

    NGINX["🌐 install.djangoplay.org<br/><small>302 redirect to R2</small>"]

    USER["👤 End User<br/><small>curl / irm</small>"]

    REPO --> CI
    CI --> NUITKA
    NUITKA --> BUILDS
    BUILDS --> REGISTRY
    BUILDS --> R2
    R2 --> NGINX
    NGINX --> USER
    REGISTRY -.->|"manual REST upload<br/>(macOS binaries)"| REGISTRY

    classDef source fill:#e6f1fb,stroke:#2474b5,stroke-width:2px,color:#174d7a
    classDef build fill:#fff2d9,stroke:#d89b18,stroke-width:2px,color:#76520b
    classDef storage fill:#eeeaff,stroke:#7655c7,stroke-width:2px,color:#4a3485
    classDef edge fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b

    class REPO source
    class CI,NUITKA,BUILDS build
    class REGISTRY,R2 storage
    class NGINX,USER edge
```

## Overview

* **CI/CD Pipeline**: Validates tests, runs a secret-detection audit, compiles the Linux x86_64 ELF binary and Windows PE executable on release tags, and pushes assets to the GitLab Generic Package Registry.
* **Public Edge Distribution**: Standalone binaries hosted on Cloudflare R2 under `/astwire/installers/`.

### Complete Asset Coverage on R2

| Binary File | Target OS / Environment | Target Architecture |
| :--- | :--- | :--- |
| `astwire-darwin-arm64` | macOS (Apple Silicon: M1, M2, M3, M4) | ARM 64-bit (`arm64`) |
| `astwire-linux-amd64` | Linux (Ubuntu, Debian, RedHat, standard cloud VMs) | Intel/AMD 64-bit (`x86_64`) |
| `astwire-linux-arm64` | Linux (AWS Graviton, Raspberry Pi, Apple Silicon Docker) | ARM 64-bit (`aarch64`/`arm64`) |
| `astwire-windows-amd64.exe` | Windows 10, 11, Server | 64-bit (`x86_64`) |

---

### Cross-Platform Binary Builds

echo "==> macOS (Darwin ARM64)..."
./installers//v1.0.0/astwire-darwin-arm64 --version
./installers//v1.0.0/astwire-darwin-arm64 --help

echo "==> Linux AMD64..."
docker run --rm --platform linux/amd64 -v "$PWD/installers/v1.0.0":/test-bin debian:bookworm-slim bash -c "
  /test-bin/astwire-linux-amd64 --version
  /test-bin/astwire-linux-amd64 --help
"

echo "==> Linux ARM64..."
docker run --rm --platform linux/arm64 -v "$PWD/installers/v1.0.0":/test-bin debian:bookworm-slim bash -c "
  /test-bin/astwire-linux-arm64 --version
  /test-bin/astwire-linux-arm64 --help
"

echo "==> Windows AMD64 via Wine..."
docker run --rm --platform linux/amd64 -v "$PWD/installers/v1.0.0":/test-bin tobix/pywine:3.11 bash -c "
  wine /test-bin/astwire-windows-amd64.exe --version
  wine /test-bin/astwire-windows-amd64.exe --help
"

The Windows build uses **PyInstaller** inside Wine rather than Nuitka — cross-compiling a native Windows PE with Nuitka from a Linux container is not supported, so this path packages via Wine's Windows Python instead.

### Verify Artifact Architecture Headers

```bash
file installers/<version>/*
```

Expected output:

* `installers/astwire-darwin-arm64`: `Mach-O 64-bit executable arm64`
* `installers/astwire-linux-amd64`: `ELF 64-bit LSB pie executable, x86-64`
* `installers/astwire-linux-arm64`: `ELF 64-bit LSB pie executable, ARM aarch64`
* `installers/astwire-windows-amd64.exe`: `PE32+ executable (console) x86-64, for MS Windows`

### Makefile shortcuts

```bash
make build-mac-arm64     # compile.sh -> installers/astwire-darwin-arm64
make build-linux-amd64   # Docker build -> installers/astwire-linux-amd64
make build-linux-arm64   # Docker build -> installers/astwire-linux-arm64
make build-windows       # Wine/PyInstaller build -> installers/astwire-windows-amd64.exe
make build-all           # all four, sequentially
```

---

## Section B: Verification & Integration Testing

### 1. Local Machine Install Verification (macOS ARM64)

Verifies that the Nginx endpoint redirects to R2, downloads the Mach-O binary, and places it into `/usr/local/bin`:

```bash
curl -fsSL https://install.djangoplay.org/astwire | bash
astwire --version
astwire --help
```

### 2. Linux Container Install Verification

**A. Linux x86_64 (`amd64`):**

```bash
docker run --rm -it --platform linux/amd64 python:3.11-slim bash -c "
  apt-get update && apt-get install -y curl sudo && \
  curl -fsSL https://install.djangoplay.org/astwire | bash && \
  astwire --version && \
  astwire --help
"
```

**B. Linux ARM64 (`aarch64`):**

```bash
docker run --rm -it --platform linux/arm64 python:3.11-slim bash -c "
  apt-get update && apt-get install -y curl sudo && \
  curl -fsSL https://install.djangoplay.org/astwire | bash && \
  astwire --version && \
  astwire --help
"
```

### 3. Windows PowerShell Install Verification

Run from PowerShell on Windows 10/11 or Windows Server:

```powershell
irm https://install.djangoplay.org/astwire.ps1 | iex
astwire --version
astwire --help
```

---

## Related

- [`package-release.md`](package-release.md) — condensed release checklist for cutting a new version
- [`local-development.md`](local-development.md) — local build/test setup
- [`../runbooks/release.md`](../runbooks/release.md) — step-by-step release runbook