Init template cleanup

bitjammer · bitjammer · commit b574df1528e2 · 2023-02-10T17:06:58.000-08:00
Improve the `swift package init` experience using the following criteria: - Simplify the templates to include only the minimum necessary to get started without making assumptions. - Use documentation links instead of arbitrary template content to teach people about Swift. - Improve the "front door" experience with the help usage. Detailed list of changes: - Remove the `system-module` template. - Remove the `manifest` template - it's emptier than `empty` and isn't providing a lot of value on its own. Make the `empty` template only generate a manifest instead. - Remove README generation. - Don't generate empty directories. - Don't emit empty dependencies array in manifests. - Update `library` template content: - Remove struct definition, use a simple public function instead. - Include documentation links for TSPL and the Standard Library. - Include documentation links for XCTest in the generated test case. - Update `executable` template content - Use simpler top-level code instead of an `@main` struct. - Remove executable tests. - Put sources directly in `./Sources`. - Clean up and align `type` argument help text - Update Usage.md documentation - Update CHANGELOG to reflect init template changes in #6144 rdar://98999734
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,6 +17,10 @@ Swift Next
   }
   ```
 
+* [#6144]
+
+  Remove the `system-module` and `manifest` templates and clean up the remaining `empty`, `library`, and `executable` templates so they include the minimum information needed to get started, with links to documentation in the generated library, executable, and test content.
+
 
 Swift 5.9
 -----------
diff --git a/Documentation/Usage.md b/Documentation/Usage.md
@@ -158,9 +158,9 @@ initialize it as a package that builds a system module:
     example$ cd ..
     $ mkdir Clibgit
     $ cd Clibgit
-    Clibgit$ swift package init --type system-module
+    Clibgit$ swift package init --type empty
 
-This creates `Package.swift` and `module.modulemap` files in the directory.
+This creates a `Package.swift` file in the directory.
 Edit `Package.swift` and add `pkgConfig` parameter:
 
 ```swift
@@ -181,7 +181,7 @@ parameter you can pass the path of a directory containing the library using the
 
     example$ swift build -Xlinker -L/usr/local/lib/
 
-Edit `module.modulemap` so it consists of the following:
+Create a `module.modulemap` file so it consists of the following:
 
     module Clibgit [system] {
       header "/usr/local/include/git2.h"
@@ -258,10 +258,10 @@ initialize it as a package that builds a system module:
     example$ cd ..
     $ mkdir CJPEG
     $ cd CJPEG
-    CJPEG$ swift package init --type system-module
+    CJPEG$ swift package init --type empty
 
-This creates `Package.swift` and `module.modulemap` files in the directory.
-Edit `module.modulemap` so it consists of the following:
+This creates `Package.swift` file in the directory.
+Create a `module.modulemap` file so it consists of the following:
 
     module CJPEG [system] {
         header "shim.h"
diff --git a/Sources/Commands/PackageTools/Init.swift b/Sources/Commands/PackageTools/Init.swift
@@ -25,12 +25,10 @@ extension SwiftPackageTool {
         
         @Option(
             name: .customLong("type"),
-            help: ArgumentHelp("Package type: empty | library | executable | system-module | manifest", discussion: """
-                empty - Create an empty package
-                library - Create a package that contains a library
-                executable - Create a package that contains a binary executable
-                system-module - Create a package that contains a system module
-                manifest - Create a Package.swift file
+            help: ArgumentHelp("Package type:", discussion: """
+                library           - A package with a library.
+                executable        - A package with an executable.
+                empty             - An empty package with a Package.swift manifest.
                 """))
         var initMode: InitPackage.PackageType = .library
 
diff --git a/Sources/Workspace/InitPackage.swift b/Sources/Workspace/InitPackage.swift
@@ -43,8 +43,6 @@ public final class InitPackage {
         case empty = "empty"
         case library = "library"
         case executable = "executable"
-        case systemModule = "system-module"
-        case manifest = "manifest"
         case `extension` = "extension"
 
         public var description: String {
@@ -114,15 +112,8 @@ public final class InitPackage {
         // FIXME: We should form everything we want to write, then validate that
         // none of it exists, and then act.
         try writeManifestFile()
-
-        if packageType == .manifest {
-            return
-        }
-
-        try writeREADMEFile()
         try writeGitIgnore()
         try writeSources()
-        try writeModuleMap()
         try writeTests()
     }
 
@@ -177,51 +168,43 @@ public final class InitPackage {
                     """)
             }
 
-            if packageType == .library || packageType == .manifest {
+            if packageType == .library {
                 pkgParams.append("""
                     products: [
-                        // Products define the executables and libraries a package produces, and make them visible to other packages.
+                        // Products define the executables and libraries a package produces, making them visible to other packages.
                         .library(
                             name: "\(pkgname)",
                             targets: ["\(pkgname)"]),
                     ]
                 """)
             }
 
-            pkgParams.append("""
-                    dependencies: [
-                        // Dependencies declare other packages that this package depends on.
-                        // .package(url: /* package url */, from: "1.0.0"),
-                    ]
-                """)
-
-            if packageType == .library || packageType == .executable || packageType == .manifest {
+            if packageType == .library || packageType == .executable {
                 var param = ""
 
                 param += """
                     targets: [
-                        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
-                        // Targets can depend on other targets in this package, and on products in packages this package depends on.
+                        // Targets are the basic building blocks of a package, defining a module or a test suite.
+                        // Targets can depend on other targets in this package and products from dependencies.
 
                 """
                 if packageType == .executable {
                     param += """
                             .executableTarget(
+                                name: "\(pkgname)",
+                                path: "Sources"),
+                        ]
                     """
                 } else {
                     param += """
                             .target(
+                                name: "\(pkgname)"),
+                            .testTarget(
+                                name: "\(pkgname)Tests",
+                                dependencies: ["\(pkgname)"]),
+                        ]
                     """
                 }
-                param += """
-
-                            name: "\(pkgname)",
-                            dependencies: []),
-                        .testTarget(
-                            name: "\(pkgname)Tests",
-                            dependencies: ["\(pkgname)"]),
-                    ]
-                """
 
                 pkgParams.append(param)
             }
@@ -242,23 +225,10 @@ public final class InitPackage {
         )
     }
 
-    private func writeREADMEFile() throws {
-        let readme = destinationPath.appending(component: "README.md")
-        guard self.fileSystem.exists(readme) == false else {
+    private func writeGitIgnore() throws {
+        guard packageType != .empty else {
             return
         }
-
-        try writePackageFile(readme) { stream in
-            stream <<< """
-                # \(pkgname)
-
-                A description of this package.
-
-                """
-        }
-    }
-
-    private func writeGitIgnore() throws {
         let gitignore = destinationPath.appending(component: ".gitignore")
         guard self.fileSystem.exists(gitignore) == false else {
             return
@@ -281,21 +251,20 @@ public final class InitPackage {
     }
 
     private func writeSources() throws {
-        if packageType == .systemModule || packageType == .manifest {
+        if packageType == .empty {
             return
         }
+
         let sources = destinationPath.appending(component: "Sources")
         guard self.fileSystem.exists(sources) == false else {
             return
         }
         progressReporter?("Creating \(sources.relative(to: destinationPath))/")
         try makeDirectories(sources)
 
-        if packageType == .empty {
-            return
-        }
-
-        let moduleDir = sources.appending(component: "\(pkgname)")
+        let moduleDir = packageType == .executable
+          ? sources
+          : sources.appending(component: "\(pkgname)")
         try makeDirectories(moduleDir)
 
         let sourceFileName = "\(typeName).swift"
@@ -305,27 +274,19 @@ public final class InitPackage {
         switch packageType {
         case .library:
             content = """
-                public struct \(typeName) {
-                    public private(set) var text = "Hello, World!"
-
-                    public init() {
-                    }
-                }
+                // The Swift Programming Language
+                // https://docs.swift.org/swift-book
 
                 """
         case .executable:
             content = """
-                @main
-                struct \(typeName) {
-                    private(set) var text = "Hello, World!"
+                // The Swift Programming Language
+                // https://docs.swift.org/swift-book
 
-                    static func main() {
-                        print(\(typeName)().text)
-                    }
-                }
+                print("Hello, world!")
 
                 """
-        case .systemModule, .empty, .manifest, .`extension`:
+        case .empty, .`extension`:
             throw InternalError("invalid packageType \(packageType)")
         }
 
@@ -334,43 +295,18 @@ public final class InitPackage {
         }
     }
 
-    private func writeModuleMap() throws {
-        if packageType != .systemModule {
-            return
-        }
-        let modulemap = destinationPath.appending(component: "module.modulemap")
-        guard self.fileSystem.exists(modulemap) == false else {
-            return
-        }
-
-        try writePackageFile(modulemap) { stream in
-            stream <<< """
-                module \(moduleName) [system] {
-                  header "/usr/include/\(moduleName).h"
-                  link "\(moduleName)"
-                  export *
-                }
-
-                """
-        }
-    }
-
     private func writeTests() throws {
-        if packageType == .systemModule {
-            return
+        switch packageType {
+            case .empty, .executable, .`extension`: return
+            default: break
         }
         let tests = destinationPath.appending(component: "Tests")
         guard self.fileSystem.exists(tests) == false else {
             return
         }
         progressReporter?("Creating \(tests.relative(to: destinationPath))/")
         try makeDirectories(tests)
-
-        switch packageType {
-        case .systemModule, .empty, .manifest, .`extension`: break
-        case .library, .executable:
-            try writeTestFileStubs(testsPath: tests)
-        }
+        try writeTestFileStubs(testsPath: tests)
     }
 
     private func writeLibraryTestsFile(_ path: AbsolutePath) throws {
@@ -381,29 +317,11 @@ public final class InitPackage {
 
                 final class \(moduleName)Tests: XCTestCase {
                     func testExample() throws {
-                        // This is an example of a functional test case.
-                        // Use XCTAssert and related functions to verify your tests produce the correct
-                        // results.
-                        XCTAssertEqual(\(typeName)().text, "Hello, World!")
-                    }
-                }
-
-                """
-        }
-    }
+                        // XCTest Documenation
+                        // https://developer.apple.com/documentation/xctest
 
-    private func writeExecutableTestsFile(_ path: AbsolutePath) throws {
-        try writePackageFile(path) { stream in
-            stream <<< """
-                import XCTest
-                @testable import \(moduleName)
-
-                final class \(moduleName)Tests: XCTestCase {
-                    func testExample() throws {
-                        // This is an example of a functional test case.
-                        // Use XCTAssert and related functions to verify your tests produce the correct
-                        // results.
-                        XCTAssertEqual(\(typeName)().text, "Hello, World!")
+                        // Defining Test Cases and Test Methods
+                        // https://developer.apple.com/documentation/xctest/defining_test_cases_and_test_methods
                     }
                 }
 
@@ -418,11 +336,9 @@ public final class InitPackage {
 
         let testClassFile = try AbsolutePath(validating: "\(moduleName)Tests.swift", relativeTo: testModule)
         switch packageType {
-        case .systemModule, .empty, .manifest, .`extension`: break
+        case .empty, .`extension`, .executable: break
         case .library:
             try writeLibraryTestsFile(testClassFile)
-        case .executable:
-            try writeExecutableTestsFile(testClassFile)
         }
     }
 }
diff --git a/Tests/WorkspaceTests/InitTests.swift b/Tests/WorkspaceTests/InitTests.swift

Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,10 @@ Swift Next`
`17`	`17`	`}`
`18`	`18`	```
`19`	`19`
	`20`	`+* [#6144]`
	`21`	`+`
	`22`	+ Remove the `system-module` and `manifest` templates and clean up the remaining `empty`, `library`, and `executable` templates so they include the minimum information needed to get started, with links to documentation in the generated library, executable, and test content.
	`23`	`+`
`20`	`24`
`21`	`25`	`Swift 5.9`
`22`	`26`	`-----------`