tftsr-devops_investigation/LIBSODIUM_BUILD_FIX.md

libsodium pkg-config Detection Fix

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 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.

Build failures observed:

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

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" (string equality) → try pkg-config detection
3. Fall back to vcpkg or fail with error

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.

What went wrong:

• Linux: Had the packages installed but wasn't explicitly told to use pkg-config → fell through to vcpkg → failed
• Windows: SODIUM_LIB_DIR was already set, but pkg-config was also available → conflicting modes → build script error

Changes in This PR

.gitea/workflows/auto-tag.yml

Linux amd64 build (line ~347)

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)

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)

env:
  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:

• 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

Explains:

• 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

Acceptance Criteria (This PR Only)

• Added SODIUM_USE_PKG_CONFIG env vars to all three CI build targets
• 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

Files Changed in This PR

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"

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)

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.