Minimize unneeded tool inclusions in SwiftSyntax's SwiftPM distribution

[Matejkob]

With the introduction of Swift Macros in Swift 5.9, there is an anticipated increase in the use of the SwiftSyntax repository. As developers adopt Swift Macros, it's crucial to ensure that they get a streamlined experience when adding and using SwiftSyntax as a dependency.

Currently, when users add SwiftSyntax as a dependency, they not only get the main source code and unit tests but also tools and utilities used for the repository's maintenance such as cmake, EditorExtension, lit_tests, utils, and format.py (I'm fully sure if all of them are unneeded - pleas correct me if I'm wrong, or maybe we have some more which actually are not needed and haven't been mentioned above).

For many end-users, these additional tools and utilities are unnecessary and may cause confusion or add unwanted clutter. A potential solution to this is to create an empty SwiftPM manifest file in each of these directories, forcing the main package to ignore them.

This restructuring will make the repository cleaner for developers who are only interested in the core functionality of SwiftSyntax and not its maintenance tools.

[ahoppen]

Tracked in Apple’s issue tracker as rdar://114373445

[ahoppen]

I don’t think it’s uncommon for repositories to have helper scripts that are intended for development purposes and not needed for the actual clients. So, I don’t have a huge issue with the existence of these directories, especially because users of SwiftPM know that the actual sources they are compiling live in the Sources directory.

To give some context here’s why the directories that you mentioned, need to exist

• cmake: This allows building swift-syntax using CMake, which is needed to build it as part of the compiler itself
• EditorExtension: See the readme in there, allows iterating on the syntactic refactorings in the SwiftRefactor model. It’s just very convenient to test the SwiftRefactor actions
• lit_tests: This one is actually going away
• utils: Allows building swift-syntax using Bazel for swift-syntax clients that build using that build system
• format.py: Well this is needed to format the sources of swift-syntax during development and I don’t know where else it should live

A potential solution to this is to create an empty SwiftPM manifest file in each of these directories, forcing the main package to ignore them.

How would an empty package manifest in these directories help?

[Matejkob]

Oh yeah, it's definitely common to see such scripts.

When Xcode detects that a directory has its own package manifest, it excludes that directory from the main package. To the best of my knowledge, this is the only method to exclude directories (other than renaming them to start with .) from appearing in the main package. I've used this workaround in several frameworks, and I've observed its frequent use in the Swift community, for instance, in the TCA repo.

We would change:

to this:

But if you find it unneeded I totally get you! ❤️

[ahoppen]

I don’t like that approach. These folders aren’t packages and the workaround only applies to Xcode, i.e. you would still see the folders when using Visual Studio Code. Also, it only hides the folders and not the other files like build-script.py or BUILD.bazel.

[Matejkob]

Gotcha! Thanks for pointing that out. I totally see where you're coming from. I'll close this issue for now. Appreciate the heads-up!