Add support for creating a macro package (#6250)

* Add support for creating a macro package

Introduce `swift package init --type macro` to create a new
package that defines a macro. It contains:

* A macro implementation target
* A library that provides the macro declaration for use by clients
* A "client" executable that imports the library and uses the macro
* A test target for debugging the macro implementation

Note that the test target runs into linking issues because the macro
implementation target is an executable, not a library. I believe
this is a known issue.

Tracked by rdar://106468626.

* Address review feedback

Author: DougGregor

Sources/Commands/PackageTools/Init.swift

@@ -31,6 +31,7 @@ extension SwiftPackageTool {
                 tool              - A package with an executable that uses
                                     Swift Argument Parser. Use this template if you
                                     plan to have a rich set of command-line arguments.
+                macro             - A package that vends a macro.
                 empty             - An empty package with a Package.swift manifest.
                 """))
         var initMode: InitPackage.PackageType = .library

Sources/Workspace/InitPackage.swift

@@ -45,6 +45,7 @@ public final class InitPackage {
         case executable = "executable"
         case tool = "tool"
         case `extension` = "extension"
+        case macro = "macro"
 
         public var description: String {
             return rawValue
@@ -135,6 +136,16 @@ public final class InitPackage {
 
                 import PackageDescription
 
+                """
+
+            if packageType == .macro {
+                stream <<< """
+                  import CompilerPluginSupport
+
+                  """
+            }
+
+            stream <<< """
                 let package = Package(
 
                 """
@@ -144,8 +155,29 @@ public final class InitPackage {
                     name: "\(pkgname)"
                 """)
 
+            var platforms = options.platforms
+
+            // Macros require macOS 10.15, iOS 13, etc.
+            if packageType == .macro {
+                func addIfMissing(_ newPlatform: SupportedPlatform) {
+                  if platforms.contains(where: { platform in
+                      platform.platform == newPlatform.platform
+                  }) {
+                      return
+                  }
+
+                  platforms.append(newPlatform)
+                }
+
+              addIfMissing(.init(platform: .macOS, version: .init("10.15")))
+              addIfMissing(.init(platform: .iOS, version: .init("13")))
+              addIfMissing(.init(platform: .tvOS, version: .init("13")))
+              addIfMissing(.init(platform: .watchOS, version: .init("6")))
+              addIfMissing(.init(platform: .macCatalyst, version: .init("13")))
+            }
+
             var platformsParams = [String]()
-            for supportedPlatform in options.platforms {
+            for supportedPlatform in platforms {
                 let version = supportedPlatform.version
                 let platform = supportedPlatform.platform
 
@@ -165,7 +197,7 @@ public final class InitPackage {
             }
 
             // Package platforms
-            if !options.platforms.isEmpty {
+            if !platforms.isEmpty {
                 pkgParams.append("""
                         platforms: [\(platformsParams.joined(separator: ", "))]
                     """)
@@ -181,6 +213,20 @@ public final class InitPackage {
                             targets: ["\(pkgname)"]),
                     ]
                 """)
+            } else if packageType == .macro {
+                pkgParams.append("""
+                    products: [
+                        // Products define the executables and libraries a package produces, making them visible to other packages.
+                        .library(
+                            name: "\(pkgname)",
+                            targets: ["\(pkgname)"]),
+                        .executable(
+                            name: "\(pkgname)Client",
+                            targets: ["\(pkgname)Client"]
+                        ),
+                    ]
+                """)
+
             }
 
             // Package dependencies
@@ -190,6 +236,12 @@ public final class InitPackage {
                         .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.2.0"),
                     ]
                 """)
+            } else if packageType == .macro {
+                pkgParams.append("""
+                    dependencies: [
+                        .package(url: "https://github.com/apple/swift-syntax.git", branch: "main"),
+                    ]
+                """)
             }
 
             // Package targets
@@ -219,6 +271,32 @@ public final class InitPackage {
                                 path: "Sources"),
                         ]
                     """
+                } else if packageType == .macro {
+                    param += """
+                            // Macro implementation, only built for the host and never part of a client program.
+                            .macro(name: "\(pkgname)Macros",
+                                   dependencies: [
+                                     .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
+                                     .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
+                                   ]
+                            ),
+
+                            // Library that exposes a macro as part of its API, which is used in client programs.
+                            .target(name: "\(pkgname)", dependencies: ["\(pkgname)Macros"]),
+
+                            // A client of the library, which is able to use the macro in its
+                            // own code.
+                            .executableTarget(name: "\(pkgname)Client", dependencies: ["\(pkgname)"]),
+
+                            // A test target used to develop the macro implementation.
+                            .testTarget(
+                                name: "\(pkgname)Tests",
+                                dependencies: [
+                                   "\(pkgname)Macros",
+                                ]
+                            ),
+                        ]
+                    """
                 } else {
                     param += """
                             .target(
@@ -239,7 +317,8 @@ public final class InitPackage {
         // Create a tools version with current version but with patch set to zero.
         // We do this to avoid adding unnecessary constraints to patch versions, if
         // the package really needs it, they should add it manually.
-        let version = InitPackage.newPackageToolsVersion.zeroedPatch
+        let version = packageType == .macro ? ToolsVersion.vNext
+            : InitPackage.newPackageToolsVersion.zeroedPatch
 
         // Write the current tools version.
         try ToolsVersionSpecificationWriter.rewriteSpecification(
@@ -331,13 +410,33 @@ public final class InitPackage {
                 }
             }
             """
+        case .macro:
+            content = """
+            // The Swift Programming Language
+            // https://docs.swift.org/swift-book
+
+            // A macro that produces both a value and a string containing the
+            // source code that generated the value. For example,
+            //
+            //     #stringify(x + y)
+            //
+            // produces a tuple `(x + y, "x + y")`.
+            @freestanding(expression)
+            public macro stringify<T>(_ value: T) -> (T, String) = #externalMacro(module: "\(moduleName)Macros", type: "StringifyMacro")
+            """
+
         case .empty, .`extension`:
             throw InternalError("invalid packageType \(packageType)")
         }
 
         try writePackageFile(sourceFile) { stream in
             stream.write(content)
         }
+
+        if packageType == .macro {
+          try writeMacroPluginSources(sources.appending("\(pkgname)Macros"))
+          try writeMacroClientSources(sources.appending("\(pkgname)Client"))
+        }
     }
 
     private func writeTests() throws {
@@ -374,6 +473,113 @@ public final class InitPackage {
         }
     }
 
+    private func writeMacroTestsFile(_ path: AbsolutePath) throws {
+        try writePackageFile(path) { stream in
+            stream <<< ##"""
+                import SwiftSyntax
+                import SwiftSyntaxBuilder
+                import SwiftSyntaxMacros
+                import XCTest
+                import \##(moduleName)Macros
+
+                var testMacros: [String: Macro.Type] = [
+                    "stringify" : StringifyMacro.self,
+                ]
+
+                final class \##(moduleName)Tests: XCTestCase {
+                  func testMacro() {
+                    // XCTest Documentation
+                    // https://developer.apple.com/documentation/xctest
+
+                    // Test input is a source file containing uses of the macro.
+                    let sf: SourceFileSyntax =
+                      #"""
+                      let a = #stringify(x + y)
+                      let b = #stringify("Hello, \(name)")
+                      """#
+                    let context = BasicMacroExpansionContext.init(
+                      sourceFiles: [sf: .init(moduleName: "MyModule", fullFilePath: "test.swift")]
+                    )
+
+                    // Expand the macro to produce a new source file with the
+                    // result of the expansion, and ensure that it has the
+                    // expected source code.
+                    let transformedSF = sf.expand(macros: testMacros, in: context)
+                    XCTAssertEqual(
+                      transformedSF.description,
+                      #"""
+                      let a = (x + y, "x + y")
+                      let b = ("Hello, \(name)", #""Hello, \(name)""#)
+                      """#
+                    )
+                  }
+                }
+
+                """##
+        }
+    }
+
+    private func writeMacroPluginSources(_ path: AbsolutePath) throws {
+        try makeDirectories(path)
+
+        try writePackageFile(path.appending("\(moduleName)Macro.swift")) { stream in
+            stream <<< ##"""
+                import SwiftCompilerPlugin
+                import SwiftSyntax
+                import SwiftSyntaxBuilder
+                import SwiftSyntaxMacros
+
+                /// Implementation of the `stringify` macro, which takes an expression
+                /// of any type and produces a tuple containing the value of that expression
+                /// and the source code that produced the value. For example
+                ///
+                ///     #stringify(x + y)
+                ///
+                ///  will expand to
+                ///
+                ///     (x + y, "x + y")
+                public struct StringifyMacro: ExpressionMacro {
+                  public static func expansion(
+                    of node: some FreestandingMacroExpansionSyntax,
+                    in context: some MacroExpansionContext
+                  ) -> ExprSyntax {
+                    guard let argument = node.argumentList.first?.expression else {
+                      fatalError("compiler bug: the macro does not have any arguments")
+                    }
+
+                    return "(\(argument), \(literal: argument.description))"
+                  }
+                }
+
+                @main
+                struct \##(moduleName)Plugin: CompilerPlugin {
+                  let providingMacros: [Macro.Type] = [
+                    StringifyMacro.self,
+                  ]
+                }
+
+                """##
+        }
+    }
+
+    private func writeMacroClientSources(_ path: AbsolutePath) throws {
+        try makeDirectories(path)
+
+        try writePackageFile(path.appending("main.swift")) { stream in
+            stream <<< ##"""
+                import \##(moduleName)
+
+                let a = 17
+                let b = 25
+
+                let (result, code) = #stringify(a + b)
+
+                print("The value \(result) was produced by the code \"\(code)\"")
+
+                """##
+        }
+    }
+
     private func writeTestFileStubs(testsPath: AbsolutePath) throws {
         let testModule = try AbsolutePath(validating: pkgname + Target.testModuleNameSuffix, relativeTo: testsPath)
         progressReporter?("Creating \(testModule.relative(to: destinationPath))/")
@@ -384,6 +590,8 @@ public final class InitPackage {
         case .empty, .`extension`, .executable, .tool: break
         case .library:
             try writeLibraryTestsFile(testClassFile)
+        case .macro:
+            try writeMacroTestsFile(testClassFile)
         }
     }
 }