Skip to content

Commit 3db552d

Browse files
kimdvkimdv
committed
Update readme
1 parent b12be78 commit 3db552d

File tree

7 files changed

+252
-229
lines changed

7 files changed

+252
-229
lines changed

‎CONTRIBUTING.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Contributing
2+
3+
## Building SwiftSyntax from `main`
4+
5+
Since SwiftSyntax relies on definitions in the main Swift repository to generate the layout of the syntax tree using `gyb`, a checkout of [apple/swift](https://github.com/apple/swift) is still required to build the latest development snapshot of SwiftSyntax.
6+
7+
To build the `main` branch of SwiftSyntax, follow the following instructions:
8+
9+
1. Check `swift-syntax` and `swift` out side by side:
10+
```
11+
- (enclosing directory)
12+
- swift
13+
- swift-syntax
14+
```
15+
16+
2. Make sure you have a recent [Trunk Swift Toolchain](https://swift.org/download/#snapshots) installed.
17+
3. Define the `TOOLCHAINS` environment variable as below to have the `swift` command point inside the toolchain:
18+
19+
```bash
20+
$ export TOOLCHAINS=swift
21+
```
22+
23+
4. To make sure everything is set up correctly, check the return statement of `xcrun --find swift`. It should point inside the latest installed trunk development toolchain. If it points inside an Xcode toolchain, check that you exported the `TOOLCHAINS` environment variable correctly. If it points inside a version-specific toolchain (like Swift 5.0-dev), you'll need to remove that toolchain.
24+
5. Run `swift-syntax/build-script.py`.
25+
If despite following those instructions, you get compiler errors, the Swift toolchain might be too old to contain recent changes in Swift's SwiftSyntaxParser C library. In that case, you'll have to build the compiler and SwiftSyntax together with the following command:
26+
27+
```bash
28+
$ swift/utils/build-script --swiftsyntax --swiftpm --llbuild
29+
```
30+
31+
Swift-CI will automatically run the code generation step whenever a new toolchain (development snapshot or release) is published. It should thus almost never be necessary to perform the above build yourself.
32+
33+
Afterward, SwiftPM can also generate an Xcode project to develop SwiftSyntax by running `swift package generate-xcodeproj`.
34+
35+
If you also want to run tests locally, read the section below as testing has additional requirements.
36+
37+
## Local Testing
38+
39+
SwiftSyntax uses some test utilities that need to be built as part of the Swift compiler project. To build the most recent version of SwiftSyntax and test it, follow the steps in [swift/README.md](https://github.com/apple/swift/blob/main/README.md) and pass `--llbuild --swiftpm --swiftsyntax` to the build script invocation to build SwiftSyntax and all its dependencies using the current trunk (`main`) compiler.
40+
41+
SwiftSyntax can then be tested using the build script in `apple/swift` by running
42+
43+
```bash
44+
swift/utils/build-script --swiftsyntax --swiftpm --llbuild -t --skip-test-cmark --skip-test-swift --skip-test-llbuild --skip-test-swiftpm
45+
```
46+
47+
This command will build SwiftSyntax and all its dependencies, tell the build script to run tests, but skip all tests but the SwiftSyntax tests.
48+
49+
Note that it is not currently supported by SwiftSyntax while building the Swift compiler using Xcode.
50+
51+
## CI Testing
52+
53+
Running `@swift-ci Please test` on the main Swift repository will also test the most recent version of SwiftSyntax.
54+
55+
Testing SwiftSyntax from its own repository is now available by commenting `@swift-ci Please test macOS platform`.

‎Documentation/README.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Documentation
2+
3+
## Usage
4+
5+
### Declare SwiftPM dependency with nightly build
6+
7+
1. Download and install the latest Trunk Development [toolchain](https://swift.org/download/#snapshots).
8+
9+
2. Define the `TOOLCHAINS` environment variable as below to have the `swift` command point inside the toolchain:
10+
```bash
11+
$ export TOOLCHAINS=swift
12+
```
13+
14+
3. To make sure everything is set up correctly, check the result of `xcrun --find swift`. It should point inside the OSS toolchain.
15+
16+
4. Add this entry to the `Package.swift` manifest of your project:
17+
18+
```swift
19+
// swift-tools-version:5.3
20+
import PackageDescription
21+
22+
let package = Package(
23+
name: "MyTool",
24+
dependencies: [
25+
.package(url: "https://github.com/apple/swift-syntax.git", .revision("swift-DEVELOPMENT-SNAPSHOT-2019-02-26")),
26+
],
27+
targets: [
28+
.target(name: "MyTool", dependencies: ["SwiftSyntax"]),
29+
]
30+
)
31+
```
32+
33+
Tags will be created for every nightly build in the form of `swift-DEVELOPMENT-SNAPSHOT-<DATE>`. The revision field
34+
should be specified with the intended tag.
35+
36+
Different from building SwiftSyntax from source, declaring SwiftSyntax as a SwiftPM dependency doesn't require
37+
the Swift compiler source because we always push gyb-generated files to a tag.
38+
39+
### Embedding SwiftSyntax in an Application
40+
41+
SwiftSyntax depends on the `lib_InternalSwiftSyntaxParser.dylib/.so` library which provides a C interface to the underlying Swift C++ parser. When you do `swift build` SwiftSyntax links and uses the library included in the Swift toolchain. If you are building an application make sure to embed `_InternalSwiftSyntaxParser` as part of your application's libraries.
42+
43+
You can either copy `lib_InternalSwiftSyntaxParser.dylib/.so` directly from the toolchain or even build it yourself from the [Swift repository](https://github.com/apple/swift), as long as you are matching the same tags or branches in both the SwiftSyntax and Swift repositories. To build it for the host os (macOS/linux) use the following steps:
44+
45+
```bash
46+
git clone https://github.com/apple/swift.git
47+
./swift/utils/update-checkout --clone
48+
./swift/utils/build-parser-lib --release --no-assertions --build-dir /tmp/parser-lib-build
49+
```
50+
51+
### Embedding in an iOS Application
52+
53+
You need to build `lib_InternalSwiftSyntaxParser.dylib` yourself, you cannot copy it from the toolchain. Follow the instructions above and change the invocation of `build-parser-lib` accordingly:
54+
55+
```bash
56+
./swift/utils/build-parser-lib --release --no-assertions --build-dir /tmp/parser-lib-build-iossim --host iphonesimulator --architectures x86_64
57+
./swift/utils/build-parser-lib --release --no-assertions --build-dir /tmp/parser-lib-build-ios --host iphoneos --architectures arm64
58+
```

‎Examples/AddOneToIntegerLiterals.swift‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import SwiftSyntax
2+
import Foundation
3+
4+
/// AddOneToIntegerLiterals will visit each token in the Syntax tree, and
5+
/// (if it is an integer literal token) add 1 to the integer and return the
6+
/// new integer literal token.
7+
///
8+
/// For example will it turn:
9+
/// ```
10+
/// let x = 2
11+
/// let y = 3_000
12+
/// ```
13+
/// into:
14+
/// ```
15+
/// let x = 3
16+
/// let y = 3001
17+
/// ```
18+
class AddOneToIntegerLiterals: SyntaxRewriter {
19+
override func visit(_ token: TokenSyntax) -> Syntax {
20+
// Only transform integer literals.
21+
guard case .integerLiteral(let text) = token.tokenKind else {
22+
return Syntax(token)
23+
}
24+
25+
// Remove underscores from the original text.
26+
let integerText = String(text.filter { ("0"..."9").contains($0) })
27+
28+
// Parse out the integer.
29+
let int = Int(integerText)!
30+
31+
// Create a new integer literal token with `int + 1` as its text.
32+
let newIntegerLiteralToken = token.withKind(.integerLiteral("\(int + 1)"))
33+
34+
// Return the new integer literal.
35+
return Syntax(newIntegerLiteralToken)
36+
}
37+
}
38+
39+
let file = CommandLine.arguments[1]
40+
let url = URL(fileURLWithPath: file)
41+
let sourceFile = try SyntaxParser.parse(url)
42+
let incremented = AddOneToIntegerLiterals().visit(sourceFile)
43+
print(incremented)

‎Examples/CodeGenerationUsingSwiftSyntaxBuilder.swift‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
import SwiftSyntaxBuilder
2+
3+
/// This example will print the following example:
4+
///
5+
///```
6+
/// import Foundation
7+
/// import UIKit
8+
/// class SomeViewController{
9+
/// let tableView: UITableView
10+
/// }
11+
///```
12+
13+
let source = SourceFile {
14+
ImportDecl(path: "Foundation")
15+
ImportDecl(path: "UIKit")
16+
ClassDecl(classOrActorKeyword: .class, identifier: "SomeViewController", membersBuilder: {
17+
VariableDecl(.let, name: "tableView", type: "UITableView")
18+
})
19+
}
20+
21+
let syntax = source.buildSyntax(format: Format())
22+
23+
var text = ""
24+
syntax.write(to: &text)
25+
26+
print(text)

‎Examples/README.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Examples
2+
3+
- Command line tool to add one to every integer literal in a source file [AddOneToIntegerLiterals.swift](https://github.com/apple/swift-syntax/blob/main/Examples/AddOneToIntegerLiterals.swift).
4+
- Code-generate a simple source file using SwiftSyntaxBuilder [CodeGenerationUsingSwiftSyntaxBuilder.swift](https://github.com/apple/swift-syntax/blob/95fe6182b755346eee74b499109b4ab9eaf38651/Examples/CodeGenerationUsingSwiftSyntaxBuilder.swift)
5+
6+
## Some Example Usages
7+
8+
[**Swift AST Explorer**](https://swift-ast-explorer.kishikawakatsumi.com/): a Swift AST visualizer.
9+
10+
[**swift-format**](https://github.com/apple/swift-format): formatting technology for Swift source code.
11+
12+
[**Swift Stress Tester**](https://github.com/apple/swift-stress-tester): a test driver for sourcekitd and Swift evolution.
13+
14+
[**SwiftSemantics**](https://github.com/SwiftDocOrg/SwiftSemantics): parses Swift code into its constituent declarations.
15+
16+
[**Sitrep**](https://github.com/twostraws/Sitrep): A source code analyzer for Swift projects
17+
18+
[**SwiftRewriter**](https://github.com/inamiy/SwiftRewriter): a Swift code formatter.
19+
20+
[**SwiftPack**](https://github.com/omochi/SwiftPack): a tool for automatically embedding Swift library source.
21+
22+
[**Periphery**](https://github.com/peripheryapp/periphery): a tool to detect unused code.
23+
24+
[**BartyCrouch**](https://github.com/Flinesoft/BartyCrouch): a tool to incrementally update strings files to help App localization.
25+
26+
[**Muter**](https://github.com/muter-mutation-testing/muter): Automated mutation testing for Swift
27+
28+
[**Swift Variable Injector**](https://github.com/LucianoPAlmeida/variable-injector): a tool to replace string literals with environment variables values.
29+
30+
[**Pecker**](https://github.com/woshiccm/Pecker): a tool to detect unused code based on [SwiftSyntax](https://github.com/apple/swift-syntax.git) and [IndexStoreDB](https://github.com/apple/indexstore-db.git).
31+
32+
[**Piranha**](https://github.com/uber/piranha): a tool for refactoring code related to feature flags.
33+
34+
[**STAR**](https://github.com/thumbtack/star): a tool to find how often specified Swift type(s) are used in a project.## Some Example Users
35+
36+
[**Swift AST Explorer**](https://swift-ast-explorer.kishikawakatsumi.com/): a Swift AST visualizer.
37+
38+
[**swift-format**](https://github.com/apple/swift-format): formatting technology for Swift source code.
39+
40+
[**Swift Stress Tester**](https://github.com/apple/swift-stress-tester): a test driver for sourcekitd and Swift evolution.
41+
42+
[**SwiftSemantics**](https://github.com/SwiftDocOrg/SwiftSemantics): parses Swift code into its constituent declarations.
43+
44+
[**Sitrep**](https://github.com/twostraws/Sitrep): A source code analyzer for Swift projects
45+
46+
[**SwiftRewriter**](https://github.com/inamiy/SwiftRewriter): a Swift code formatter.
47+
48+
[**SwiftPack**](https://github.com/omochi/SwiftPack): a tool for automatically embedding Swift library source.
49+
50+
[**Periphery**](https://github.com/peripheryapp/periphery): a tool to detect unused code.
51+
52+
[**BartyCrouch**](https://github.com/Flinesoft/BartyCrouch): a tool to incrementally update strings files to help App localization.
53+
54+
[**Muter**](https://github.com/muter-mutation-testing/muter): Automated mutation testing for Swift
55+
56+
[**Swift Variable Injector**](https://github.com/LucianoPAlmeida/variable-injector): a tool to replace string literals with environment variables values.
57+
58+
[**Pecker**](https://github.com/woshiccm/Pecker): a tool to detect unused code based on [SwiftSyntax](https://github.com/apple/swift-syntax.git) and [IndexStoreDB](https://github.com/apple/indexstore-db.git).
59+
60+
[**Piranha**](https://github.com/uber/piranha): a tool for refactoring code related to feature flags.
61+
62+
[**STAR**](https://github.com/thumbtack/star): a tool to find how often specified Swift type(s) are used in a project.

0 commit comments

Comments
 (0)