[Pitch] The idea of built-in or default-available plugins for SwiftPM

Evolution Pitches
, ,
1

I'd like to discuss options on how to approach, and what would be acceptable, to enable some concept of "default available plugins" for the broader swift ecosystem.

The inception for this is from Documentation, specifically the docc-plugin that provides a plugin to conveniently build, or preview, documentation. Today if you want to use this, you need to explicitly add the dependency to each individual Swift package. While that's not a terrible burden, it's more friction than I'd personally like to see.

In an ideal scenario in my head, once you have a swift toolchain installed, I'd like to be able to have the docc plugin automatically loaded and available for any of my projects, without having to add the explicit dependency, so that as I'm fiddling with a new or existing project, I can easily invoke swift package preview-documentation and have get the preview immediately.

Perhaps there's a concept of a cached and readily available plugin that can be seeded on a local machine, and that don't need to be recompiled on every pass, that might be available.

The same pattern would be exceptionally useful for other tools that I used across several packages, such as formatting. There seems to be some initial precedent for this in the built-in command: swift package diagnose-api-breaking-changes, which is also exceptionally useful (and perhaps still considered experimental?)

All this said, I don't fully understand the constraints and where/how I could establish an active experiment for consideration, or discuss the what's acceptable/unacceptable within the existing constraints to assemble a contribution to make this happen.

11 Likes
[Pitch] Documentation generation for any SwiftPM package
2

Or maybe just systemwide packages with maybe a ‘.swiftconfig’ file to store the developer preferences?

2 Likes
3

i think a separate .swiftconfig (or perhaps .swiftpm) file is an excellent idea. among other benefits, it could be gitignored, which would avoid having to pivot around local modifications to the Package.swift.

i’m less enthusiastic about making swift-docc-plugin universally enabled everywhere, but i can appreciate how that might be an easier step implementation-wise.

2 Likes
4

A challenge with this is that it makes packages less portable. e.g. some company builds their own dev environment, splatted automatically to all their employee's machines, which includes these "default" plug-ins, which the employees now unwittingly rely on and thus produce packages which can't be reliably built anywhere else.

It's the sort of thing that's very easy to miss when sharing packages outside of the organisation (whether open source or with other organisations / people) because it works on your machine, and your colleagues' machines.

Sure, it's "easy" to fix this with a patch after the fact, but it's still at least an annoyance.

One of the things I like about the Swift package ecosystem is that mostly it just works - I add a dependency in my own project and I'm good to go. Contrast that to a lot of other languages and build systems where you have to followed long instructions on how to manually build and install dependencies, configure your environment "correctly", etc.

(it's a similar mentality behind build systems like Blaze (a la Bazel) which trade off 'capability' for reproducibility)

1 Like
5

i think this is getting a bit ahead of the conceived use case, which is to allow people developing a package to use swift-docc-plugin without fighting the version control in Package.swift. swift-docc-plugin isn’t required to build a package (or even its documentation!), and i think that a package that is overly reliant on package plugins to compile successfully is not that different from packages that are overly reliant on things like system dependencies.

1 Like
6

I'm think I'm missing the thinking on how this could make a package less portable. The idea I'm after is making it so that you have some swiftpm plugin commands automatically available, potentially ones that aren't "built into the toolchain" from a starting point.

The one-liner is

I wish I could type "swift package preview-documentation" right after cloning someone's package, and have that work without the Package.swift having an explicit dependency on swift-docc-plugin.

In case you're thinking I'm talking about the "I need this to compile the package dependencies", that's not my intent here. As it stands in the manifest of Package.swift, there isn't really a concept of the kind of dependency, and maybe that's part of the issue that I'm trying to detangle?

1 Like
Default behavior of "swift format"
7

Both default and installable plugins were on my short list (which was actually a pretty long list) of things we'll need in SwiftPM one day.

The docc-plugin was a good attempt at avoiding to constantly add more functionality to the SwiftPM project, but ultimately it's a bit half-baked without the concept of default plugins. diagnose-api-breaking-changes is a good example for something that's currently built-in but suffers from it since it isn't part of the core functionality but could potentially more easily attract contributors as a plugin.

I think there should also be a concept of installable plugins since there's also room for functionality that isn't default but still something that needs to be available independently of any particular package. My favorite example for this were extensible package templates were 3rd party templates would be plugins.

4 Likes
8

Ah, I apologise, I misunderstood.

1 Like