Skip to content

Latest commit

 

History

History
93 lines (65 loc) · 4.42 KB

CONTRIBUTING.md

File metadata and controls

93 lines (65 loc) · 4.42 KB

Contributing

This guide refers to Swift Development Snapshots. These can be downloaded from swift.org/download. If you are seeing issues, it is generally a good idea to re-try with the latest Swift Development Snapshot.

Building

The easiest option to build SwiftSyntax it to open it in Xcode.

Alternatively you can also build it from the command line using build-script.py. To do this, perform the following steps

  1. Check swift-syntax and swift-argument-parser out side by side: 
    - (enclosing directory)
  - swift-argument-parser
  - swift-syntax
  2. Execute the following command 
    swift-syntax/build-script.py build --toolchain /Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-<recent date>.xctoolchain/usr

Formatting

SwiftSyntax is being formatted using swift-format to ensure a consistent style.

To format your changes run format.py at the root of this repository. If you have a swift-format executable ready, you can pass it to format.py. If you do not, format.py will build its own copy of swift-format in /tmp/swift-format.

CI will ensure that all hand-written source code is correctly formatted. Generated source code is not formatted to make it easier to spot changes when re-running code generation.

Testing

Because of SwiftSyntax’s integration with the Swift compiler project, testing certain parts of the project is a little bit more involved than others.

The SwiftParser tests have no dependencies, other XCTests require you to use a matching Swift Development Snapshot, lit-based test require a compiler build.

Run the tests that you believe are necessary locally. CI will always run all test before allowing the PR to be merged.

SwiftParser

If you are only modifying the SwiftParser module, you can just run the tests using Xcode by testing the SwiftParserTest target.

If you can’t find it in your Schemes, you need to manually add it using Product -> Scheme -> New Scheme…

XCTests

To run the tests in Xcode, select the SwiftSyntax-Package scheme and hit Product -> Test.

You can also run the tests from the command line using

./build-script.py test --toolchain /Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-<recent date>.xctoolchain/usr --skip-lit-tests

If you are seeing issues regarding a mismatched parser library, try the following

  1. Update your Swift Development Snapshot
  2. Revert your swift-syntax checkout to the date of your Swift Development Snapshot
  3. Wait for a new Swift Development Snapshot
  4. If the above options are not possible, build your own Swift toolchain locally and use that toolchain as the --toolchain parameter for SwiftSyntax’s build-script.py invocations
  • Note: Building your own toolchain will take more than 1 hour and even longer if you are running into any issues. We do not recommend building your own Swift toolchain unless you are familiar with Swift compiler development.

Tip: Running SwiftSyntax’s self-parse tests takes the majority of testing time. If you want to iterate quickly, you can skip these tests using the following steps:

  1. Product -> Scheme -> Edit Scheme…
  2. Select the Arguments tab in the Run section
  3. Add a SKIP_LONG_TESTS environment variable with value 1

lit-based Tests

A few tests are based LLVM’s lit and FileCheck tools. To run these, build FileCheck, e.g. by building the Swift compiler and run the tests using the following command:

./build-script.py test --toolchain /Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-<recent date>.xctoolchain/usr --skip-lit-tests --filecheck-exec /path/to/build/Release+Asserts/llvm-macosx-x86_64/bin/FileCheck

Generating Source Code

If you want to modify the code-generated files, perform the following steps:

  1. Check out swift next to swift-syntax 
    - (enclosing directory)
  - swift
  - swift-argument-parser
  - swift-syntax
  2. Run the following command 
    swift-syntax/build-script.py generate-source-code --toolchain /Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-<recent date>.xctoolchain/usr
  3. The new source-generated file will be written into your Sources directory.

Swift Version

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).