Dev1an
March 27, 2023, 9:53am
1
If you are creating an SPM package with binary targets and you execute: swift package generate-documentation I get an empty doccarchive as a result.
How can we enable docc docs for binary targets? Do we need to compile the docs when we build the xcframework and embed it in the xcframework somehow? Or can it be generated from normal xcframework? Or is there some other way? What are the best practices for documenting binaryTargets in an SPM package? Is there a way to get the versioned docs hosted on http://swiftpackageindex.com/ ?
1 Like
Kyle-Ye
October 4, 2025, 4:13pm
2
FYI, there is a known bug on SwiftPM which break the doc generation if contains a binaryTarget.
opened 10:40AM - 18 May 24 UTC
bug
### Is it reproducible with SwiftPM command-line tools: `swift build`, `swift te… st`, `swift package` etc?
- [X] Confirmed reproduction steps with SwiftPM CLI.
### Description
> Background Context: https://github.com/SwiftPackageIndex/SwiftPackageIndex-Server/issues/3061#issuecomment-2118726676
If a target has a dependency on binaryTarget. Then the call of `PackageManager.getSymbolGraph` to that target will get a directory contains no symbol graph.
It will break `PackageManager.getSymbolGraph`'s client such as swift-docc-plugin.
The downstream user can generate doc using `swift build` and call `docc convert` to generate documentation. But if they migrate to swift-docc-plugin or swift-docc-plugin based service like SwiftPackageIndex, the documentation build will fail.
```
// ✅ Build Package Documentation via Xcode GUI
// ✅ Build Package Documentation manually
swift build --target DemoKit \
-Xswiftc -emit-symbol-graph \
-Xswiftc -emit-symbol-graph-dir -Xswiftc "./symbol-graph"
docc convert --additional-symbol-graph-dir ./symbol-graph ...
// ❌ Build Package Documentation via swift-docc-plugin
swift package generate-documentation --target DemoKit
```
### Expected behavior
Produce SymbolGraph normally.
### Actual behavior
Call swift-symbolgraph-extract with the arguments manually in terminal or adding the following patch to SymbolGraphExtract.swift
```diff
public func extractSymbolGraph(
...
try process.launch()
- try process.waitUntilExit()
+ let result = try process.waitUntilExit()
+ if let error = String(bytes: try result.stderrOutput.get(), encoding: .utf8) {
+ print(error)
+. }
}
```
And you will get the following error message.
```
"<unknown>:0: error: missing required module \'MMKV\'\nError: Failed to load the module \'DemoKit\'. Are you missing build dependencies or include/framework directories?\nSee the previous error messages for details. Aborting.\n"
```
I have tried to add the framework manually via `-F`/`-I`/`-L ${MMKV_framework_path}` but none of them will work.
### Steps to reproduce
For user side reproduce steps:
1. Download the following DemoKit.zip package
2. Run `swift package generate-documentation --target DemoKit --verbose` and no documentation will be created.
For swiftpm developer reproduce steps:
1. Set up swiftpm repo development environment
2. Build PackageDescription target first and then choose `swift-package` target
3. Set working directory to `DemoKit` and the corresponding arguments on launch in Xcode
4.(Optional) Apply the diff mentioned above.
[DemoKit.zip](https://github.com/apple/swift-package-manager/files/15362819/DemoKit.zip)
> Note: Here I use MMKV.xcframework as an example but any binary framework would have the same issue. The binary framework have nothing special here.
### Swift Package Manager version/commit hash
5.10
### Swift & OS version (output of `swift --version ; uname -a`)
5.10 & macOS 14.4.1
1 Like