From 5046cb4653676cbbfd421d436a2b32b818be6ed5 Mon Sep 17 00:00:00 2001 From: Alex Hoppen Date: Mon, 18 Sep 2023 11:34:31 -0700 Subject: [PATCH] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md hasn’t really been re-visited in a while and contained a lot of outdated information. Shorten it a little bit. --- Examples/README.md | 1 + README.md | 94 ++++++---------------------------------------- 2 files changed, 13 insertions(+), 82 deletions(-) diff --git a/Examples/README.md b/Examples/README.md index 92527118f8d..c8a8fb1657a 100644 --- a/Examples/README.md +++ b/Examples/README.md @@ -5,6 +5,7 @@ Each example can be executed by navigating into this folder and running `swift r - [AddOneToIntegerLiterals](Sources/AddOneToIntegerLiterals/AddOneToIntegerLiterals.swift): Command line tool to add 1 to every integer literal in a source file - [CodeGenerationUsingSwiftSyntaxBuilder](Sources/CodeGenerationUsingSwiftSyntaxBuilder/CodeGenerationUsingSwiftSyntaxBuilder.swift): Code-generate a simple source file using SwiftSyntaxBuilder - [ExamplePlugin](Sources/ExamplePlugin): Compiler plugin executable using [`SwiftCompilerPlugin`](../Sources/SwiftCompilerPlugin) +- [MacroExamples](Sources/MacroExamples): A collection of Swift macros Furthermore, SwiftSyntax uses [`SwiftSyntaxBuilder`](../Sources/SwiftSyntaxBuilder) extensively to generate its own code. That code can be found in the [CodeGeneration](../CodeGeneration) package. diff --git a/README.md b/README.md index e71df212c34..49ced029b96 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# SwiftSyntax +# Swift Syntax -SwiftSyntax is a set of Swift libraries for parsing, inspecting, generating, and transforming Swift source code. +The swift-syntax package is a set of libraries that work on a source-accurate tree representation of Swift source code, called the SwiftSyntax tree. The SwiftSyntax tree forms the backbone of Swift’s macro system – the macro expansion nodes are represented as SwiftSyntax nodes and a macro generates a SwiftSyntax tree to be inserted into the source file. ## Documentation @@ -8,99 +8,29 @@ You can read SwiftSyntax’s documentation on [swiftpackageindex.com](https://sw A great way to interactively explore the SwiftSyntax tree of a source file is https://swift-ast-explorer.com, developed by [@kishikawakatsumi](https://github.com/kishikawakatsumi). -## Adding SwiftSyntax as a Dependency +A set of example usages of swift-syntax can be found in [Examples](Examples). -### Trunk Development (main) +## Releases -The mainline branch of SwiftSyntax tracks the latest developments. It is not -an official release, and is subject to rapid changes in APIs and behaviors. To -use it, add this repository to the `Package.swift` manifest of your project: +Releases of SwiftSyntax are aligned with corresponding language and tooling releases, for example the major version 509 of swift-syntax is aligned with Swift 5.9. To depend on swift-syntax in a SwiftPM package, add the following to your `Package.swift`. -```swift -// swift-tools-version:5.7 -import PackageDescription - -let package = Package( - name: "MyTool", - dependencies: [ - .package(url: "https://github.com/apple/swift-syntax.git", branch: "main"), - ], - targets: [ - .target(name: "MyTool", dependencies: [ - .product(name: "SwiftSyntax", package: "swift-syntax"), - ]), - ] -) -``` - -Mainline SwiftSyntax also includes - -- `SwiftParser` for natively parsing source code -- `SwiftOperators` for folding SwiftSyntax trees containing operators -- `SwiftSyntaxBuilder` for generating Swift code with a result builder-style interface -- `SwiftSyntaxMacros` for providing syntactic macro support - -### Releases - -Releases of SwiftSyntax are aligned with corresponding language -and tooling releases and are stable. To use them, -add this repository to the `Package.swift` manifest of your project: ```swift -// swift-tools-version:5.7 -import PackageDescription - -let package = Package( - name: "MyTool", - dependencies: [ - .package(url: "https://github.com/apple/swift-syntax.git", exact: "<#Specify Release tag#>"), - ], - targets: [ - .target(name: "MyTool", dependencies: [ - .product(name: "SwiftSyntax", package: "swift-syntax"), - ]), - ] -) +dependencies: [ + .package(url: "https://github.com/apple/swift-syntax.git", from: "<#latest swift-syntax tag#>"), +], ``` + +To add swift-syntax as a dependency of your Xcode project, go to the *Package Dependencies* tab of your Xcode project, click the plus button and search for https://github.com/apple/swift-syntax.git. -Replace `<#Specify Release tag#>` by the version of SwiftSyntax that you want to use (see the following table for mapping details). - -| Xcode Release | Swift Release Tag | SwiftSyntax Release Tag | -|:-------------------:|:-------------------:|:-------------------------:| -| Xcode 14.3 | swift-5.8-RELEASE | 508.0.0 | -| Xcode 14.0 | swift-5.7-RELEASE | 0.50700.1 | -| Xcode 13.3 | swift-5.6-RELEASE | 0.50600.1 | -| Xcode 13.0 | swift-5.5-RELEASE | 0.50500.0 | -| Xcode 12.5 | swift-5.4-RELEASE | 0.50400.0 | -| Xcode 12.0 | swift-5.3-RELEASE | 0.50300.0 | -| Xcode 11.4 | swift-5.2-RELEASE | 0.50200.0 | - -## Documentation - -SwiftSyntax uses [DocC](https://developer.apple.com/documentation/docc) bundles -for its documentation. To view rendered documentation in Xcode, open the -SwiftSyntax package and select - -``` -Product > Build Documentation -``` - -Associated articles are written in markdown, and can be viewed in a browser, -text editor, or IDE. +## Reporting Issues -- [SwiftSyntax](Sources/SwiftSyntax/Documentation.docc) -- [SwiftParser](Sources/SwiftParser/SwiftParser.docc) -- [SwiftOperators](Sources/SwiftOperators/SwiftOperators.docc) -- [SwiftSyntaxMacros](Sources/SwiftSyntaxMacros/SwiftSyntaxMacros.docc) +If you should hit any issues while using SwiftSyntax, we appreciate bug reports on [GitHub Issue](https://github.com/apple/swift-syntax/issues). ## Contributing Start contributing to SwiftSyntax see [this guide](CONTRIBUTING.md) for more information. -## Reporting Issues - -If you should hit any issues while using SwiftSyntax, we appreciate bug reports on [GitHub Issue](https://github.com/apple/swift-syntax/issues). - ## Bazel SwiftSyntax provides an experimental [Bazel](https://bazel.build) build configuration, maintained by Keith Smiley.