Skip to content

Commit d64def2

Browse files
committed
[docs] GettingStarted.md: Do not suggest to run tests when building toolchain
* Running the entire test suite is unnecessarily burdensome for newcomers, given the already considerable build times. * Test failures are not a beginner-friendly indication of an out-of-sync checkout, nor is such an indication generally worth the expenses. * We do not want a known issue to block anyone’s workflow.
1 parent 5eb942c commit d64def2

File tree

1 file changed

+9
-19
lines changed

1 file changed

+9
-19
lines changed

docs/HowToGuides/GettingStarted.md

Lines changed: 9 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ toolchain as a one-off, there are a couple of differences:
1515
- [Cloning the project](#cloning-the-project)
1616
- [Troubleshooting cloning issues](#troubleshooting-cloning-issues)
1717
- [Installing dependencies](#installing-dependencies)
18-
- [macOS](#macOS)
18+
- [macOS](#macos)
1919
- [Linux](#linux)
2020
- [Building the project for the first time](#building-the-project-for-the-first-time)
2121
- [Spot check dependencies](#spot-check-dependencies)
@@ -245,7 +245,7 @@ Phew, that's a lot to digest! Now let's proceed to the actual build itself!
245245
```sh
246246
utils/build-script --skip-build-benchmarks \
247247
--skip-ios --skip-watchos --skip-tvos --swift-darwin-supported-archs "$(uname -m)" \
248-
--sccache --release-debuginfo --swift-disable-dead-stripping --test
248+
--sccache --release-debuginfo --swift-disable-dead-stripping
249249
```
250250
- Via Xcode:
251251
```sh
@@ -254,25 +254,16 @@ Phew, that's a lot to digest! Now let's proceed to the actual build itself!
254254
--sccache --release-debuginfo --swift-disable-dead-stripping \
255255
--xcode
256256
```
257-
**Note:** Building `--xcode` together with `--test` is a common source of issues. So to run
258-
tests is recommended to use `ninja` because is normally more stable.
259257
- Linux (uses Ninja):
260258
```sh
261-
utils/build-script --release-debuginfo --test --skip-early-swift-driver \
259+
utils/build-script --release-debuginfo --skip-early-swift-driver \
262260
--skip-early-swiftsyntax
263261
```
264262
This will create a directory
265263
`swift-project/build/Ninja-RelWithDebInfoAssert`
266264
(with `Xcode` instead of `Ninja` if you used `--xcode`)
267265
containing the Swift compiler and standard library and clang/LLVM build artifacts.
268-
- If the build succeeds: Once the build is complete, the tests will run.
269-
- If the tests are passing: Great! We can go to the next step.
270-
- If some tests are failing:
271-
- Consider [filing a bug report](https://swift.org/contributing/#reporting-bugs).
272-
- Note down which tests are failing as a baseline. This baseline will be
273-
handy later when you run the tests after making a change.
274-
- If the build fails:
275-
See [Troubleshooting build issues](#troubleshooting-build-issues).
266+
If the build fails, see [Troubleshooting build issues](#troubleshooting-build-issues).
276267

277268
If you would like to additionally build the Swift corelibs,
278269
ie swift-corelibs-libdispatch, swift-corelibs-foundation, and swift-corelibs-xctest,
@@ -514,15 +505,14 @@ compiler. Then your changes will not be reflected when the test runs because the
514505
option, but it will lead to a longer feedback loop due to more things getting
515506
rebuilt.
516507

508+
In the rare event that a local test failure happens to be unrelated to your
509+
changes (is not due to stale binaries and reproduces without your changes),
510+
there is a good chance that it has already been caught by our continuous
511+
integration infrastructure, and it may be ignored.
512+
517513
If you want to rerun all the tests, you can either rebuild the whole project
518514
and use `lit.py` without `--filter` or use `run-test` to handle both aspects.
519515

520-
Recall the baseline failures mentioned in
521-
[the build section](#the-actual-build). If your baseline had failing tests, make
522-
sure you compare the failures seen after your changes to the baseline. If some
523-
test failures look totally unrelated to your changes, there is a good chance
524-
that they were already failing as part of the baseline.
525-
526516
For more details on running tests and understanding the various Swift-specific
527517
lit customizations, see [Testing.md](/docs/Testing.md). Also check out the
528518
[lit documentation](https://llvm.org/docs/CommandGuide/lit.html) to understand

0 commit comments

Comments
 (0)