[nac5504]

Adds SOAR-0017 proposing an advanced, opt-in output.maxDeclarationsPerFile control for splitting large generated namespaces into smaller Swift files.

Includes benchmark results, build-tool plugin considerations, and a fixed file-count alternative. Adds the proposal to the documentation index.

Related discussions: #866, #925, #930.

This PR only adds the proposal; implementation is separate.

Tracking issue: #974.

[czechboy0]

Hi @nac5504,

thanks for the proposal, however I think this is an important callout:

Supporting this option in the build-tool plugin would require a prebuild command or another mechanism for discovering dynamic outputs and is deferred to separate work.

I don't think we'd realistically accept this PR if we can't support the feature in a build plugin.

I'd consider this proposal/change blocked on first considering the move to a prebuild plugin. @simonjbeaumont, thoughts?

[czechboy0]

See comment above, let's discuss the build/prebuild plugin first.

[simonjbeaumont]

I don't think we'd realistically accept this PR if we can't support the feature in a build plugin.

I'd consider this proposal/change blocked on first considering the move to a prebuild plugin. @simonjbeaumont, thoughts?

I agree with the second of these statements. I expect this change will require us to move to a prebuild plugin but I'm not personally opposed to that.

I do agree it would be good to make that change independently, first, though.

[czechboy0]

Sorry, that's what I meant.

That we wouldn't accept a change that doesn't work in the plugin, only on the CLI.

[nac5504]

Thank you both for the feedback!

Would you be open to using a prebuild command conditionally when output.maxDeclarationsPerFile is configured, and keep the existing build command otherwise? Something to this effect:

if config.maxDeclarationsPerFile != nil {
    return [.prebuildCommand(
        // Discover a variable set of generated files.
    )]
} else {
    return [.buildCommand(
        // Declare the known output files.
    )]
}

That would support dynamic outputs for declaration splitting while preserving the current incremental-build behavior for users with the default configuration.

[czechboy0]

I'd prefer for us to keep it simple. If we feel that moving from a build to prebuild plugin is the right call, we should make that change across the board. Creating new configuration states that require additional qualification etc should be avoided unless really necessary.

[nac5504]

I'd prefer for us to keep it simple. If we feel that moving from a build to prebuild plugin is the right call, we should make that change across the board. Creating new configuration states that require additional qualification etc should be avoided unless really necessary.

I agree that keeping a single config state is the best way forward, but I'm not yet convinced that moving everything to prebuild commands is the right call. I'm weighing this proposed declaration-based approach, which is only compatible with prebuild commands, against an explicit file-count approach that would work with regular build commands. How do you both see this choice affecting future features, including some already planned perhaps? Would dynamic-output support be a useful foundation to establish now?

My main concern is incremental-build performance. Prebuild commands run on every build, even when inputs are unchanged or declaration splitting is disabled. We'd need caching and careful output handling to avoid adding generation or compilation work that offsets the gains the proposal aims to achieve. An explicit file count config could offer comparable compilation benefits while retaining SwiftPM’s existing dependency tracking. The tradeoff is potentially more involved configuration, such as separate file counts for each Types namespace to accommodate their different sizes, which users may need to adjust as their API grows.

[czechboy0]

Anything config driven would require the plugin to read the config file, which it doesn't today. It only constructs the CLI invocation and the CLI is the one reading the config file.