Skip to content

Commit c086922

Browse files
authored
Improve docs for implementing macros in an existing Swift package (#184)
This contribution improves the documentation for getting started with macros in an existing Swift Package. Notably, it is not obvious to first-time users that `CompilerPluginSupport` needs to be imported, and the default platform support is too low to support macros (in Xcode 15 at the time of this writing). It also adds imports ahead of the `FourCharacterCode` macro implementation example, since these will be needed to make macros compile. These combined additions will smooth out the intro to macros significantly.
2 parents 15c0f7b + 5e635d4 commit c086922

File tree

1 file changed

+28
-3
lines changed

1 file changed

+28
-3
lines changed

TSPL.docc/LanguageGuide/Macros.md

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -463,10 +463,32 @@ this creates several files,
463463
including a template for a macro implementation and declaration.
464464

465465
To add macros to an existing project,
466-
add a target for the macro implementation
467-
and a target for the macro library.
466+
edit the beginning of your `Package.swift` file as follows:
467+
468+
- Set a Swift tools version of 5.9 or later in the `swift-tools-version` comment.
469+
- Import the `CompilerPluginSupport` module.
470+
- Include macOS 10.15 as a minimum deployment target in the `platforms` list.
471+
472+
The code below shows the beginning of an example `Package.swift` file.
473+
474+
```swift
475+
// swift-tools-version: 5.9
476+
477+
import PackageDescription
478+
import CompilerPluginSupport
479+
480+
let package = Package(
481+
name: "MyPackage",
482+
platforms: [ .iOS(.v17), .macOS(.v13)],
483+
// ...
484+
)
485+
```
486+
487+
Next, add a target for the macro implementation
488+
and a target for the macro library
489+
to your existing `Package.swift` file.
468490
For example,
469-
you can add something like the following to your `Package.swift` file,
491+
you can add something like the following,
470492
changing the names to match your project:
471493

472494
```swift
@@ -514,6 +536,9 @@ consider `#fourCharacterCode` from the previous section.
514536
Here's a structure that implements that macro:
515537

516538
```swift
539+
import SwiftSyntax
540+
import SwiftSyntaxMacros
541+
517542
public struct FourCharacterCode: ExpressionMacro {
518543
public static func expansion(
519544
of node: some FreestandingMacroExpansionSyntax,

0 commit comments

Comments
 (0)