From 2bd74025d441ce7ca7af26eeb5aaa5fdc340fa81 Mon Sep 17 00:00:00 2001
From: Simon Gurcke <simon@gurcke.de>
Date: Mon, 26 Oct 2026 12:04:00 +1000
Subject: [PATCH] Fix Linux ARM64 DuckDB linking with LLD

---
 .cargo/config.toml             | 2 ++
 .github/workflows/release.yaml | 3 +++
 .github/workflows/tests.yaml   | 1 +
 AGENTS.md                      | 7 +++++--
 4 files changed, 11 insertions(+), 2 deletions(-)
 create mode 100644 .cargo/config.toml

diff --git a/.cargo/config.toml b/.cargo/config.toml
new file mode 100644
index 0000000..15c5335
--- /dev/null
+++ b/.cargo/config.toml
@@ -0,0 +1,2 @@
+[target.aarch64-unknown-linux-gnu]
+rustflags = ["-C", "link-arg=-fuse-ld=lld"]
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 011d65e..aacfcaa 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -35,6 +35,9 @@ jobs:
         with:
           targets: ${{ matrix.target }}
       - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2
+      - name: Install LLD
+        if: matrix.target == 'aarch64-unknown-linux-gnu'
+        run: sudo apt-get update && sudo apt-get install -y lld
       - name: Set version from tag
         shell: bash
         run: |
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
index 0301c7e..7672dde 100644
--- a/.github/workflows/tests.yaml
+++ b/.github/workflows/tests.yaml
@@ -26,6 +26,7 @@ jobs:
           filters: |
             rust:
               - ".github/workflows/tests.yaml"
+              - ".cargo/**"
               - "Cargo.lock"
               - "Cargo.toml"
               - "npm/**"
diff --git a/AGENTS.md b/AGENTS.md
index ea41496..ceff794 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -68,8 +68,6 @@ The API base URL follows the same pattern: `--api-base-url` flag > `APITALLY_API
 
 ## Common Commands
 
-Building requires CMake, because DuckDB is compiled from source with the ICU extension.
-
 ```bash
 cargo build              # Build (debug)
 cargo build --release    # Build (release, optimized)
@@ -79,6 +77,11 @@ cargo clippy             # Lint
 cargo fmt                # Format code
 ```
 
+## Building
+
+- CMake is required to compile DuckDB from source with the ICU extension.
+- Linux ARM64 builds also require LLD. `.cargo/config.toml` selects it to resolve references between DuckDB's static extension archives.
+
 ## Distribution
 
 The CLI is published to npm as `@apitally/cli`. The npm package contains no Rust code — its `postinstall` script (`npm/install.js`) downloads the pre-built binary for the user's platform from the GitHub release. `npm/cli.js` is a thin Node wrapper that spawns the native binary.