iOS Build Issue - Libbox Module Not Found

🚨 Problem Summary

The iOS build is failing with the error:

error: Unable to find module dependency: 'Libbox'
import Libbox

🔍 Root Cause Analysis

After extensive debugging, we've identified the root cause:

The Library target does NOT link Libbox.xcframework in its Build Phases

Evidence

From project.pbxproj file analysis:

Library target's Frameworks build phase (line 515-524):

3AEC211A2A459B4700A63465 /* Frameworks */ = {
  isa = PBXFrameworksBuildPhase;
  files = (
    0451E1D62CC3AE2800E9A49F /* GRDB in Frameworks */,
    3A7E90382A46778E00D53052 /* BinaryCodable in Frameworks */,
    3AF3A3D22B2207F3001FD7C1 /* libresolv.tbd in Frameworks */,
  );
};

Notice: Libbox.xcframework is NOT in this list!

However, Libbox.xcframework IS linked in other targets:

Line 507: Libbox.xcframework is linked in another target's Frameworks phase
Line 178: Libbox.xcframework is referenced in the project

What This Means

Libbox.xcframework exists in the project and is correctly tracked by Git
Libbox.xcframework binary is ~60MB and should be downloaded correctly
Library target uses Libbox in its Swift code (import Libbox)
But Library target doesn't link Libbox.xcframework in its Build Phases

This is a missing framework linking configuration issue.

🔧 Required Fix

Option 1: Fix in Xcode (Recommended)

Open iOS-SwiftUI-Code/uuvpn.xcodeproj in Xcode
Select the Library target (not the SFI scheme)
Go to Build Phases tab
Expand Link Binary With Libraries
Click + button
Add Libbox.xcframework
Build and test locally
Commit and push the changes

Option 2: Manual pbxproj Edit (Advanced)

This requires manually editing project.pbxproj to add:

A PBXBuildFile entry for Libbox in Library's Frameworks phase
Add the file reference to Library's Frameworks build phase

This is complex and error-prone. Not recommended unless you're experienced with Xcode project file format.

📊 Verification

After fixing, verify by building locally:

cd iOS-SwiftUI-Code
xcodebuild -project uuvpn.xcodeproj -scheme SFI -sdk iphonesimulator -configuration Debug

If successful, commit and push, then the GitHub Actions build should work.

🎯 Why This Happened

This appears to be a project configuration issue in the original UUVPN repository. The Library target needs Libbox to compile, but the framework linking was never added to the Library target's Build Phases.

📝 Additional Notes

Libbox.xcframework is a precompiled binary framework (~60MB)
It contains binaries for iOS (device), iOS Simulator, macOS, and tvOS
The framework is used for VPN core functionality
Multiple files in Library import Libbox:
- ExtensionProvider.swift
- Profile+Transferable.swift
- Profile+Share.swift
- Extension+RunBlocking.swift
- HTTPClient.swift
- ProfileServer.swift
- Profile+Update.swift
- Extension+Iterator.swift
- NWSocket.swift
- ExtensionPlatformInterface.swift
- CommandClient.swift
- ExtensionProfile.swift

⚠️ Current Status

✅ Libbox.xcframework exists in repository
✅ Libbox.xcframework is tracked by Git
✅ Libbox binary file is ~60MB (not a placeholder)
❌ Library target does NOT link Libbox.xcframework
❌ iOS build fails due to missing module dependency

Action Required: Fix project configuration in Xcode

Generated by CI/CD debugging on 2026-07-02

3.5 KiB Raw Blame History