[SE-0301] Updating a project and its manifest programmatically and from the command line

[DougGregor]

Package manifest files are Swift source code, so editing them means working with the source code directly. Introduce a new library PackageModelSyntax based on swift-syntax that allows us to perform targeted manipulations of the manifest file programmatically, making suggested edits to the file without having to understand everything in it.

Introduce two editing commands:

• addPackageDependency: adds a new package dependency to the manifest file, e.g.,

   .package(url: "https://github.com/apple/swift-syntax.git", from: "510.0.1"),

• addTarget: adds a new target to the manifest file, e.g.,

   .executableTarget(
    name: "MyProgram",
    dependencies: [ "MyLib" ]
  )

In both cases, this is handled as a limited transform on the swift-syntax tree that then produces a series of edits that update the package manifest. We don't make any attempts to reason about the whole package, so this doesn't require any round-tripping with a semantic model. The editing commands can also introduce new files into the package. For example, adding target will create a new source file Sources/\(targetName)/\(targetName).swift with contents appropriate for the target type (struct for a library, @main for an executable, macro implementation struct for a macro target, etc.).

These editing operations are surfaced by implementing two of the commands from SE-0301 "Package Editing Commands", swift package add-dependency and swift package add-target. Adding a dependency looks a bit like this:

swift package add-dependency --from 510.0.1 https://github.com/apple/swift-syntax.git

and will produce the .package(...) example above and insert it into the appropriate place in the manifest.

Adding a target looks like this:

swift package add-target MyProgram --type executable --dependencies MyLib OtherLib

and adds this target to the manifest

.executableTarget(
    name: "MyProgram",
    dependencies: [
        "MyLib",
        "OtherLib"
    ]
),

as well as Sources/MyProgram/MyProgram.swift:

import MyLib
import OtherLib

@main
struct MyProgramMain {
    static func main() {
        print("Hello, world")
    }
}

[MaxDesiatov]

@swift-ci test

[ahoppen]

We do actually have a utility to infer indentation in swift-syntax: https://github.com/apple/swift-syntax/blob/728e2f6d5f9fd4a8e45eab6e52e86ad1519a7e2a/Sources/SwiftBasicFormat/InferIndentation.swift#L19-L27

[DougGregor]

Oh, huh. Should I be worried that this is processing the entire file? I suppose I should thread through an optional indentation value if we're going to do that.

[ahoppen]

I don’t think it should be a huge deal if the user actually invokes swift package add and better than just using 4 spaces which does tend to look stupid if the rest of the file is indented with 2 spaces.

[ahoppen]

Wouldn’t it make more sense for this to be an instance function on SyntaxProtocol instead of a static function?

[DougGregor]

No, because you are looking for something of the Self type.

[ahoppen]

I was thinking if it is a cleaner API to have it be like

tree.findFirst { (node: FunctionCallSyntax) -> Bool in
  doChecks(for: node)
}

Instead of

FunctionCallSyntax.findFirst(in: tree) { node in
  doChecks(for: node)
}

which reads a little backwards to me. But maybe it’s a matter of taste.

[DougGregor]

I hate requiring type annotations on closures... but I can create an ofType argument or similar to make this cleaner.

[DougGregor]

This is in decent shape except that the bootstrap script is totally broken.

[DougGregor]

@swift-ci please test

[DougGregor]

@swift-ci please test macOS

[DougGregor]

@swift-ci please test Windows

[DougGregor]

@swift-ci please test macOS

[DougGregor]

@swift-ci please test

[DougGregor]

@swift-ci please test Windows

[owenv]

If we ship the abi.json file for PackageDescription in the toolchain, that might work

[DougGregor]

If we're going to look there, we might as well just parse the PackageDescription module sources, since we have swift-syntax around.

[MaxDesiatov]

@swift-ci test windows

[DougGregor]

@swift-ci please test

[DougGregor]

@swift-ci please test macOS

[DougGregor]

@swift-ci please test Windows

[DougGregor]

@swift-ci please test

[DougGregor]

@swift-ci please test