tftsr-devops_investigation/FIX_SUMMARY.md

libsodium Build Failure - FINAL FIX

The Problem

libsodium-sys-stable v1.24.0 build script was failing with:

thread 'main' panicked at build.rs:539:13:
libsodium not found via pkg-config or vcpkg

Root Cause Analysis

After 12 hours of attempts, the issue is clear:

Build Script Logic (from libsodium-sys-stable/build.rs)

The build script checks in priority order:

1. SODIUM_LIB_DIR - if set, use that path directly (HIGHEST PRIORITY)
2. SODIUM_USE_PKG_CONFIG - if set, try pkg-config/vcpkg
3. Fallback - try to build from source

Previous Failed Approaches

1. PR #101, #102: Tried pkg-config environment variables - failed because pkg-config couldn't find libsodium in containers
2. PR with use-pkg-config feature: Enabled the feature but pkg-config still failed to locate libraries

Why pkg-config Failed

• Container images have libsodium installed but pkg-config can't find the .pc files
• Cross-compilation adds complexity to pkg-config searches
• Different containers have different pkg-config configurations

The Solution

Use SODIUM_LIB_DIR to bypass pkg-config entirely.

This directly tells the build script where libsodium is installed, skipping all detection logic.

Implementation

test.yml (Rust tests)

Added to ALL cargo commands:

env:
  SODIUM_LIB_DIR: /usr/lib/x86_64-linux-gnu

auto-tag.yml (Release builds)

Linux x86_64:

SODIUM_LIB_DIR: /usr/lib/x86_64-linux-gnu

Linux aarch64:

SODIUM_LIB_DIR: /usr/lib/aarch64-linux-gnu

Windows MinGW:

SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib

macOS: No change needed (already works)

Why This Will Work

1. SODIUM_LIB_DIR has highest priority in build.rs - checked BEFORE pkg-config
2. Direct path - no detection, no guessing, no pkg-config configuration issues
3. Already confirmed - the original working Windows build used this exact approach
4. Simple - one environment variable per platform

Branch Info

• Branch: fix/libsodium-direct-path
• Base: beta
• Commits: 1 atomic commit
• Files Changed: 2 (.gitea/workflows/test.yml, .gitea/workflows/auto-tag.yml)

Testing Status

• ⏳ Awaiting CI pipeline results
• Expected: ALL builds (Linux x86, Linux ARM, Windows, macOS) will succeed
• Expected: ALL test jobs (fmt, clippy, tests) will succeed

If This Still Fails

The only remaining possibility would be:

1. Libsodium is NOT actually installed in the containers (verify with dpkg -L libsodium-dev)
2. The library path is wrong (verify with find /usr -name "libsodium.*")

But based on previous error messages showing pkg-config attempts, libsodium IS installed - we just need to tell the build script where it is.

---

Created: 2026-06-14 (after 12 hours of attempts)
Approach: Direct library path specification
Confidence: HIGH - This is the intended workaround when pkg-config fails

Update History

Commit 1: Initial SODIUM_LIB_DIR implementation

Added SODIUM_LIB_DIR to all workflows, but conflicted with existing use-pkg-config feature.

Commit 2: Remove conflicting feature

Removed libsodium-sys-stable = { version = "1.24", features = ["use-pkg-config"] } from Cargo.toml. The build script doesn't allow both SODIUM_LIB_DIR and SODIUM_USE_PKG_CONFIG simultaneously.

Commit 3: Refactor to job-level env

Moved SODIUM_LIB_DIR from per-step env to job-level env in test.yml for consistency and to ensure ALL cargo commands (including cargo generate-lockfile) have access to it.

Final State

Branch commits:

1. 863868b2 - fix(ci): use SODIUM_LIB_DIR to bypass pkg-config detection
2. b20deab3 - fix: remove use-pkg-config feature conflicting with SODIUM_LIB_DIR
3. 1172f201 - refactor(ci): move SODIUM_LIB_DIR to job-level env

Files modified:

• .gitea/workflows/test.yml - SODIUM_LIB_DIR at job level for 3 Rust jobs
• .gitea/workflows/auto-tag.yml - SODIUM_LIB_DIR in Build steps for all platforms
• src-tauri/Cargo.toml - Removed conflicting use-pkg-config dependency
• src-tauri/Cargo.lock - Updated after dependency removal

Automated Review: APPROVE WITH COMMENTS (addressed in commit 3)