No symbols are extracted when generating documentation (w/ the CLI) while the package uses a local XCFramework reference

[heckj]

I ran into an odd situation where I when I attempted to use swift-docc-plugin to generate documentation archives (either converted for static HTML or the original DocC archives), the archives would end up with 0 symbols within them.

An example of this kind of project is OSS in github: automerge-swift and the relevant pieces that make the difference here is a local reference to an XCFramework. The relevant stanza of Package.swift to illustrate:

   .binaryTarget(
      name: "automergeFFI",
      path: "./automergeFFI.xcframework.zip"
    ),
    .target(
      name: "AutomergeUniffi",
      dependencies: ["automergeFFI"],
      path: "./AutomergeUniffi"
    ),
    .target(
      name: "Automerge",
      dependencies: ["AutomergeUniffi"]
    ),

I dug through this down into SwiftPM, where the symbols are extracted. The relevant process call to do the extraction isn't available using -v or -vv output from swift package, but is in the form of:

/Applications/Xcode-14.3_beta_2.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/swift-symbolgraph-extract -module-name Automerge -target arm64-apple-macosx10.15 -I /Users/heckj/src/automerge-swifter/.build/arm64-apple-macosx/debug -sdk /Applications/Xcode-14.3_beta_2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX13.3.sdk -F /Applications/Xcode-14.3_beta_2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Frameworks -I /Applications/Xcode-14.3_beta_2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/usr/lib -L /Applications/Xcode-14.3_beta_2.app/Contents/Developer/Platforms/MacOSX.platform/Developer/usr/lib -module-cache-path /Users/heckj/src/automerge-swifter/.build/arm64-apple-macosx/debug/ModuleCache -v -minimum-access-level public -skip-inherited-docs -omit-extension-block-symbols -output-dir /Users/heckj/src/automerge-swifter/temp

This script doesn't reference the local XCFramework directories at all, resulting in the whole extraction process failing with out propagating up a failure (as opposed to a "no symbols" scenario, which seems like a correct, non-failure response for an empty swift file kind of setup).

Building the package with this structure works without issue - so it seems that the core issue under the covers is that the extraction of symbols uses different logic to build up the includes, or pre-loads a module cache, where the symbol extraction doesn't do that. Therefore a workaround exists to run a build to explicitly pull our the symbols, and then run docc directly with a reference to that manually generated symbol cache.

This issue only appears to happen when using a local XCFramework reference. When using a binaryTarget with a remote reference and hash, it "does the right thing" with preloading a module cache or including the relevant directories (not sure which).

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

documentation archive to contain symbols

Actual behavior

documentation archives generated with any internal content, but no symbols are included within them.

Steps to Reproduce

The branch debug-docc-plugin on the repository https://github.com/heckj/automerge-swifter/ illustrates the issue with a script:

git clone https://github.com/automerge/automerge-swift -b debug-docc-plugin
cd automerge-swift
./scripts/build-xcframework.sh # NOTE: requires Rust to be installed to build this!
./test-docc-script.bash

Example output of script:

Building for debugging...
[54/54] Linking snippet-extract
Build complete! (4.26s)
Generating documentation for 'Automerge'...
symbol graph options: 'SymbolGraphOptions(minimumAccessLevel: PackagePlugin.PackageManager.SymbolGraphOptions.AccessLevel.public, includeSynthesized: true, includeSPI: false, emitExtensionBlocks: false)'
Building for debugging...
[15/15] Compiling Automerge value.swift
Build complete! (2.35s)
target symbol graph directory path: '/Users/heckj/Desktop/foo/automerge-swifter/.build/arm64-apple-macosx/extracted-symbols/automerge-swifter/Automerge'
snippet extractor provided, attempting to generate snippet symbol graph
no snippet symbol graphs generated
docc archive output path: '/Users/heckj/Desktop/foo/automerge-swifter/.build/plugins/Swift-DocC/outputs/Automerge.doccarchive'
docc invocation: '/Applications/Xcode-14.3_beta_2.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc convert /Users/heckj/Desktop/foo/automerge-swifter/Sources/Automerge/Automerge.docc --fallback-bundle-identifier com.github.automerge.automerge-swifter --output-path ./docs --emit-digest --transform-for-static-hosting --hosting-base-path automerge-swifter --fallback-display-name Automerge --additional-symbol-graph-dir /Users/heckj/Desktop/foo/automerge-swifter/.build/arm64-apple-macosx/extracted-symbols/automerge-swifter/Automerge'
Converting documentation...
Conversion complete! (0.26s)
Generated DocC archive at '/Users/heckj/Desktop/foo/automerge-swifter/docs'
Generated        0 identifiers/symbols

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.1.0, and main (6a8f81a21df0aef44513f5ce25b58ae758347789)
Swift Compiler version: ```
swift-driver version: 1.75.1 Apple Swift version 5.8 (swiftlang-5.8.0.119.11 clang-1403.0.22.11.100)
Target: arm64-apple-macosx13.0

[Kyle-Ye]

Encounter the same issue #80