-
Notifications
You must be signed in to change notification settings - Fork 10.4k
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.
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
Update README.md #11463
Update README.md #11463
Conversation
…ia package manager
README.md
Outdated
### System Requirements | ||
|
||
macOS, Ubuntu Linux LTS, and the latest Ubuntu Linux release are the current | ||
supported host development operating systems. | ||
|
||
For macOS, you need [Xcode 9.0 beta 4](https://developer.apple.com/xcode/downloads/). | ||
To build for macOS, you always need the latest version of Xcode, currently | ||
[Xcode 9.0 beta 4](https://developer.apple.com/xcode/downloads/). You will |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
9.0 beta 5 is now out
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is someone going to keep this up to date? Could also link to developer.apple.com/downloads, although I believe that page is walled off behind an Apple ID login.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I didn't bump the version because I know there's an issue right now with beta 5 and AVFoundation. I think it's better to let this lie live till beta 6 / GM ;0
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is updated once swift is ready to be built with new Xcode, and ci.swift.org has been updated.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it'd be good to really make clear that the latest supported is beta 4. I have a lot of issues when I started because Swift wasn't compiling on beta 4 (and this doc said beta 3). I assumed it was all my fault 😬
Looks good, thanks! |
@swift-ci Please smoke test |
README.md
Outdated
development environment. Options for doing things differently are | ||
discussed below. | ||
These instructions give the most direct path to a working Swift development | ||
environment. To build from source you will need 2gb of disk space for the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
2gb → 2 GB, 20gb → 20 GB
utils/build-script
Outdated
@@ -1186,7 +1186,7 @@ Using option presets: | |||
using the name=value syntax on the command line. | |||
|
|||
|
|||
Any arguments not listed are forwarded directly to Swift's | |||
Any arguments not listed, or arguments after `--` are forwarded to Swift's |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actually, this is not true.
https://github.com/apple/swift/blob/ade67ca8994dbbb5d4754a06147c787eaa0d11f7/utils/swift_build_support/swift_build_support/migration.py#L33-L34
--
is simply ignored.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good catch!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yep. It used to be true, but we changed it once we decided to move build-script-impl into build-script. (That effort itself then ran into issues, but that's another story.)
README.md
Outdated
|
||
utils/build-script -x | ||
- Select the ‘swift’ scheme | ||
- Pull up the scheme editor (⌘+⇧+<) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The ⌘ symbol, and maybe the ⇧ symbol, won't render on Linux,. Might want to spell this as "Command-Shift-<", or as Command-Shift-, or Command-Shift-Comma. Or do it like Xcode does it: Command-<. There's no great answer here :\
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think I'll leave the formatting for now. Since it's Xcode specific, not formatting on Linux isn't the worst.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nitpick: technically, this should be written "⇧⌘<" if you're going to use symbols. (Citation: me)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looking great!
README.md
Outdated
|
||
**[MacPorts](https://macports.org)** | ||
utils/build-script -R --debug-swift |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This will also build LLVM, Clang, and the Swift standard library with optimizations and asserts, but no debug symbols. Worth pointing out e.g. utils/build-script -r --debug-swift-stdlib
, for people wanting to work on the standard library but want a optimized+asserts compiler.
I think a better recommendation for beginners is utils/build-script -r
, as a debug compiler or standard library is very slow, and I would expect many beginners initially to want something fast more than the ability to break in a debugger meaningfully. ^^^ This is complete opinion, feel free to ignore.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, also, I always specify a -j<n>
so that my machine remains responsive. Might be worth a mention. Similarly for the ninja
and lit
sections. Oddly enough, I don't think build-script passes it off the lit correctly...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
utils/build-script -r
also disables asserts in the compiler, which is not something you want when hacking on the compiler itself.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
TBH, I wonder if it would be better to have the longer more verbose names in the getting started guide, e.g.: --release-debuginfo and --release. IMO this will be easier for new contributors to remember since it isn't a random flag. Just my 2 cents.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@slavapestov nope, utils/build-script -r
builds with assertions enabled. You have to pass --no-assertions
to turn them off.
README.md
Outdated
A basic command to build Swift with optimizations and run basic tests with | ||
Ninja: | ||
cd ${SWIFT_BUILD_ROOT} | ||
ninja swift |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is very compelling for people who want to rapidly iterate on the compiler without having to build the standard library (which takes a while). Worth calling out explicitly.
For anyone wanting to work on the standard library, ninja
is usually just fine as that can build overlays in parallel and skips the benchmarks. Speaking of which, not sure if you want to call out the benchmarks targets.
README.md
Outdated
|
||
Make sure you are using the latest release of Xcode to build, including Betas. | ||
If you have changed Xcode versions but still encounter errors that appear to | ||
be related to the Xcode version, try passing `-- --rebuild` to `build-script`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Might be worth covering --reconfigure
. There's no need for a total recompilation of all C++ (Clang, LLVM, Swift compiler) just for a newer Xcode.
docs/Testing.md
Outdated
LLVM's lit.py script directly. For example: | ||
Using `lit.py` directly can provide more control and faster feedback to your | ||
development cycle. To invoke LLVM's `lit.py` script directly, it must be | ||
configured to use your local build directory. For example: | ||
|
||
``` | ||
% ${LLVM_SOURCE_ROOT}/utils/lit/lit.py -sv ${SWIFT_BUILD_ROOT}/test-iphonesimulator-i386/Parse/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is worth hyperlinking to from the GettingStarted guide, as it's one of the first things I tell new contributors once they're building and running. Otherwise, it's rather buried.
README.md
Outdated
|
||
Contributions to Swift are welcomed and encouraged! Please see the | ||
[Contributing to Swift guide](https://swift.org/contributing/). | ||
See [docs/DebuggingTheCompiler.md](docs/DebuggingTheCompiler.md). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This document is still .rst
, not .md
README.md
Outdated
work with other SDKs, you'll need to create a second build using Ninja. | ||
### Build Failures | ||
|
||
Make sure you are using the latest release of Xcode to build, including Betas. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this might not be true, as discussed in "System Requirements"
README.md
Outdated
**[Homebrew](https://brew.sh/)** | ||
The Xcode IDE can be used to edit the Swift source code, but it is not currently | ||
fully supported as a build environment for SDKs other than macOS. If you need to | ||
work with other SDKs, you'll need to create a second build using Ninja. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
One of the doubts that I had when starting was how I could run the tests with Xcode. Apparently, there's no way. I think that should also be explicitly said here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can run the tests by building the check-swift target.
README.md
Outdated
|
||
**Via HTTPS** | ||
utils/build-script -r -t |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For example, here, it would be clearer if you said:
./utils/build-script --release-debuginfo --assertions --test
README.md
Outdated
|
||
sudo port install cmake ninja | ||
|
||
Instructions for installing CMake and Ninja directly can be found [here](#build-dependencies) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nitpick: maybe change "here" to "below"?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for taking the time to look through and improve this, Brian!
README.md
Outdated
These instructions give the most direct path to a working Swiftdevelopment | ||
environment. To build from source you will need 2gb of disk space for the | ||
source code and over 20gb of disk space for the build artifacts. The first | ||
build will take multiple hours, but incremental builds will finish much faster. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think any build takes "multiple hours", even on my old MacBook Air, unless you build an all-debug compiler and a release standard library. "may take more than an hour", perhaps?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe it just feels like hours sometimes. I'm going to run a few builds out of my own curiosity, but downgraded this to a "can".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So I have a Mid-2015 MBP 2.5 GHz i7, and running -x
took 3 hours, and just a debug compiler (-R --debug-swift
) took 70 minutes. So I think this is pretty accurate. My intent with adding this information was to set expectations, not an official benchmark.
README.md
Outdated
@@ -108,7 +108,7 @@ options such as building a Swift-compatible LLDB, building the Swift Package | |||
Manager, building for iOS, running tests after builds, and more. It also | |||
supports presets, which you can define for common combinations of build options. | |||
|
|||
To find out more: | |||
View the inline help to find out more, in particular the section "Typical uses" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nitpick: Missing a colon.
utils/build-script
Outdated
@@ -1186,7 +1186,7 @@ Using option presets: | |||
using the name=value syntax on the command line. | |||
|
|||
|
|||
Any arguments not listed are forwarded directly to Swift's | |||
Any arguments not listed, or arguments after `--` are forwarded to Swift's |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yep. It used to be true, but we changed it once we decided to move build-script-impl into build-script. (That effort itself then ran into issues, but that's another story.)
README.md
Outdated
|
||
utils/build-script -x | ||
- Select the ‘swift’ scheme | ||
- Pull up the scheme editor (⌘+⇧+<) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nitpick: technically, this should be written "⇧⌘<" if you're going to use symbols. (Citation: me)
README.md
Outdated
auto-create a *lot* of schemes for all of the available targets. A common debug | ||
flow would involve: | ||
|
||
- Select the ‘swift’ scheme |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nitpick: smart quotes?
README.md
Outdated
- Select the ‘Arguments’ tab and click the ‘+’ | ||
- Add the command line options | ||
- Close the scheme editor | ||
- Build and run |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll suggest an alternate workflow: rather than messing with the command line options in the scheme editor, change the scheme to "Wait for executable to be launched", then run the build product in Terminal. Do you think that's better or worse for new people?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I stole this workflow from a recent swift-dev post, and I think including both is a good idea. Thanks!
README.md
Outdated
@@ -21,6 +21,8 @@ features like flow control, data structures, and functions, with high-level | |||
constructs like objects, protocols, closures, and generics. Swift embraces | |||
modules, eliminating the need for headers and the code duplication they entail. | |||
|
|||
To learn more about the programming language, visit [swift.org](https://swift.org/documentation/) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Missing a period.
…ILD_ROOT means something else in the build script.
Hey folks, thanks for all the feedback! I believe I've addressed everyones comments, but a quick double check would be great. In particular
|
README.md
Outdated
|
||
utils/build-script -h | ||
|
||
A basic command to build Swift with optimizations and run basic tests with | ||
Ninja: | ||
|
||
utils/build-script -r -t | ||
utils/build-script --release --test |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah, IIRC -r
is --release-debuginfo
, not just --release
. (That's -R
.) I know you make that distinction below, but for the very first thing people build they probably want the debug info and assertions.
README.md
Outdated
- Pull up the scheme editor (⌘+⇧+<) | ||
- Select the ‘Arguments’ tab and click the ‘+’ | ||
- Select the 'swift' scheme | ||
- Pull up the scheme editor (⌘⇧<) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Extra nitpick: Command comes first when spelled out, but last in symbol form.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some comments related to assertions and some questions.
README.md
Outdated
|
||
**Via HTTPS** | ||
utils/build-script --release --test |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The most basic build-script that people should use for new people IMO is:
./utils/build-script --release-debuginfo --assertions --test
You really want the --assertions.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My thought with this build (Not in the "Development Environment" section), was that it would be a release capable build.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe specify that? It seems like you are suggesting that this is the most basic build that people use.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I strongly recommend building with assertions for both compiler and stdlib. Only disable for benchmarking and perf tuning (or release validation, which is out of scope for most contributors).
README.md
Outdated
|
||
sudo port install cmake ninja | ||
utils/build-script --release |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Again, I would change this to --release-debuginfo --assertions. In my experience assertions/debug info do not hurt compile time /that/ much and are really useful while developing. The debuginfo is useful since it will improve the ability of the new person to get better diagnostics when failures happen IIRC. But maybe my memory is wrong. The assertions though I would definitely consider adding.
README.md
Outdated
options such as building a Swift-compatible LLDB, building the Swift Package | ||
Manager, building for iOS, running tests after builds, and more. It also | ||
supports presets, which you can define for common combinations of build options. | ||
utils/build-script --release-debuginfo --debug-swift |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Again --assertions.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would also mention here that --debug-swift does not touch the stdlib. So for a fully debug experience with a release LLVM, you need to do:
./utils/build-script --release-debuginfo --debug-swift --debug-swift-stdlib.
Additionally, as an advanced feature, there is an option that you can use to compile just the typechecker in release. This is useful in reducing compile time if one only wants to debug /post-typechecking/. The option is:
--force-optimized-typechecker.
That being said, I am not 100% sure if this option is appropriate for this guide.
README.md
Outdated
|
||
utils/build-script -h | ||
utils/build-script --release --debug-swift-stdlib |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You need assertions here. This will compile the stdlib without assertions IIRC.
README.md
Outdated
This command will rebuild the stdlib and skip the `benchmarks` target. This | ||
is great for developers interested in working on the standard library. | ||
|
||
It is always a good idea to do a full build after using `update-checkout`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Question. Was the notion of a scheme used in update-checkout confusing to you? Do you think it needs to be explained?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
People who stay on the master branch don't need to know about schemes.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure. That is why I was unsure.
I don't think
The build directory created is
That said, I'm new around here and may be missing something! |
If it is on by default, ok. I guess I always pass it in for explicitness. |
README.md
Outdated
|
||
|
||
### System Requirements | ||
|
||
macOS, Ubuntu Linux LTS, and the latest Ubuntu Linux release are the current | ||
supported host development operating systems. | ||
|
||
For macOS, you need [Xcode 9.0 beta 4](https://developer.apple.com/xcode/downloads/). | ||
<a name="xcode"></a> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Formatting nitpick: I think this would be a bit clearer with a #### macOS
header to go balance with #### Linux
below. Or maybe remove the Linux header and just rely on the paragraph separation of sections.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM. Thank you for this effort!
Hey @milseman -- I pushed up a few more changes after your approval. It'd be good to get another scan to make sure it still looks good. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Two small suggestions that add clarity.
README.md
Outdated
discussed below. | ||
These instructions give the most direct path to a working Swift development | ||
environment. To build from source you will need 2 GB of disk space for the | ||
source code and over 20 GB of disk space for the build artifacts. The first |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The first build => A clean build
README.md
Outdated
|
||
#### Install via third-party packaging tool (macOS only) | ||
This will only build the compiler, and it will not build the standard library. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This makes it sound like you will not build the standard library rather than what will happen (you will build the stdlib but you will suffer through building an optimized stdlib with a debug compiler).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Interesting, given your phrasing above in ()
, would you just recommend using both --debug-swift --debug-swift-stdlib
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No. It depends on what you are doing. For instance, if you are working on optimization passes, you definitely want a release stdlib. But if you do not care about optimizations, not using a debug stdlib will be significantly faster.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I strongly recommend only using a debug build for the portion that you will be tightly iterating and debugging on. Otherwise even just basic things like testing or building the stdlib itself take way too long.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Exactly.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ok, this is super helpful! I updated the section to describe these switches as a performance consideration rather than the over-arching guidance I was specifying before.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just some clarifications on compiler vs project, and a suggestion to highlight the alternatives over the global debug config
README.md
Outdated
|
||
**Via HTTPS** | ||
If you are interested in debugging the compiler, run: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This isn't just the compiler, but the whole Swift project: Clang, Swift frontend, LLVM, standard library, runtimes, and all. I would move this section lower.
Straw man: """
When working on a specific area of the project, it helps to build the area you're working on in a debug configuration while building the rest of the project with optimizations. Below are some examples of using debug variants:
utils/build-script --release-debuginfo --debug-swift # Swift frontend built in debug
utils/build-script --release-debuginfo --debug-swift-stdlib # Standard library built in debug
utils/build-script --release-debuginfo --debug-swift --force-optimized-typechecker # Swift frontend sans type checker built in debug
If you want to build the entire project in debug, which will produce a considerably slower compiler and standard library, you can run:
utils/build-script --debug
"""
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great, I like that direction a lot better @milseman ! I polished up the phrasing a touch and pushed up a change.
This looks awesome to me! I think further tweaking can be in a different PR. I want to get all this goodness in front of new contributor's eyes as soon as we can. |
@swift-ci please smoke test |
I'm interested in improving the developer on boarding experience, so I took a stab at changing the README.md. I'm not sure if this change is cutting a bit too deep, but I wanted to roll back some of what I've learned about developing in Swift back into the README to help others get involved.
README.md changes:
DebuggingTheCompiler.rst
-- I found this document way too late!Testing.rst
build-script
will rebuild all targets, and that lit can be used to run tests directlylit.py
testing has been a lot more helpful than using CMake.