Proposal: Improving SPIManifest, Documentation, Diagnostics, and Discoverability

[maximkrouk]

The current documentation for SPIManifest is very minimal. While this keeps the surface area small, it also makes it difficult to understand best practices, trade-offs, and intended usage patterns, especially for more complex packages.

I recently added .spi.yml manifests to several of my packages and found the process more frustrating than expected. Richer examples, clearer guidance, and additional elaboration on certain features would significantly improve the experience.

Below are some concrete issues and suggestions

Background & Examples

For reference, here are two packages with different .spi.yml configurations:

Example 1 (multiplatform docs):

capturecontext/cocoa-aliases

• SPI page
• Naive SPI manifest
• Updated SPI manifest

version: 1
builder:
  configs:
  - platform: ios
    documentation_targets:
      - CocoaAliases

  - platform: macos-xcodebuild
  - platform: macos-spm
    documentation_targets:
      - CocoaAliases

  - platform: tvos
    documentation_targets:
      - CocoaAliases

  - platform: watchos
    documentation_targets:
      - CocoaAliases

  - platform: visionOS
    documentation_targets:
      - CocoaAliases

Example 2 (multitarget docs):

capturecontext/swift-keypaths-extensions

• SPI page
• Naive SPI manifest
• Updated SPI manifest

version: 1
builder:
  configs:
  - platform: ios
  - platform: macos-spm
  - platform: macos-xcodebuild
  - platform: tvos
  - platform: watchos
  
  - platform: linux
    swift_version: '5.9'

  - platform: linux
    swift_version: '6.0'

  - documentation_targets:
    - KeyPathsExtensions
    - KeyPathMapper

Issue 1: Scheme Selection Is Central but Poorly Observable

The documentation correctly explains that builder.configs are used to guide the build system, including scheme selection:

“Sometimes a build can fail even though a package is compatible, because we choose the wrong scheme.”

However, in practice, scheme selection is both critical and opaque.

Problems

• When a build fails due to an incorrect or missing scheme:
  • the generated spi-builder-workspace is not visible
  • available schemes are not printed
  • As a result, authors often resort to trial-and-error edits to .spi.yml without knowing which schemes SPI actually sees, given high queue times can take a while to figure it out.
• If custom schemes are the same current configuration can introduce a bunch of boilerplate

Suggestions

• Improve failure diagnostics by:
  • including xcodebuild -list output in build logs
  • explicitly documenting how schemes are discovered
• Add builder.default_scheme entry, which will be used for builder.config entries when custom scheme is not specified

Issue 2: macos-spm vs macos-xcodebuild

The documentation distinguishes between macos-spm and macos-xcodebuild, which can be useful, but can also be too verbose and frustrating given that afaiu there is no mention of default behavior in docs:

"This will generate documentation on the default platform, which is macOS"

"If your package is not compatible with macOS, you can specify which platform to generate documentation on"

Problems:

• It's not clear:
  • if macos-xcodebuild needed when macos-spm is already included.
  • if declaring all available platforms is good (explicit) or bad (redundantly loads build system)

Note

Writing the proposal made me reflect on SPI manifests, so for me now it looks like it's ok to specify all available platforms, (spi tries to build everything anyway), however it's required only if one needs a custom scheme or docs for specific platform

Suggestions

• Add macos option, that will:
  • share the scheme for macos-spm and macos-xcodebuild
  • use spi-default option for docs

Note

It's currently possible to achieve this behavior by explicitly defining macos-spm and macos-xcodebuild platforms (or even omitting them if a custom scheme is not needed) and documentation_targets with no platform, however it would be nice to have a medium-verbose option

Issue 3: Multi-Target Documentation Has Poor Discoverability

The documentation explains that:

“Targets will appear in the order listed in the selector dropdown … the first target will be the landing page target.”

While technically correct, this interaction is not discoverable in practice.

In multi-target packages (e.g. swift-keypaths-extensions), secondary documentation targets are effectively hidden unless the user already knows to hover over the module name in the header.

Suggestions

• I'm not sure if it's a DocC limitation, but Apple docs do allow to navigate frameworks in their docs via sidebar
• If it is a DocC limitation, a dedicated landing page with enumerated documentation targets for multitarget packages would be nice

[maximkrouk]

Update

Issue 3 seems to be addressed here #3871

[maximkrouk]

Addition

• Add xcbeautify-processed build logs as an addition to raw xcodebuild output 💅
• Also, it would be cool if there was a guide how to bootstrap the same environment for local builds 🤔