Merge pull request #62371 from AnthonyLatsis/wakamole

GettingStarted.md: A sprinkle of minor improvements

Author: AnthonyLatsis

docs/HowToGuides/GettingStarted.md

@@ -84,9 +84,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
@@ -109,10 +110,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/
 
@@ -148,7 +149,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
 
@@ -160,33 +160,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
 
@@ -209,6 +214,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)
@@ -225,15 +235,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
-   ```
-   (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
@@ -250,6 +252,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
@@ -259,7 +263,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