Skip to content

GettingStarted.md: A sprinkle of minor improvements #62371

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 3 commits into from
Dec 8, 2022
Merged

GettingStarted.md: A sprinkle of minor improvements #62371

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3cfb3b8
GettingStarted.md: Don’t suggest starting Sccache manually: `build-sc…
AnthonyLatsis Dec 2, 2022
c7ca361
GettingStarted.md: Fix indentation in bullet so that it renders corre…
AnthonyLatsis Dec 2, 2022
52c821a
GettingStarted.md: Reformat notes
AnthonyLatsis Dec 2, 2022
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
80 changes: 42 additions & 38 deletions docs/HowToGuides/GettingStarted.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,9 +81,10 @@ toolchain as a one-off, there are a couple of differences:
cd swift
utils/update-checkout --clone
```
**Note:** If you've already forked the project on GitHub at this stage,
**do not clone your fork** to start off. We describe
[how to setup your fork](#setting-up-your-fork) in a subsection below.
> **Note**
> If you've already forked the project on GitHub at this stage, **do not
> clone your fork** to start off. We describe [how to setup your fork](#setting-up-your-fork)
> in a subsection below.
<!-- Recommending against cloning the fork due to https://github.com/apple/swift/issues/55918 and https://github.com/apple/swift/issues/55947. -->
3. Double-check that `swift`'s sibling directories are present.
```sh
Expand All @@ -106,10 +107,10 @@ toolchain as a one-off, there are a couple of differences:
Detailed branching information, including names for release branches, can
be found in [Branches.md](/docs/Branches.md).

**Note:**
The commands used in the rest of this guide assumes that the absolute path
to your working directory is something like `/path/to/swift-project/swift`.
Double-check that running `pwd` prints a path ending with `swift`.
> **Note**
> The commands used in the rest of this guide assumes that the absolute path
> to your working directory is something like `/path/to/swift-project/swift`.
> Double-check that running `pwd` prints a path ending with `swift`.

[uploaded your SSH keys to GitHub]: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/

Expand Down Expand Up @@ -145,7 +146,6 @@ Double-check that running `pwd` prints a path ending with `swift`.
[Xcode]: https://developer.apple.com/xcode/resources/
[CMake]: https://cmake.org
[Ninja]: https://ninja-build.org
[Sccache]: https://github.com/mozilla/sccache
[Homebrew]: https://brew.sh/
[Homebrew Bundle]: https://github.com/Homebrew/homebrew-bundle

Expand All @@ -157,33 +157,38 @@ Double-check that running `pwd` prints a path ending with `swift`.
* [CentOS 7](https://github.com/apple/swift-docker/blob/main/swift-ci/master/centos/7/Dockerfile)
* [Amazon Linux 2](https://github.com/apple/swift-docker/blob/main/swift-ci/master/amazon-linux/2/Dockerfile)

2. To install `sccache` (optional):
* If you're not building within a Docker container:
```
sudo snap install sccache --candidate --classic
```
* If you're building within a Docker container, you'll have to install `sccache` manually, since [`snap`
is not available in environments without `systemd`](https://unix.stackexchange.com/questions/541230/do-snaps-require-systemd):
2. To install [Sccache][] (optional):
* If you're not building within a Docker container:
```sh
sudo snap install sccache --candidate --classic
```
* If you're building within a Docker container, you'll have to install
`sccache` manually, since [`snap` is not available in environments
without `systemd`](https://unix.stackexchange.com/questions/541230/do-snaps-require-systemd):

```
SCCACHE_VERSION=v0.3.0
curl -L "https://github.com/mozilla/sccache/releases/download/${SCCACHE_VERSION}/sccache-${SCCACHE_VERSION}-$(uname -m)-unknown-linux-musl.tar.gz" -o sccache.tar.gz
tar xzpvf sccache.tar.gz
sudo cp "sccache-${SCCACHE_VERSION}-$(uname -m)-unknown-linux-musl/sccache" /usr/local/bin
sudo chmod +x /usr/local/bin/sccache
```
```sh
SCCACHE_VERSION=v0.3.0
curl -L "https://github.com/mozilla/sccache/releases/download/${SCCACHE_VERSION}/sccache-${SCCACHE_VERSION}-$(uname -m)-unknown-linux-musl.tar.gz" -o sccache.tar.gz
tar xzpvf sccache.tar.gz
sudo cp "sccache-${SCCACHE_VERSION}-$(uname -m)-unknown-linux-musl/sccache" /usr/local/bin
sudo chmod +x /usr/local/bin/sccache
```

**Note:** LLDB currently requires at least `swig-1.3.40` but will
successfully build with version 2 shipped with Ubuntu.
> **Note**
> LLDB currently requires at least `swig-1.3.40` but will successfully build
> with version 2 shipped with Ubuntu.

[Sccache]: https://github.com/mozilla/sccache

## Building the project for the first time

### Spot check dependencies

* Run `cmake --version`: This should be 3.19.6 or higher.
* Run `python3 --version`: Check that this succeeds.
* Run `ninja --version`: Check that this succeeds.
* Run `sccache --version`: Check that this succeeds.
* Run `cmake --version`; this should be 3.19.6 or higher.
* Run `python3 --version`; check that this succeeds.
* Run `ninja --version`; check that this succeeds.
* If you installed and want to use Sccache: Run `sccache --version`; check
that this succeeds.

### The roles of different tools

Expand All @@ -206,6 +211,11 @@ to understand what the different tools do:
(i.e. do a "clean build"), Sccache can accelerate the new build
significantly. There are few things more satisfying than seeing Sccache
cut through build times.

> **Note**
> Sccache defaults to a cache size of 10GB, which is relatively small
> compared to build artifacts. You can bump it up, say, by setting
> `export SCCACHE_CACHE_SIZE="50G"` in your dotfile(s).
5. `utils/update-checkout` is a script to help you work with all the individual
git repositories together, instead of manually cloning/updating each one.
6. `utils/build-script` (we will introduce this shortly)
Expand All @@ -222,15 +232,7 @@ Phew, that's a lot to digest! Now let's proceed to the actual build itself!

### The actual build

1. Make sure you have Sccache running.
```sh
sccache --start-server
Copy link
Contributor

Choose a reason for hiding this comment

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

Is this not needed anymore?

Copy link
Collaborator Author

@AnthonyLatsis AnthonyLatsis Dec 3, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

build-script starts sccache for you if you pass --sccache (the invocation in the next step passes it).

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

We only pass it in the macOS invocation though. On Linux sccache is presented as optional. I should probably add a sentence suggesting to add this option to the Linux invocation if the reader chose to install sccache.

Copy link
Contributor

Choose a reason for hiding this comment

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

build-script starts sccache for you if you pass --sccache (the invocation in the next step passes it).

Ah ok, maybe I just couldn't find it then. To me we were only validating with --show-stats

I should probably add a sentence suggesting to add this option to the Linux invocation if the reader chose to install sccache.

Makes sense

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

To me we were only validating with --show-stats

I only just realized what you meant here. It happens --show-stats starts the server implicitly, so we’re covered.

```
(Optional) Sccache defaults to a cache size of 10GB, which is relatively
small compared to build artifacts. You can bump it up, say by setting
`export SCCACHE_CACHE_SIZE="50G"` in your dotfile(s). For more details,
see the [Sccache README][Sccache].
2. Build the toolchain with optimizations, debuginfo, and assertions, using
1. Build the toolchain with optimizations, debuginfo, and assertions, using
Ninja.
- macOS:
```sh
Expand All @@ -247,6 +249,8 @@ Phew, that's a lot to digest! Now let's proceed to the actual build itself!
utils/build-script --release-debuginfo --skip-early-swift-driver \
--skip-early-swiftsyntax
```
If you installed and want to use Sccache, include the `--sccache` option in
the invocation as well.

> **Note**
> If you aren't planning to edit the parts of the compiler that are written
Expand All @@ -256,7 +260,7 @@ Phew, that's a lot to digest! Now let's proceed to the actual build itself!
containing the Swift compiler and standard library and clang/LLVM build artifacts.
If the build fails, see [Troubleshooting build issues](#troubleshooting-build-issues).

> **Note:**
> **Note**
> `--release-debuginfo` means that although debug information will be produced, all targets will
> be compiled in release mode, meaning optimized code, which can affect your debugging experience.
> Consider [`--debug-swift` to build a debug variant of the compiler](#debugging-issues) and have
Expand Down