Templates

Documentation/Usage.md

@@ -8,6 +8,7 @@
     * [Creating a Library Package](#creating-a-library-package)
     * [Creating an Executable Package](#creating-an-executable-package)
     * [Creating a Macro Package](#creating-a-macro-package)
+    * [Creating a Package based on a custom user-defined template](#creating-a-package-based-on-a-custom-user-defined-template)
   * [Defining Dependencies](#defining-dependencies)
   * [Publishing a Package](#publishing-a-package)
   * [Requiring System Libraries](#requiring-system-libraries)
@@ -88,6 +89,79 @@ Evolution proposal for [Expression Macros](https://github.com/swiftlang/swift-ev
 and the WWDC [Write Swift macros](https://developer.apple.com/videos/play/wwdc2023/10166) 
 video. See further documentation on macros in [The Swift Programming Language](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/macros/) book.
 
+
+### Creating a Package based on a custom user-defined template
+
+SwiftPM can create packages based on custom user-defined templates distributed as Swift packages. These templates can be obtained from local directories, Git repositories, or package registries, and provide interactive configuration through command-line arguments.
+To create a package from a custom template, use the `swift package init` command with the `--type` option along with a template source:
+
+```bash
+# From a package registry
+$ swift package init --type MyTemplate --package-id author.template-example
+
+# From a Git repository
+$ swift package init --type MyTemplate --url https://github.com/author/template-example
+
+# From a local directory
+$ swift package init --type MyTemplate --path /path/to/template
+```
+
+The template will prompt you for configuration options during initialization:
+
+```bash
+$ swift package init --type ServerTemplate --package-id example.server-templates
+Building template package...
+Build of product 'ServerTemplate' complete! (3.2s)
+
+Add a README.md file with an introduction and tour of the code: [y/N] y
+
+Choose from the following:
+
+• Name: crud
+  About: Generate CRUD server with database support
+• Name: bare  
+  About: Generate a minimal server
+
+Type the name of the option:
+crud
+
+Pick a database system for data storage. [sqlite3, postgresql] (default: sqlite3):
+postgresql
+
+Building for debugging...
+Build of product 'ServerTemplate' complete! (1.1s)
+```
+
+Templates support the same versioning options as regular Swift package dependencies:
+
+```bash
+# Specific version
+$ swift package init --type MyTemplate --package-id author.template --exact 1.2.0
+
+# Version range
+$ swift package init --type MyTemplate --package-id author.template --from 1.0.0
+
+# Specific branch
+$ swift package init --type MyTemplate --url https://github.com/author/template --branch main
+
+# Specific revision
+$ swift package init --type MyTemplate --url https://github.com/author/template --revision abc123
+```
+
+You can provide template arguments directly to skip interactive prompts:
+
+```bash
+$ swift package init --type ServerTemplate --package-id example.server-templates crud --database postgresql --readme true
+```
+
+Use the `--build-package` flag to automatically build and validate the generated package:
+
+```bash
+$ swift package init --type MyTemplate --package-id author.template --build-package
+```
+
+This ensures your template generates valid, buildable Swift packages.
+
 ## Defining Dependencies
 
 To depend on a package, define the dependency and the version in the manifest of

Examples/init-templates/Package.swift

@@ -0,0 +1,69 @@
+// swift-tools-version:6.3.0
+import PackageDescription
+
+let testTargets: [Target] = [.testTarget(
+    name: "ServerTemplateTests",
+    dependencies: [
+        "ServerTemplate",
+    ]
+)]
+
+let package = Package(
+    name: "SimpleTemplateExample",
+    products:
+    .template(name: "PartsService") +
+        .template(name: "Template1") +
+        .template(name: "Template2") +
+        .template(name: "ServerTemplate"),
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-argument-parser", branch: "main"),
+        .package(url: "https://github.com/apple/swift-system.git", from: "1.4.2"),
+        .package(url: "https://github.com/stencilproject/Stencil.git", from: "0.15.1"),
+    ],
+    targets: testTargets + .template(
+        name: "PartsService",
+        dependencies: [
+            .product(name: "ArgumentParser", package: "swift-argument-parser"),
+            .product(name: "SystemPackage", package: "swift-system"),
+        ],
+
+        initialPackageType: .executable,
+        description: "This template generates a simple parts management service using Hummingbird, and Fluent!"
+
+    ) + .template(
+        name: "Template1",
+        dependencies: [
+            .product(name: "ArgumentParser", package: "swift-argument-parser"),
+            .product(name: "SystemPackage", package: "swift-system"),
+        ],
+
+        initialPackageType: .executable,
+        templatePermissions: [
+            .allowNetworkConnections(scope: .none, reason: "Need network access to help generate a template"),
+        ],
+        description: "This is a simple template that uses Swift string interpolation."
+
+    ) + .template(
+        name: "Template2",
+        dependencies: [
+            .product(name: "ArgumentParser", package: "swift-argument-parser"),
+            .product(name: "SystemPackage", package: "swift-system"),
+            .product(name: "Stencil", package: "Stencil"),
+
+        ],
+        resources: [
+            .process("StencilTemplates"),
+        ],
+        initialPackageType: .executable,
+        description: "This is a template that uses Stencil templating."
+
+    ) + .template(
+        name: "ServerTemplate",
+        dependencies: [
+            .product(name: "ArgumentParser", package: "swift-argument-parser"),
+            .product(name: "SystemPackage", package: "swift-system"),
+        ],
+        initialPackageType: .executable,
+        description: "A set of starter Swift Server projects."
+    )
+)

Examples/init-templates/Plugins/PartsServicePlugin/PartsServicePlugin.swift

@@ -0,0 +1,24 @@
+import Foundation
+
+import PackagePlugin
+
+/// plugin that will kickstart the template executable
+@main
+struct PartsServiceTemplatePlugin: CommandPlugin {
+    func performCommand(
+        context: PluginContext,
+        arguments: [String]
+    ) async throws {
+        let tool = try context.tool(named: "PartsService")
+        let packageDirectory = context.package.directoryURL.path
+        let packageName = context.package.displayName
+
+        let process = Process()
+
+        process.executableURL = URL(filePath: tool.url.path())
+        process.arguments = ["--pkg-dir", packageDirectory, "--name", packageName] + arguments.filter { $0 != "--" }
+
+        try process.run()
+        process.waitUntilExit()
+    }
+}

Examples/init-templates/Plugins/ServerTemplatePlugin/ServerTemplatePlugin.swift

@@ -0,0 +1,51 @@
+import Foundation
+
+import PackagePlugin
+
+/// plugin that will kickstart the template executable
+@main
+struct ServerTemplatePlugin: CommandPlugin {
+    func performCommand(
+        context: PluginContext,
+        arguments: [String]
+    ) async throws {
+        let tool = try context.tool(named: "ServerTemplate")
+        let packageDirectory = context.package.directoryURL.path
+
+        let process = Process()
+
+        let stderrPipe = Pipe()
+
+        process.executableURL = URL(filePath: tool.url.path())
+        process.arguments = ["--pkg-dir", packageDirectory] + arguments.filter { $0 != "--" }
+        process.standardError = stderrPipe
+
+        try process.run()
+        process.waitUntilExit()
+
+        let stderrData = stderrPipe.fileHandleForReading.readDataToEndOfFile()
+        let stderrOutput = String(data: stderrData, encoding: .utf8) ?? ""
+
+        if process.terminationStatus != 0 {
+            throw PluginError.executionFailed(code: process.terminationStatus, stderrOutput: stderrOutput)
+        }
+    }
+
+    enum PluginError: Error, CustomStringConvertible {
+        case executionFailed(code: Int32, stderrOutput: String)
+
+        var description: String {
+            switch self {
+            case .executionFailed(let code, let stderrOutput):
+                """
+
+                Plugin subprocess failed with exit code \(code).
+
+                Output:
+                \(stderrOutput)
+
+                """
+            }
+        }
+    }
+}

Examples/init-templates/Plugins/Template1Plugin/Template1Plugin.swift

@@ -0,0 +1,54 @@
+//
+//  plugin.swift
+//  TemplateWorkflow
+//
+//  Created by John Bute on 2025-04-14.
+//
+import Foundation
+
+import PackagePlugin
+
+/// plugin that will kickstart the template executable
+@main
+struct TemplatePlugin: CommandPlugin {
+    func performCommand(
+        context: PluginContext,
+        arguments: [String]
+    ) async throws {
+        let tool = try context.tool(named: "Template1")
+        let packageDirectory = context.package.directoryURL.path
+        let process = Process()
+        let stderrPipe = Pipe()
+
+        process.executableURL = URL(filePath: tool.url.path())
+        process.arguments = ["--pkg-dir", packageDirectory] + arguments.filter { $0 != "--" }
+        process.standardError = stderrPipe
+
+        try process.run()
+        process.waitUntilExit()
+        let stderrData = stderrPipe.fileHandleForReading.readDataToEndOfFile()
+        let stderrOutput = String(data: stderrData, encoding: .utf8) ?? ""
+
+        if process.terminationStatus != 0 {
+            throw PluginError.executionFailed(code: process.terminationStatus, stderrOutput: stderrOutput)
+        }
+    }
+
+    enum PluginError: Error, CustomStringConvertible {
+        case executionFailed(code: Int32, stderrOutput: String)
+
+        var description: String {
+            switch self {
+            case .executionFailed(let code, let stderrOutput):
+                """
+
+                Plugin subprocess failed with exit code \(code).
+
+                Output:
+                \(stderrOutput)
+
+                """
+            }
+        }
+    }
+}

Examples/init-templates/Plugins/Template2Plugin/Template2Plugin.swift

@@ -0,0 +1,34 @@
+//
+//  Template2Plugin.swift
+//  TemplateWorkflow
+//
+//  Created by John Bute on 2025-04-23.
+//
+
+//
+//  plugin.swift
+//  TemplateWorkflow
+//
+//  Created by John Bute on 2025-04-14.
+//
+import Foundation
+
+import PackagePlugin
+
+/// plugin that will kickstart the template executable
+@main
+struct DeclarativeTemplatePlugin: CommandPlugin {
+    func performCommand(
+        context: PluginContext,
+        arguments: [String]
+    ) async throws {
+        let tool = try context.tool(named: "Template2")
+        let process = Process()
+
+        process.executableURL = URL(filePath: tool.url.path())
+        process.arguments = arguments.filter { $0 != "--" }
+
+        try process.run()
+        process.waitUntilExit()
+    }
+}

Examples/init-templates/README.md

@@ -0,0 +1,21 @@
+# Swift package templating example
+
+---
+
+This template project is a simple example of how a template author can create a template and generate a swift projects, utilizing the `swift package init` capability in swift package manager (to come).
+
+## Parts Service
+
+The parts service template can generate a REST service using Hummingbird (app server), and Fluent (ORM) with configurable database management system (SQLite3, and PostgreSQL). There are various switches to customize your project.
+
+Invoke the parts service generator like this:
+
+```
+swift run parts-service --pkg-dir <new_package_dir>
+```
+
+You can find the additional information and parameters by invoking the help:
+
+```
+swift run parts-service --help
+```