Add a version indicator macro to indicate the swift-syntax version a client is building against #2050
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
bnbarham
reviewed
Aug 11, 2023
|
|
||
| ## Detailed Explanation | ||
|
|
||
| All the ideas described in the following apply to all packages that depend on swift-syntax, not only macros. | ||
|
|
||
| For simplicity, this article assumes that `509` is the current swift-syntax version and `510` the next, but everything applies to any other major swift-syntax version update, including version jumps to `600`. | ||
| For simplicity, this article assumes that 509 is the current swift-syntax version and `510` the next, but everything applies to any other major swift-syntax version update, including version jumps to e.g. 600. |
There was a problem hiding this comment.
Inconsistent with wrapping version in `` and not. I think it's just the one 510 that is wrapped now.
|
|
||
| Any client package that depends on the macro using an `from: "1.0"` and doesn’t have any other transitive dependencies on swift-syntax will automatically receive version `1.3` of the macro when updating the package dependencies using `swift package update` or Xcode’s *Update to Latest Package Versions* command. | ||
| Since swift-syntax 510 might have introduced source-breaking changes. If the macro uses any of the APIs that have changes it needs to use conditional compilation clauses that check the version of swift-syntax it is building against. For that purpose, swift-syntax contains marker modules. All versions of swift-syntax ≥ 509 include a `SwiftSyntax509` module. Similarly, swift-syntax ≥ 510 includes a `SwiftSyntax510` and `SwiftSyntax509` module. This allows clients to write |
There was a problem hiding this comment.
Suggested change
| Since swift-syntax 510 might have introduced source-breaking changes. If the macro uses any of the APIs that have changes it needs to use conditional compilation clauses that check the version of swift-syntax it is building against. For that purpose, swift-syntax contains marker modules. All versions of swift-syntax ≥ 509 include a `SwiftSyntax509` module. Similarly, swift-syntax ≥ 510 includes a `SwiftSyntax510` and `SwiftSyntax509` module. This allows clients to write | |
| In order to handle breaking API changes, clients can wrap uses of such APIs in conditional compilation clauses that check the version of swift-syntax it is building against. Empty version modules will be used to allow such a check. All versions of swift-syntax ≥ 509 will include an empty `SwiftSyntaxVersion509` module, swift-syntax ≥ 510 will include both a `SwiftSyntaxVersion510` and `SwiftSyntaxVersion509` module, and so on for any new releases. This allows clients to write |
There was a problem hiding this comment.
Removed the Empty version modules will be used to allow such a check from your suggestion and added the following at the end instead:
The `SwiftSyntax<version>` modules are empty and don’t contain any code. Their only purpose is to serve as targets for the `canImport` checks.
ahoppen
force-pushed
the
ahoppen/version-indicator-module
branch
from
78209c1 to
38f9b2b
Compare
kimdv
approved these changes
Aug 13, 2023
|
@swift-ci Please test |
bnbarham
approved these changes
Aug 18, 2023
|
|
||
| When starting to write a macro, no special considerations need to be made with regard to versioning. Depending on swift-syntax as with `from: "509.0.0"` will make sure that the macro receives any bug fix updates to swift-syntax 509. For example, a macro depending on swift-syntax 509 might be released as version 1.0, 1.2, 2.0, … | ||
| Any given version macro can depend on multiple major swift-syntax versions at once. For example, if a macro supports both swift-syntax 509 and swift-syntax 510 may declare its dependency on swift-syntax as |
There was a problem hiding this comment.
Suggested change
| Any given version macro can depend on multiple major swift-syntax versions at once. For example, if a macro supports both swift-syntax 509 and swift-syntax 510 may declare its dependency on swift-syntax as | |
| Any given version macro can depend on multiple major swift-syntax versions at once. For example, if a macro supports both swift-syntax 509 and swift-syntax 510, it may declare its dependency on swift-syntax as |
…client is building against All swift-syntax versions ≥ 509 will include a module `SwiftSyntax509` and all swift-syntax versions ≥ 510 will include both `SwiftSyntax509` and `SwiftSyntax510`. This way clients can check which version of swift-syntax they are building against using e.g. ```swift #if canImport(SwiftSyntax510) // code specific to swift-syntax version >= 510 #else // code for swift-syntax < 510 #endif ```
ahoppen
force-pushed
the
ahoppen/version-indicator-module
branch
from
38f9b2b to
002bbbd
Compare
|
@swift-ci Please test |
|
@swift-ci Please test Windows |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
All swift-syntax versions ≥ 509 will include a module
SwiftSyntax509and all swift-syntax versions ≥ 510 will include bothSwiftSyntax509andSwiftSyntax510. This way clients can check which version of swift-syntax they are building against using e.g.