swift-gyb

Generate Swift sources and resource files from Python templates during SwiftPM builds.

Overview · Quick look · Install · Usage · Requirements · Documentation · Contributing · License

Overview

Keep repeated declarations in a template that expands with the target. GybPlugin also bundles generated resources under their own extensions; the usage guide covers Python template syntax, build conditions, and output rules.

Quick look

Place Setting.swift.gyb beside the target’s Swift files and enable GybPlugin:

public enum Setting {
% for type in ["Bool", "Int", "String"]:
  case ${type.lower()}(${type})
% end
}

Install

Add the package to Package.swift and apply GybPlugin to each target that contains templates:

dependencies: [
  .package(
    url: "https://github.com/swift-library/swift-gyb.git",
    .upToNextMinor(from: "0.2.0")
  ),
],
targets: [
  .target(
    name: "YourLibrary",
    plugins: [
      .plugin(name: "GybPlugin", package: "swift-gyb"),
    ]
  ),
]

The plugin works with library, executable, and test targets written in Swift. It skips targets in other languages.

Note

swift-gyb is pre-1.0. Minor releases may include breaking changes, so depend on it with .upToNextMinor(from:).

Usage

Apply GybPlugin to each target with templates and keep at least one ordinary Swift file in that target. The usage guide contains a complete package, generated enum, resource examples, and template syntax.

Requirements

• Swift 6.0 or later.
• Python 3, available as python3 on the build machine's PATH.
• macOS 12, iOS 15, tvOS 15, or watchOS 9 or later, or Linux. Packages with lower deployment targets can use 0.0.2.

CI builds and tests the plugin on macOS with Swift 6.0 and 6.3 and on Linux with Swift 6.2.

Documentation

• Usage guide: examples, behavior, and limits.
• gyb.py: the template engine in the Swift repository.
• Swift GYB on NSHipster: a walkthrough of gyb templates in the Swift standard library.
• Changelog

Contributing

Read CONTRIBUTING.md and the code of conduct before opening a pull request. Before submitting changes, run the same checks as CI:

Scripts/check

It runs the gyb.py self-test, swift test. The tests use Swift Testing, so swift test needs a Swift 6 toolchain. Releases follow the swift-library versioning standard.

License

swift-gyb is available under the Apache License 2.0 with the Swift Runtime Library Exception. See LICENSE.txt and NOTICE. The bundled gyb.artifactbundle/gyb.py is utils/gyb.py from the Swift project, which is distributed under the same license.