Skip to content

Improve the documentation for building master #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 4, 2019
Merged

Improve the documentation for building master #87

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 26 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,37 +52,55 @@ Then, import `SwiftSyntax` in your Swift code.
## Contributing

### Building SwiftSyntax from `master`

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 `master` of SwiftSyntax.

To build the `master` version of SwiftSyntax, check `swift-syntax` and `swift` out side by side
To build the `master` version of SwiftSyntax, follow the following instructions:

1. Check `swift-syntax` and `swift` out side by side:

```
- (enclosing directory)
- swift
- swift-syntax
```

And run `swift-syntax/build-script.py`. SwiftSyntax is now being built with the Swift compiler installed on the system.
2. Make sure you have a recent [master Swift toolchain](https://swift.org/download/#snapshots) installed.
3. Define the `TOOLCHAINS` environment variable as below to have the `swift` command point inside the toolchain:

```
$ export TOOLCHAINS=swift
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens if we have multiple OSS toolchain in the dir. Will this select the latest master?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It will

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've noticed if any swift-5.0-development snapshots are present, these toolchains will take precedence over the master ones. Could you mention this caveat?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the documentation to warn against version specific toolchains. Let me know if you think this is enough.

```

4. To make sure everything is setup correctly, check the return statement of `xcrun --find swift`. It should point inside the latest installed master 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.
5. Run `swift-syntax/build-script.py`.

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:

```
$ swift/utils/build-script --swiftsyntax --swiftpm --llbuild
Copy link

@mdiep mdiep Feb 22, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can only be used to build a .dylib, right? Not a .framework?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the only way that I've been able to successfully build a recent version of SwiftSyntax—but it's still not in a usable form. 😞

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can't remember what it builds: I've only used it for development.

```

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

Afterwards, SwiftPM can also generate an Xcode project to develop SwiftSyntax by running `swift package generate-xcodeproj`.

If you also want to run tests locally, read the section below as testing has additional requirements.
If you also want to run tests locally, read the section below as testing has additional requirements.

### Local Testing
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/master/README.md) and pass `--llbuild --swiftpm --swiftsyntax` to the build script invocation to build SwiftSyntax and all its dependencies using the current `master` compiler.
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/master/README.md) and pass `--llbuild --swiftpm --swiftsyntax` to the build script invocation to build SwiftSyntax and all its dependencies using the current `master` compiler.

SwiftSyntax can then be tested using the build script in `apple/swift` by running
SwiftSyntax can then be tested using the build script in `apple/swift` by running
```
swift/utils/build-script --swiftsyntax --swiftpm --llbuild -t --skip-test-cmark --skip-test-swift --skip-test-llbuild --skip-test-swiftpm
```
This command will build SwiftSyntax and all its dependencies, tell the build script to run tests, but skip all tests but the SwiftSyntax tests.
This command will build SwiftSyntax and all its dependencies, tell the build script to run tests, but skip all tests but the SwiftSyntax tests.

Note that it is not currently supported to SwiftSyntax while building the Swift compiler using Xcode.

### CI Testing

Running `@swift-ci Please test` on the main Swift repository will also test the most recent version of SwiftSyntax.
Running `@swift-ci Please test` on the main Swift repository will also test the most recent version of SwiftSyntax.

Testing SwiftSyntax from its own repository is now available by commenting `@swift-ci Please test macOS platform`.

Expand Down