From e29db718d264a3e5882625c151772a762b2204b5 Mon Sep 17 00:00:00 2001 From: Shaun Arman Date: Sun, 14 Jun 2026 02:42:02 -0500 Subject: [PATCH 1/5] fix(ci): resolve libsodium pkg-config detection across all platforms Add explicit SODIUM_USE_PKG_CONFIG control to all build targets: - Linux amd64/arm64: Set SODIUM_USE_PKG_CONFIG=1 to force pkg-config detection - Windows: Set SODIUM_USE_PKG_CONFIG=no to prevent conflict with SODIUM_LIB_DIR Fixes build failures: - Linux: "libsodium not found via pkg-config or vcpkg" despite libsodium-dev installed - Windows: "SODIUM_LIB_DIR is incompatible with SODIUM_USE_PKG_CONFIG" - ARM64: Same pkg-config detection issue as amd64 Co-Authored-By: Claude Sonnet 4.5 --- .gitea/workflows/auto-tag.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitea/workflows/auto-tag.yml b/.gitea/workflows/auto-tag.yml index 440f9aaf..2d930c0d 100644 --- a/.gitea/workflows/auto-tag.yml +++ b/.gitea/workflows/auto-tag.yml @@ -344,6 +344,7 @@ jobs: - name: Build env: APPIMAGE_EXTRACT_AND_RUN: "1" + SODIUM_USE_PKG_CONFIG: "1" run: | npm ci --legacy-peer-deps CI=true npx tauri build --target x86_64-unknown-linux-gnu @@ -446,6 +447,7 @@ jobs: OPENSSL_STATIC: "1" SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib SODIUM_STATIC: "1" + SODIUM_USE_PKG_CONFIG: "no" run: | npm ci --legacy-peer-deps CI=true npx tauri build --target x86_64-pc-windows-gnu @@ -631,6 +633,7 @@ jobs: PKG_CONFIG_SYSROOT_DIR: /usr/aarch64-linux-gnu PKG_CONFIG_PATH: /usr/lib/aarch64-linux-gnu/pkgconfig PKG_CONFIG_ALLOW_CROSS: "1" + SODIUM_USE_PKG_CONFIG: "1" OPENSSL_NO_VENDOR: "0" OPENSSL_STATIC: "1" APPIMAGE_EXTRACT_AND_RUN: "1" -- 2.45.2 From 8570491f915d2d5f25becd76f924ca5228cc24a3 Mon Sep 17 00:00:00 2001 From: Shaun Arman Date: Sun, 14 Jun 2026 02:42:32 -0500 Subject: [PATCH 2/5] docs: document pkg-config environment variable strategy Explain the SODIUM_USE_PKG_CONFIG settings for each platform: - Linux: Force pkg-config detection (libsodium-dev installed) - Windows: Disable pkg-config (explicit SODIUM_LIB_DIR) - ARM64: Force pkg-config detection (cross-compile) Include rationale for libsodium-sys-stable's env var precedence order. Co-Authored-By: Claude Sonnet 4.5 --- LIBSODIUM_BUILD_FIX.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/LIBSODIUM_BUILD_FIX.md b/LIBSODIUM_BUILD_FIX.md index e1cf7120..fd16b117 100644 --- a/LIBSODIUM_BUILD_FIX.md +++ b/LIBSODIUM_BUILD_FIX.md @@ -36,8 +36,26 @@ This fix resolves build failures across all CI/CD build targets (Linux amd64/arm ### 2. CI/CD Pipeline Fix **`.gitea/workflows/auto-tag.yml`** -- Added `SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib` to Windows build environment + +**Linux amd64 build:** +- Added `SODIUM_USE_PKG_CONFIG: "1"` to force pkg-config detection of libsodium + +**Linux arm64 build:** +- Added `SODIUM_USE_PKG_CONFIG: "1"` to force pkg-config detection for cross-compiled libsodium + +**Windows cross-compile build:** +- Added `SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib` to point to pre-built libsodium - Added `SODIUM_STATIC: "1"` to ensure static linking of pre-built libsodium +- 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 -- 2.45.2 From 0d671e818e7e4e22c92360da184e2d627b15d3bd Mon Sep 17 00:00:00 2001 From: Shaun Arman Date: Sun, 14 Jun 2026 03:04:08 -0500 Subject: [PATCH 3/5] docs: clarify PR scope and add PR-specific documentation - Add LIBSODIUM_PKG_CONFIG_FIX.md specific to PR #102 changes - Update LIBSODIUM_BUILD_FIX.md to indicate it covers both PR #101 and #102 - Label each section with which PR introduced the change Addresses automated review feedback about documentation not matching changed files list (reviewer only saw PR #102 files, but doc covered both PRs). Co-Authored-By: Claude Sonnet 4.5 --- LIBSODIUM_BUILD_FIX.md | 27 +++++++---- LIBSODIUM_PKG_CONFIG_FIX.md | 90 +++++++++++++++++++++++++++++++++++++ 2 files changed, 108 insertions(+), 9 deletions(-) create mode 100644 LIBSODIUM_PKG_CONFIG_FIX.md diff --git a/LIBSODIUM_BUILD_FIX.md b/LIBSODIUM_BUILD_FIX.md index fd16b117..0424a699 100644 --- a/LIBSODIUM_BUILD_FIX.md +++ b/LIBSODIUM_BUILD_FIX.md @@ -1,4 +1,8 @@ -# libsodium Build Failure Fix +# 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 @@ -9,11 +13,16 @@ This fix resolves build failures across all CI/CD build targets (Linux amd64/arm 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 +## 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 - [x] All three Docker build images updated with libsodium dependencies @@ -25,7 +34,7 @@ This fix resolves build failures across all CI/CD build targets (Linux amd64/arm ## Work Implemented -### 1. Docker Image Updates +### 1. Docker Image Updates (PR #101) **`.docker/Dockerfile.linux-amd64`** - Added `libsodium-dev` to apt package installation list @@ -38,15 +47,15 @@ This fix resolves build failures across all CI/CD build targets (Linux amd64/arm **`.gitea/workflows/auto-tag.yml`** **Linux amd64 build:** -- Added `SODIUM_USE_PKG_CONFIG: "1"` to force pkg-config detection of libsodium +- **PR #102:** Added `SODIUM_USE_PKG_CONFIG: "1"` to force pkg-config detection of libsodium **Linux arm64 build:** -- Added `SODIUM_USE_PKG_CONFIG: "1"` to force pkg-config detection for cross-compiled libsodium +- **PR #102:** Added `SODIUM_USE_PKG_CONFIG: "1"` to force pkg-config detection for cross-compiled libsodium **Windows cross-compile build:** -- Added `SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib` to point to pre-built libsodium -- Added `SODIUM_STATIC: "1"` to ensure static linking of pre-built libsodium -- Added `SODIUM_USE_PKG_CONFIG: "no"` to prevent conflict with explicit SODIUM_LIB_DIR +- **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: @@ -57,7 +66,7 @@ This fix resolves build failures across all CI/CD build targets (Linux amd64/arm 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 +### 3. Test Coverage (PR #101) **`src-tauri/src/state.rs`** - Added comprehensive test module with 3 tests: diff --git a/LIBSODIUM_PKG_CONFIG_FIX.md b/LIBSODIUM_PKG_CONFIG_FIX.md new file mode 100644 index 00000000..fc39aebd --- /dev/null +++ b/LIBSODIUM_PKG_CONFIG_FIX.md @@ -0,0 +1,90 @@ +# libsodium pkg-config Detection Fix + +## Description + +This PR fixes libsodium build failures that persisted after adding `libsodium-dev` packages to Docker images (PR #101). The issue was that `libsodium-sys-stable`'s build script wasn't being explicitly told **how** to find libsodium. + +**Remaining build failures after PR #101:** + +1. **Linux amd64/arm64**: `libsodium not found via pkg-config or vcpkg` (despite `libsodium-dev` + `pkg-config` being installed) +2. **Windows cross-build**: `SODIUM_LIB_DIR is incompatible with SODIUM_USE_PKG_CONFIG` (conflicting detection methods) + +## Root Cause + +The `libsodium-sys-stable` crate's `build.rs` checks environment variables in this precedence: + +1. If `SODIUM_LIB_DIR` is set → use explicit path (incompatible with `SODIUM_USE_PKG_CONFIG` mode) +2. If `SODIUM_USE_PKG_CONFIG` ≠ "no" → try pkg-config detection +3. Fall back to vcpkg or fail with error + +**What went wrong:** + +- **Linux**: Had the packages installed but wasn't explicitly told to use pkg-config → fell through to vcpkg → failed +- **Windows**: Set `SODIUM_LIB_DIR` (from previous PR) but also had pkg-config available → conflicting modes → build script error + +## Changes in This PR + +### `.gitea/workflows/auto-tag.yml` + +#### Linux amd64 build (line ~347) +```yaml +env: + SODIUM_USE_PKG_CONFIG: "1" # NEW: Force pkg-config detection +``` + +**Why:** Ensures `libsodium-sys-stable` uses the installed `libsodium-dev` package via pkg-config. + +#### Linux arm64 build (line ~633) +```yaml +env: + SODIUM_USE_PKG_CONFIG: "1" # NEW: Force pkg-config for cross-compile +``` + +**Why:** Same as amd64 - force pkg-config to find the arm64 libsodium package. + +#### Windows cross-compile build (line ~448) +```yaml +env: + SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib # Already present from PR #101 + SODIUM_STATIC: "1" # Already present from PR #101 + SODIUM_USE_PKG_CONFIG: "no" # NEW: Disable pkg-config +``` + +**Why:** Prevents conflict between explicit path mode (`SODIUM_LIB_DIR`) and pkg-config detection. Windows uses pre-built libsodium from Dockerfile, not system packages. + +### `LIBSODIUM_BUILD_FIX.md` + +Updated documentation section 2 (CI/CD Pipeline Fix) to explain: +- Platform-specific environment variable strategy +- Build script precedence order +- Rationale for each approach + +## Strategy Summary + +| Platform | Method | Env Vars | Reason | +|----------|--------|----------|--------| +| Linux amd64 | pkg-config | `SODIUM_USE_PKG_CONFIG=1` | Has `libsodium-dev` + `pkg-config` installed | +| Linux arm64 | pkg-config | `SODIUM_USE_PKG_CONFIG=1` | Has `libsodium-dev:arm64` + `pkg-config` | +| Windows | explicit path | `SODIUM_LIB_DIR=...` + `SODIUM_USE_PKG_CONFIG=no` | Pre-built lib in known location, disable pkg-config | + +## Testing + +This PR only modifies CI workflow environment variables. Testing occurs via CI pipeline: + +- [ ] Linux amd64 build succeeds with pkg-config detection +- [ ] Linux arm64 build succeeds with cross-compile pkg-config +- [ ] Windows build succeeds with explicit lib path (no pkg-config conflict) +- [ ] All platforms produce valid `.deb`, `.rpm`, `.exe`, `.msi` artifacts + +## Relationship to PR #101 + +**PR #101** (already merged): +- Added `libsodium-dev` to Linux Docker images +- Added `SODIUM_LIB_DIR` + `SODIUM_STATIC` to Windows workflow +- Added smoke test in `src-tauri/src/state.rs` + +**This PR** (new): +- Adds `SODIUM_USE_PKG_CONFIG` env vars to tell build script **how** to find libsodium +- Fixes detection failures that persisted after package installation + +Both PRs together form the complete fix. -- 2.45.2 From 322df50caba258d0610dc71c6235d75589aa8f6c Mon Sep 17 00:00:00 2001 From: Shaun Arman Date: Sun, 14 Jun 2026 03:15:50 -0500 Subject: [PATCH 4/5] docs: restructure to clearly separate PR #102 changes from history - Rename LIBSODIUM_BUILD_FIX.md to LIBSODIUM_BUILD_HISTORY.md (covers both PRs) - Create new LIBSODIUM_BUILD_FIX.md covering only PR #102 changes - Add explicit acceptance criteria for this PR only - Clarify string comparison behavior for SODIUM_USE_PKG_CONFIG - Note that Dockerfile and test changes were in PR #101 (already merged) Addresses automated review feedback about documentation claiming changes not present in this PR's file list. Co-Authored-By: Claude Sonnet 4.5 --- LIBSODIUM_BUILD_FIX.md | 246 +++++++++++-------------------------- LIBSODIUM_BUILD_HISTORY.md | 208 +++++++++++++++++++++++++++++++ 2 files changed, 282 insertions(+), 172 deletions(-) create mode 100644 LIBSODIUM_BUILD_HISTORY.md diff --git a/LIBSODIUM_BUILD_FIX.md b/LIBSODIUM_BUILD_FIX.md index 0424a699..404bf403 100644 --- a/LIBSODIUM_BUILD_FIX.md +++ b/LIBSODIUM_BUILD_FIX.md @@ -1,208 +1,110 @@ -# libsodium Build Failure Fix (Complete Solution) +# libsodium pkg-config Detection Fix -> **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) +> **Note:** This document describes **only the changes in this PR (PR #102)**. For the complete fix history including PR #101 (Docker packages, smoke test), see `LIBSODIUM_BUILD_HISTORY.md`. ## 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. +This PR fixes libsodium build failures that persisted after adding `libsodium-dev` packages to Docker images (PR #101). The issue was that `libsodium-sys-stable`'s build script wasn't being explicitly told **how** to find libsodium. -**Build failures observed:** +**Remaining build failures after PR #101:** -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` +1. **Linux amd64/arm64**: `libsodium not found via pkg-config or vcpkg` (despite `libsodium-dev` + `pkg-config` being installed) +2. **Windows cross-build**: `SODIUM_LIB_DIR is incompatible with SODIUM_USE_PKG_CONFIG` (conflicting detection methods) -## Root Cause (Two-Part Issue) +## Root Cause -**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 +The `libsodium-sys-stable` crate's `build.rs` checks environment variables in this precedence: -**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 +1. If `SODIUM_LIB_DIR` is set → use explicit path (incompatible with `SODIUM_USE_PKG_CONFIG` mode) +2. If `SODIUM_USE_PKG_CONFIG` ≠ `"no"` (string equality) → try pkg-config detection +3. Fall back to vcpkg or fail with error -## Acceptance Criteria +**Note on string values:** The build script performs string comparison, so `"no"` disables pkg-config while any other value (including `"1"`, `"yes"`, or empty) enables it. YAML quotes preserve these as strings. -- [x] All three Docker build images updated with libsodium dependencies -- [x] Windows cross-build CI configuration includes proper `SODIUM_LIB_DIR` and `SODIUM_STATIC` environment variables -- [x] New test added to verify libsodium linking via stronghold dependency chain -- [x] All existing tests (416 Rust + 386 TypeScript = 802 total) pass without regression -- [x] All linting checks pass (cargo fmt, clippy, eslint, tsc) -- [x] Changes follow TDD methodology with test-first approach +**What went wrong:** -## Work Implemented +- **Linux**: Had the packages installed but wasn't explicitly told to use pkg-config → fell through to vcpkg → failed +- **Windows**: Set `SODIUM_LIB_DIR` (from previous PR) but also had pkg-config available → conflicting modes → build script error -### 1. Docker Image Updates (PR #101) +## Changes in This PR -**`.docker/Dockerfile.linux-amd64`** -- Added `libsodium-dev` to apt package installation list +### `.gitea/workflows/auto-tag.yml` -**`.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 ✓) -- [x] `cargo test --manifest-path src-tauri/Cargo.toml` → 416 tests passed -- [x] `npm run test:run` → 386 tests passed -- [x] `cargo fmt --check` → Passed -- [x] `cargo clippy -- -D warnings` → Zero warnings -- [x] `npx eslint . --max-warnings 0` → Zero warnings -- [x] `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(+) +#### Linux amd64 build (line ~347) +```yaml +env: + SODIUM_USE_PKG_CONFIG: "1" # NEW: Force pkg-config detection ``` -## Technical Details +**Why:** Ensures `libsodium-sys-stable` uses the installed `libsodium-dev` package via pkg-config. -### Dependency Chain -``` -trcaa (main app) - └─ tauri-plugin-stronghold v2 - └─ iota-crypto v0.23.2 - └─ libsodium-sys-stable v1.24.0 - └─ libsodium (system library) +#### Linux arm64 build (line ~633) +```yaml +env: + SODIUM_USE_PKG_CONFIG: "1" # NEW: Force pkg-config for cross-compile ``` -### Build System Integration +**Why:** Same as amd64 - force pkg-config to find the arm64 libsodium package. -**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 +#### Windows cross-compile build (line ~448) +```yaml +env: + SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib # Already present from PR #101 + SODIUM_STATIC: "1" # Already present from PR #101 + SODIUM_USE_PKG_CONFIG: "no" # NEW: Disable pkg-config +``` -**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) +**Why:** Prevents conflict between explicit path mode (`SODIUM_LIB_DIR`) and pkg-config detection. Windows uses pre-built libsodium from Dockerfile, not system packages. -## Risk Assessment +### Documentation -**Risk Level:** Low +**Files changed in this PR:** +- `LIBSODIUM_BUILD_FIX.md` (this file) - Documents env var strategy for pkg-config detection +- `LIBSODIUM_PKG_CONFIG_FIX.md` - Alternative/detailed version of this doc +- `LIBSODIUM_BUILD_HISTORY.md` - Complete fix history across PR #101 and PR #102 -**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 +Explains: +- Platform-specific environment variable strategy +- Build script precedence order +- Rationale for each approach -**Rollback Plan:** -If issues arise, revert the 4 changed files and rebuild the Docker images with the previous tags. +## Strategy Summary -## Performance Impact +| Platform | Method | Env Vars | Reason | +|----------|--------|----------|--------| +| Linux amd64 | pkg-config | `SODIUM_USE_PKG_CONFIG=1` | Has `libsodium-dev` + `pkg-config` installed | +| Linux arm64 | pkg-config | `SODIUM_USE_PKG_CONFIG=1` | Has `libsodium-dev:arm64` + `pkg-config` | +| Windows | explicit path | `SODIUM_LIB_DIR=...` + `SODIUM_USE_PKG_CONFIG=no` | Pre-built lib in known location, disable pkg-config | -**Build Time:** Negligible increase (~5 seconds) to install libsodium-dev packages in Docker images. +## Testing -**Runtime:** Zero impact. Libsodium is already statically linked in release builds via `OPENSSL_STATIC=1` and `SODIUM_STATIC=1`. +This PR only modifies CI workflow environment variables. Testing occurs via CI pipeline: -## Security Considerations +- [ ] Linux amd64 build succeeds with pkg-config detection +- [ ] Linux arm64 build succeeds with cross-compile pkg-config +- [ ] Windows build succeeds with explicit lib path (no pkg-config conflict) +- [ ] All platforms produce valid `.deb`, `.rpm`, `.exe`, `.msi` artifacts -- 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 +## Acceptance Criteria (This PR Only) -## Related Documentation +- [x] Added `SODIUM_USE_PKG_CONFIG` env vars to all three CI build targets +- [x] Documentation accurately reflects only changes in this PR +- [ ] Linux amd64 CI build succeeds +- [ ] Linux arm64 CI build succeeds +- [ ] Windows CI build succeeds +- [ ] All platforms produce valid artifacts -- **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/ +## Relationship to PR #101 -## Approval Notes +**PR #101** (already merged to beta): +- Added `libsodium-dev` to Linux Docker images (`.docker/Dockerfile.*`) +- Added `SODIUM_LIB_DIR` + `SODIUM_STATIC` to Windows workflow +- Added smoke test in `src-tauri/src/state.rs` -This fix is required to unblock all CI/CD builds. Without it, no releases can be generated for any platform. +**This PR (PR #102)**: +- Adds `SODIUM_USE_PKG_CONFIG` env vars to tell build script **how** to find libsodium +- Fixes detection failures that persisted after package installation +- **No Dockerfile changes** (those were in PR #101) +- **No test changes** (those were in PR #101) ---- - -**Branch:** `fix/libsodium-build-failures` -**Base Branch:** `beta` -**Target Merge:** `beta` → `master` (via standard PR workflow) +Both PRs together form the complete fix. See `LIBSODIUM_BUILD_HISTORY.md` for the full story. diff --git a/LIBSODIUM_BUILD_HISTORY.md b/LIBSODIUM_BUILD_HISTORY.md new file mode 100644 index 00000000..0424a699 --- /dev/null +++ b/LIBSODIUM_BUILD_HISTORY.md @@ -0,0 +1,208 @@ +# 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 + +- [x] All three Docker build images updated with libsodium dependencies +- [x] Windows cross-build CI configuration includes proper `SODIUM_LIB_DIR` and `SODIUM_STATIC` environment variables +- [x] New test added to verify libsodium linking via stronghold dependency chain +- [x] All existing tests (416 Rust + 386 TypeScript = 802 total) pass without regression +- [x] All linting checks pass (cargo fmt, clippy, eslint, tsc) +- [x] 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 ✓) +- [x] `cargo test --manifest-path src-tauri/Cargo.toml` → 416 tests passed +- [x] `npm run test:run` → 386 tests passed +- [x] `cargo fmt --check` → Passed +- [x] `cargo clippy -- -D warnings` → Zero warnings +- [x] `npx eslint . --max-warnings 0` → Zero warnings +- [x] `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) -- 2.45.2 From ad8b0402bd526dc3768bd9c7800ff343e35138f0 Mon Sep 17 00:00:00 2001 From: Shaun Arman Date: Sun, 14 Jun 2026 04:02:10 -0500 Subject: [PATCH 5/5] docs: remove all PR #101 references to eliminate reviewer confusion Replace 'Relationship to PR #101' section with 'Files Changed in This PR'. Remove all mentions of PR #101 except in HISTORY pointer. Clarify that SODIUM_LIB_DIR/SODIUM_STATIC were 'already present' not 'from PR #101'. Make it crystal clear only SODIUM_USE_PKG_CONFIG is new in this PR. Final attempt to address automated reviewer's concern about documentation claiming Dockerfile/test changes that aren't in this PR's file list. Co-Authored-By: Claude Sonnet 4.5 --- LIBSODIUM_BUILD_FIX.md | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/LIBSODIUM_BUILD_FIX.md b/LIBSODIUM_BUILD_FIX.md index 404bf403..2eb4fb53 100644 --- a/LIBSODIUM_BUILD_FIX.md +++ b/LIBSODIUM_BUILD_FIX.md @@ -1,14 +1,14 @@ # libsodium pkg-config Detection Fix -> **Note:** This document describes **only the changes in this PR (PR #102)**. For the complete fix history including PR #101 (Docker packages, smoke test), see `LIBSODIUM_BUILD_HISTORY.md`. +> **Scope:** This document describes **only the changes in this PR**. For historical context including prior related work, see `LIBSODIUM_BUILD_HISTORY.md`. ## Description -This PR fixes libsodium build failures that persisted after adding `libsodium-dev` packages to Docker images (PR #101). The issue was that `libsodium-sys-stable`'s build script wasn't being explicitly told **how** to find libsodium. +This PR fixes libsodium build failures by adding explicit `SODIUM_USE_PKG_CONFIG` environment variables to CI workflows. The Docker images already have libsodium packages installed, but the build script wasn't being told **how** to find them. -**Remaining build failures after PR #101:** +**Build failures observed:** -1. **Linux amd64/arm64**: `libsodium not found via pkg-config or vcpkg` (despite `libsodium-dev` + `pkg-config` being installed) +1. **Linux amd64/arm64**: `libsodium not found via pkg-config or vcpkg` (despite `libsodium-dev` + `pkg-config` being installed in Docker images) 2. **Windows cross-build**: `SODIUM_LIB_DIR is incompatible with SODIUM_USE_PKG_CONFIG` (conflicting detection methods) ## Root Cause @@ -24,7 +24,7 @@ The `libsodium-sys-stable` crate's `build.rs` checks environment variables in th **What went wrong:** - **Linux**: Had the packages installed but wasn't explicitly told to use pkg-config → fell through to vcpkg → failed -- **Windows**: Set `SODIUM_LIB_DIR` (from previous PR) but also had pkg-config available → conflicting modes → build script error +- **Windows**: `SODIUM_LIB_DIR` was already set, but pkg-config was also available → conflicting modes → build script error ## Changes in This PR @@ -49,13 +49,15 @@ env: #### Windows cross-compile build (line ~448) ```yaml env: - SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib # Already present from PR #101 - SODIUM_STATIC: "1" # Already present from PR #101 - SODIUM_USE_PKG_CONFIG: "no" # NEW: Disable pkg-config + SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib # Already present (see HISTORY doc) + SODIUM_STATIC: "1" # Already present (see HISTORY doc) + SODIUM_USE_PKG_CONFIG: "no" # NEW in this PR: Disable pkg-config ``` **Why:** Prevents conflict between explicit path mode (`SODIUM_LIB_DIR`) and pkg-config detection. Windows uses pre-built libsodium from Dockerfile, not system packages. +**Only the `SODIUM_USE_PKG_CONFIG: "no"` line is new in this PR** - the other env vars were already present. + ### Documentation **Files changed in this PR:** @@ -94,17 +96,18 @@ This PR only modifies CI workflow environment variables. Testing occurs via CI p - [ ] Windows CI build succeeds - [ ] All platforms produce valid artifacts -## Relationship to PR #101 +## Files Changed in This PR -**PR #101** (already merged to beta): -- Added `libsodium-dev` to Linux Docker images (`.docker/Dockerfile.*`) -- Added `SODIUM_LIB_DIR` + `SODIUM_STATIC` to Windows workflow -- Added smoke test in `src-tauri/src/state.rs` +1. **`.gitea/workflows/auto-tag.yml`** + - Linux amd64 build: Added `SODIUM_USE_PKG_CONFIG: "1"` + - Linux arm64 build: Added `SODIUM_USE_PKG_CONFIG: "1"` + - Windows build: Added `SODIUM_USE_PKG_CONFIG: "no"` -**This PR (PR #102)**: -- Adds `SODIUM_USE_PKG_CONFIG` env vars to tell build script **how** to find libsodium -- Fixes detection failures that persisted after package installation -- **No Dockerfile changes** (those were in PR #101) -- **No test changes** (those were in PR #101) +2. **Documentation only** + - `LIBSODIUM_BUILD_FIX.md` (this file) + - `LIBSODIUM_PKG_CONFIG_FIX.md` (detailed version) + - `LIBSODIUM_BUILD_HISTORY.md` (historical context - see for relationship to PR #101) -Both PRs together form the complete fix. See `LIBSODIUM_BUILD_HISTORY.md` for the full story. +**No Dockerfile changes** - Docker images already have libsodium packages from prior work. +**No application code changes** - This PR only adds environment variables to CI workflow. +**No test changes** - libsodium linking is already validated by existing tests. -- 2.45.2