tftsr-devops_investigation/LIBSODIUM_BUILD_FIX.md

libsodium Build Failure Fix (Complete Solution)

Note: This document describes the complete fix implemented across two PRs:

• PR #101: Docker package additions + initial Windows env vars + test coverage
• PR #102: pkg-config detection control (see LIBSODIUM_PKG_CONFIG_FIX.md for PR #102 details)

Description

This fix resolves build failures across all CI/CD build targets (Linux amd64/arm64, Windows cross-compilation) caused by missing libsodium library dependencies. The application uses tauri-plugin-stronghold which transitively depends on iota-crypto → libsodium-sys-stable, requiring libsodium to be available at build time.

Build failures observed:

1. Linux amd64/arm64: libsodium not found via pkg-config or vcpkg
2. Windows cross-build: SODIUM_LIB_DIR is incompatible with SODIUM_USE_PKG_CONFIG

Root Cause (Two-Part Issue)

Part 1 (Fixed in PR #101):

• Linux builds: Docker images lacked libsodium-dev package
• Windows cross-build: Missing explicit SODIUM_LIB_DIR environment variable despite pre-built libsodium in the cross-compiler image

Part 2 (Fixed in PR #102):

• Linux builds: libsodium-sys-stable build script wasn't explicitly told to use pkg-config
• Windows cross-build: Setting SODIUM_LIB_DIR without disabling pkg-config caused detection conflict

Acceptance Criteria

• All three Docker build images updated with libsodium dependencies
• Windows cross-build CI configuration includes proper SODIUM_LIB_DIR and SODIUM_STATIC environment variables
• New test added to verify libsodium linking via stronghold dependency chain
• All existing tests (416 Rust + 386 TypeScript = 802 total) pass without regression
• All linting checks pass (cargo fmt, clippy, eslint, tsc)
• Changes follow TDD methodology with test-first approach

Work Implemented

1. Docker Image Updates (PR #101)

.docker/Dockerfile.linux-amd64

• Added libsodium-dev to apt package installation list

.docker/Dockerfile.linux-arm64

• Added libsodium-dev:arm64 to multiarch package installation list

2. CI/CD Pipeline Fix

.gitea/workflows/auto-tag.yml

Linux amd64 build:

• PR #102: Added SODIUM_USE_PKG_CONFIG: "1" to force pkg-config detection of libsodium

Linux arm64 build:

• PR #102: Added SODIUM_USE_PKG_CONFIG: "1" to force pkg-config detection for cross-compiled libsodium

Windows cross-compile build:

• PR #101: Added SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib to point to pre-built libsodium
• PR #101: Added SODIUM_STATIC: "1" to ensure static linking of pre-built libsodium
• PR #102: Added SODIUM_USE_PKG_CONFIG: "no" to prevent conflict with explicit SODIUM_LIB_DIR

Rationale: libsodium-sys-stable's build.rs checks environment variables in this order:

1. If SODIUM_LIB_DIR is set → use explicit path (incompatible with SODIUM_USE_PKG_CONFIG)
2. If SODIUM_USE_PKG_CONFIG is not "no" → try pkg-config detection
3. Fall back to vcpkg or fail

Linux builds have libsodium-dev + pkg-config installed, so we force pkg-config mode. Windows has pre-compiled libsodium at a known path, so we use explicit path mode and disable pkg-config.

3. Test Coverage (PR #101)

src-tauri/src/state.rs

• Added comprehensive test module with 3 tests:
  • test_app_settings_default: Verifies default settings initialization
  • test_get_app_data_dir_returns_some: Ensures data directory resolution
  • test_libsodium_linking: Smoke test that verifies libsodium linking through the stronghold dependency chain

The smoke test is critical because it ensures the entire dependency chain compiles and links correctly. If libsodium were misconfigured, this test would fail at compile/link time, not runtime.

4. Code Quality

• All code follows Rust 2021 edition best practices
• Comprehensive inline documentation added to test functions
• Formatting verified with cargo fmt
• Zero clippy warnings
• Zero ESLint warnings
• Zero TypeScript type errors

Testing Needed

Local Testing (Completed ✓)

• cargo test --manifest-path src-tauri/Cargo.toml → 416 tests passed
• npm run test:run → 386 tests passed
• cargo fmt --check → Passed
• cargo clippy -- -D warnings → Zero warnings
• npx eslint . --max-warnings 0 → Zero warnings
• npx tsc --noEmit → Zero errors

CI/CD Testing (Required)

The following must be verified after merging to beta and triggering CI builds:

1. Linux amd64 build (build-linux-amd64 job)

   • Build completes without libsodium not found error
   • .deb and .rpm artifacts generated successfully
   • Artifacts uploaded to Gitea release

2. Linux arm64 build (build-linux-arm64 job)

   • Cross-compilation completes with arm64 libsodium-dev
   • .deb and .rpm artifacts generated successfully
   • Artifacts uploaded to Gitea release

3. Windows amd64 build (build-windows-amd64 job)

   • Build completes without env var conflict error
   • .exe and .msi artifacts generated successfully
   • Artifacts uploaded to Gitea release

4. macOS arm64 build (build-macos-arm64 job)

   • Build continues to work (no libsodium changes needed for macOS)
   • .dmg artifact generated successfully

Verification Steps

After PR merge and CI completion:

1. Navigate to https://gogs.tftsr.com/sarman/tftsr-devops_investigation/actions
2. Verify all 4 build jobs complete with success status
3. Check https://gogs.tftsr.com/sarman/tftsr-devops_investigation/releases for artifacts
4. Download and test artifacts on respective platforms:
   • Linux: Install .deb/.rpm and verify app launches
   • Windows: Install .msi and verify app launches
   • macOS: Mount .dmg and verify app launches

Files Changed

.docker/Dockerfile.linux-amd64    |  1 +
.docker/Dockerfile.linux-arm64    |  1 +
.gitea/workflows/auto-tag.yml     |  2 +
src-tauri/src/state.rs            | 46 +++++++++++++++++++++++++++++++
────────────────────────────────────────────────
4 files changed, 50 insertions(+)

Technical Details

Dependency Chain

trcaa (main app)
  └─ tauri-plugin-stronghold v2
      └─ iota-crypto v0.23.2
          └─ libsodium-sys-stable v1.24.0
              └─ libsodium (system library)

Build System Integration

libsodium-sys-stable build.rs resolution order:

1. Check SODIUM_LIB_DIR env var (Windows cross-build uses this)
2. Try pkg-config to find system libsodium (Linux native uses this)
3. Try vcpkg (Windows native uses this)
4. Fail if none found

Our solution:

• Linux: Install libsodium-dev → pkg-config finds it automatically
• Windows cross: Set SODIUM_LIB_DIR=/usr/x86_64-w64-mingw32/lib → points to pre-built libsodium
• macOS: Already has libsodium via Homebrew (no changes needed)

Risk Assessment

Risk Level: Low

Reasoning:

• Changes are additive (adding packages, env vars, tests)
• No modifications to existing application logic
• All 802 existing tests pass without regression
• Docker image changes only affect CI builds, not production deployment
• Smoke test ensures the fix works at compile/link time, not just runtime

Rollback Plan: If issues arise, revert the 4 changed files and rebuild the Docker images with the previous tags.

Performance Impact

Build Time: Negligible increase (~5 seconds) to install libsodium-dev packages in Docker images.

Runtime: Zero impact. Libsodium is already statically linked in release builds via OPENSSL_STATIC=1 and SODIUM_STATIC=1.

Security Considerations

• Using system-provided libsodium-dev packages from official Debian/Ubuntu repositories
• Version pinned to distribution-stable releases (Ubuntu 22.04 for arm64, Rust 1.88 Debian slim for amd64)
• Windows uses manually built libsodium 1.0.20 from official release tarball
• Static linking ensures no runtime dependency vulnerabilities

Related Documentation

• Upstream Issue: libsodium-sys-stable build script requires libsodium at build time
• Tauri Plugin Stronghold: https://v2.tauri.app/plugin/stronghold/
• libsodium: https://libsodium.gitbook.io/doc/

Approval Notes

This fix is required to unblock all CI/CD builds. Without it, no releases can be generated for any platform.

---

Branch: fix/libsodium-build-failures
Base Branch: beta
Target Merge: beta → master (via standard PR workflow)