diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0de218a0e5e..e28dd3800d8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,6 +63,22 @@ Tip: Running SwiftSyntax’s self-parse tests takes the majority of testing time 2. Select the Arguments tab in the Run section 3. Add a `SKIP_LONG_TESTS` environment variable with value `1` +### Additional Verification + +swift-syntax has two additional verification methods (see the two sections below) that provide more extensive validation. They have significant runtime impact on swift-syntax and are thus not enabled by default when building swift-syntax, but are enabled in CI. If CI fails and you are unable to reproduce the failure locally, make sure that `SKIP_LONG_TESTS` is not set and try enabling these validations. + +#### RawSyntax Validation + +When the `SWIFTSYNTAX_ENABLE_RAWSYNTAX_VALIDATION` environment variable is set while building swift-syntax (or the check for that variable has been changed to always return `true` in Package.swift), SwiftSyntax will perform additional validation that the layout of the syntax tree is correct. It validates that every child of a syntax node has the correct kind (which should be guaranteed by the Swift type system in most cases) and, more importantly, validates that each token only has one of the token kinds that is specified in the syntax tree layout of the `CodeGeneration` package. + +If this validation hits an assertion failure that a token is not accepted at a certain position in the syntax tree, double check if the token kind that is being stored in the syntax tree actually makes sense here. If it does not, check if there is a parser bug or whether you need to remap the token kind. If it does make sense, add the token kind to `.token(choices:)` of the syntax node in CodeGeneration, re-generate that source code and run tests again. + +#### Test Case Mutation + +When the `SWIFTPARSER_ENABLE_ALTERNATE_TOKEN_INTROSPECTION` environment variable is set while building swift-syntax (or the check for that variable has been changed to always return `true` in Package.swift), SwiftParser records alternative tokens that the parser was looking for at specific offsets in the source file (e.g. whether it also checked for a `struct` keyword when the source code contained a `class` keyword). It will then use that information to mutate the test case by e.g. substituting `class` by `struct`. + +When testing finds one of these failures, it will show you the syntax tree that produced the failure. Create a new test case with the source code the failure gives you and fix the failure. + ### `lit`-based Tests A few tests are based LLVM’s `lit` and `FileCheck` tools. diff --git a/CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndex.swift b/CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndex.swift index ba49c47c40c..89040006c58 100644 --- a/CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndex.swift +++ b/CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndex.swift @@ -67,9 +67,40 @@ let nodesSections: String = { return result }() +var contributingDocs: String = { + let contributingDocsFolder = URL(fileURLWithPath: #filePath) + .deletingLastPathComponent() + .deletingLastPathComponent() + .deletingLastPathComponent() + .deletingLastPathComponent() + .deletingLastPathComponent() + .deletingLastPathComponent() + .appendingPathComponent("Sources") + .appendingPathComponent("SwiftSyntax") + .appendingPathComponent("Documentation.docc") + .appendingPathComponent("Contributing") + + let files = (try? FileManager.default.contentsOfDirectory(at: contributingDocsFolder, includingPropertiesForKeys: nil)) ?? [] + + return files.compactMap { file in + if file.pathExtension != "md" { + return nil + } + let doccName = file.lastPathComponent + .replacingOccurrences(of: ".md", with: "") + .replacingOccurrences(of: " ", with: "-") + return "- " + }.sorted().joined(separator: "\n") +}() + let swiftSyntaxDoccIndex: String = { - let templateURL = URL(fileURLWithPath: #filePath).deletingLastPathComponent().appendingPathComponent("SwiftSyntaxDoccIndexTemplate.md") + let templateURL = URL(fileURLWithPath: #filePath) + .deletingLastPathComponent() + .appendingPathComponent("SwiftSyntaxDoccIndexTemplate.md") let template = try! String(contentsOf: templateURL) - return template.replacingOccurrences(of: "{{Nodes}}", with: nodesSections) + return + template + .replacingOccurrences(of: "{{Nodes}}", with: nodesSections) + .replacingOccurrences(of: "{{ContributingDocs}}", with: contributingDocs) }() diff --git a/CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndexTemplate.md b/CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndexTemplate.md index 13c3b4b127b..5d92a905bcd 100644 --- a/CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndexTemplate.md +++ b/CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndexTemplate.md @@ -17,13 +17,17 @@ allows Swift tools to parse, inspect, generate, and transform Swift source code. ### Articles - -- -- ### Tutorials - +### Contributing + +These articles are intended for developers wishing to contribute to SwiftSyntax + +{{ContributingDocs}} + ### Syntax - diff --git a/Sources/SwiftSyntax/Documentation.docc/ChangingSwiftSyntax.md b/Sources/SwiftSyntax/Documentation.docc/Contributing/ChangingSwiftSyntax.md similarity index 100% rename from Sources/SwiftSyntax/Documentation.docc/ChangingSwiftSyntax.md rename to Sources/SwiftSyntax/Documentation.docc/Contributing/ChangingSwiftSyntax.md diff --git a/Sources/SwiftSyntax/Documentation.docc/Contributing/Existentials.md b/Sources/SwiftSyntax/Documentation.docc/Contributing/Existentials.md new file mode 100644 index 00000000000..cc36eaed7c2 --- /dev/null +++ b/Sources/SwiftSyntax/Documentation.docc/Contributing/Existentials.md @@ -0,0 +1,10 @@ +# When to use protocols in SwiftSyntax + +Learn when to use protocols value types like ``ExprSyntax`` over protocols like ``ExprSyntaxProtocol``. + + +SwiftSyntax tries to minimize the use of existentials (aka. protocols spelled with `any` or protocols spelled without `some`) wherever possible. This is because when the stored value is more than 3 words (a word is the size of a pointer) large, these existentials store their data on the heap. The data stored inside `RawSyntax` is larger than 3 words and thus every time you pass a value around as a e.g. an `ExprSyntaxProtocol`, a new heap allocation will be made and that data needs to be reference-counted, which causes a very noticeable performance overhead. + +swift-syntax offers two alternatives: +- When passing a single node around, use `some ExprSyntaxProtocol`. This allows the concrete expression node (e.g. an ``IntegerLiteralExprSyntax``) to be passed directly without the need to wrap it in an existential and thus avoid the performance overhead. +- When multiple expression nodes need to be represented that might be of different types, eg. in an array of expressions, use the ``ExprSyntax`` type. ``ExprSyntax`` is a struct and can thus be allocated on the stack. The downside is that specific expression nodes need to explicitly be upcast to `ExprSyntax` (`ExprSyntax(integerLiteral)`) and downcast to more specific types using a custom `as` method (`expr.as(IntegerLiteralExprSyntax.self)`). diff --git a/Sources/SwiftSyntax/Documentation.docc/Contributing/SPI.md b/Sources/SwiftSyntax/Documentation.docc/Contributing/SPI.md new file mode 100644 index 00000000000..c8c71e07079 --- /dev/null +++ b/Sources/SwiftSyntax/Documentation.docc/Contributing/SPI.md @@ -0,0 +1,9 @@ +# @_spi attribute + +Learn when SwiftSyntax exposes declaration annotated as `@_spi`. + +Functions marked as `@_spi(RawSyntax)` (where ``RawSyntax`` can be any name) are considered *SPI* (System Programming Interface) and are only accessible if the module that declares them is imported as `@_spi(RawSyntax)`. + +Since functions marked as SPI are not part of the public API, swift-syntax makes no guarantee to their source stability. swift-syntax makes no effort to keep its SPI stable. + +Declarations are typically marked as SPI because they have some kind of caveat that makes them unsafe to use in general. For example, when accessing ``RawSyntax`` nodes, you need to manually guarantee that the ``SyntaxArena`` they’re allocated in will not be de-allocated. Other declarations have an `@_spi` to share them between different modules within the swift-syntax package. These would use the [`package` modifier](https://github.com/apple/swift-evolution/blob/main/proposals/0386-package-access-modifier.md) if not for the fact that swift-syntax needed to compile with the last two Swift releases (see ). diff --git a/Sources/SwiftSyntax/Documentation.docc/Contributing/Swift Version.md b/Sources/SwiftSyntax/Documentation.docc/Contributing/Swift Version.md new file mode 100644 index 00000000000..ec5e456618f --- /dev/null +++ b/Sources/SwiftSyntax/Documentation.docc/Contributing/Swift Version.md @@ -0,0 +1,7 @@ +# Language Features Usable in swift-syntax + +Defines which language features the swift-syntax package can use. + +We require that SwiftSyntax builds with the latest released compiler and the previous major version (e.g. with Swift 5.8 and Swift 5.7). + +*This documentation article needs to be expanded* diff --git a/Sources/SwiftSyntax/Documentation.docc/Create SwiftSyntax Release.md b/Sources/SwiftSyntax/Documentation.docc/Create SwiftSyntax Release.md deleted file mode 100644 index 6ad33995621..00000000000 --- a/Sources/SwiftSyntax/Documentation.docc/Create SwiftSyntax Release.md +++ /dev/null @@ -1,31 +0,0 @@ -# Create SwiftSyntax snapshot release with parser library - -## Create release tag -1. Check out the tag you want to release in the SwiftSyntax repository -## Smoke test on macOS - -1. Change the binary target in `Package.swift` to point to your personal GitHub repo -2. Update to Latest Package Versions in Xcode -3. Run tests - -## Smoke test on Linux - -1. Pull the latest development snapshot docker image for the release, e.g. `docker pull swiftlang/swift:nightly-5.6-focal` -2. Start a development docker image `docker run -it --rm swiftlang/swift:nightly-5.6-focal` -3. `git clone https://github.com//swift-syntax` -4. `cd swift-syntax` -5. `git checkout ` -6. `swift test` - -## Publish Release - -1. Push tag to apple/swift-syntax -2. On apple/swift-syntax create a new release using the just-pushed tag -3. If this is a snapshot release, check “This is a pre-release” -4. Publish 🎉 -5. Add the new release to README.md - -## Integration test - -1. Create a new Swift package on macOS that depends on SwiftSyntax and verify that it can parser Swift source into a syntax tree -2. Do the same on Linux diff --git a/Sources/SwiftSyntax/Documentation.docc/generated/SwiftSyntax.md b/Sources/SwiftSyntax/Documentation.docc/generated/SwiftSyntax.md index 6aae4aced67..a15c12ad8f3 100644 --- a/Sources/SwiftSyntax/Documentation.docc/generated/SwiftSyntax.md +++ b/Sources/SwiftSyntax/Documentation.docc/generated/SwiftSyntax.md @@ -17,13 +17,20 @@ allows Swift tools to parse, inspect, generate, and transform Swift source code. ### Articles - -- -- ### Tutorials - +### Contributing + +These articles are intended for developers wishing to contribute to SwiftSyntax + +- +- +- +- + ### Syntax -