Merge pull request swiftlang#68514 from AnthonyLatsis/xcode-workflow

[docs] GettingStarted: Misc improvements to the Xcode setup instructions

Author: AnthonyLatsis

docs/HowToGuides/GettingStarted.md

@@ -25,6 +25,8 @@ toolchain as a one-off, there are a couple of differences:
 - [Editing code](#editing-code)
   - [Setting up your fork](#setting-up-your-fork)
   - [Using Ninja with Xcode](#using-ninja-with-xcode)
+    - [Regenerating the Xcode project](#regenerating-the-xcode-project)
+    - [Troubleshooting editing issues in Xcode](#troubleshooting-editing-issues-in-xcode)
   - [Other IDEs setup](#other-ides-setup)
   - [Editing](#editing)
   - [Incremental builds with Ninja](#incremental-builds-with-ninja)
@@ -280,7 +282,7 @@ Phew, that's a lot to digest! Now let's proceed to the actual build itself!
    > **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 
+   > Consider [`--debug-swift` to build a debug variant of the compiler](#debugging-issues) and have
    > the swift targets (including `swift-frontend`) built in debug mode.
 
    If you would like to additionally build the Swift corelibs,
@@ -365,78 +367,77 @@ whenever the heading is modified.
 -->
 ### Using Ninja with Xcode
 
-This workflow enables you to navigate, edit, build, run, and debug in Xcode
-while retaining the option of building with Ninja on the command line.
-
-Assuming that you have already [built the toolchain via Ninja](#the-actual-build),
-several more steps are necessary to set up this environment:
-* Generate Xcode projects with `utils/build-script --swift-darwin-supported-archs "$(uname -m)" --xcode --clean`.
-  This will first build a few LLVM files that are needed to configure the
-  projects.
-* Create a new Xcode workspace.
-* Add the generated Xcode projects or Swift packages that are relevant to your
-  tasks to your workspace. All the Xcode projects can be found among the
-  build artifacts under `build/Xcode-*/`. For example:
-  * If you are aiming for the compiler, add `build/Xcode-*/swift-macosx-*/Swift.xcodeproj`.
-    This project also includes the standard library and runtime sources. If you
-    need the parts of the compiler that are implemented in Swift itself, add the
-    `swift/SwiftCompilerSources/Package.swift` package as well.
-  * If you are aiming for just the standard library or runtime, add
-    `build/Xcode-*/swift-macosx-*/stdlib/Swift-stdlib.xcodeproj`.
-  <!-- FIXME: Without this "hard" line break, the note doesn’t get properly spaced from the bullet -->
-  <br />
-
-  > **Warning**  
-  > Adding both `Swift.xcodeproj` and `LLVM.xcodeproj` *might* slow down the IDE
-    and is not recommended unless you know what you're doing.
-
-  In general, we encourage you to add only what you need. Keep in mind that none
-  of the generated Xcode projects are required to build or run with this setup
-  because we are using Ninja—an *external* build system; rather, they should be
-  viewed as a means of leveraging the navigation, editing and debugging features
-  of the IDE in relation to the source code they wrap.
-
-* Create an empty Xcode project in the workspace, using the
-  _External Build System_ template.
-* Add a target to the empty project, using the _External Build System_ template,
-  and name it after the Ninja target that you want to build (e.g. `swift-frontend`
-  is the compiler).
+This workflow enables you to edit, build, run, and debug in Xcode. The
+following steps assume that you have already [built the toolchain with Ninja](#the-actual-build).
+
+> **Note**  
+> A seamless LLDB debugging experience requires that your `build-script`
+  invocation for Ninja is tuned to produce build rules for the
+  [debug variant](#debugging-issues) of the component you intend to debug.
+
+* <p id="generate-xcode">
+  Generate the Xcode project with
+
+  ```sh
+  utils/build-script --swift-darwin-supported-archs "$(uname -m)" --xcode --clean`.
+  ```
+
+  This can take a few minutes due to metaprogrammed sources that depend on LLVM
+  tools that are built from source.
+  </p>
+* Create an empty Xcode workspace.
+* Add `build/Xcode-*/swift-macosx-*/Swift.xcodeproj` to the workspace. If Xcode
+  prompts to autocreate schemes, select *Manually Manage Schemes* and don't
+  create any schemes just yet.
+
+  This project includes the sources for almost everything in the repository,
+  including the compiler, standard library and runtime. If you intend to work on
+  a compiler subcomponent that is written in Swift and has a `Package.swift`
+  file (e.g. `lib/ASTGen`), first choose *Product > Scheme > Manage Schemes...*
+  and select the *Autocreate schemes* checkbox, then add the package directory
+  to the workspace by choosing *File > Add Files to "\<workspace name>"*. Xcode
+  will automatically create schemes for package manifest.
+* Create an Xcode project using the _External Build System_ template, and add
+  it to the workspace.
+* Create a target in the new project, using the _External Build System_
+  template.
 * In the _Info_ pane of the target settings, set
   * _Build Tool_ to the absolute path of the `ninja` executable (the output of
     `which ninja` on the command line)
-  * _Arguments_ to the Ninja target (e.g. `bin/swift-frontend`)
-  * _Directory_ to the absolute path of the build directory where the Ninja
-    target lives. For Swift targets such as the compiler or standard library,
-    this is the `build/Ninja-*/swift-macosx-*` directory.
-* Add a scheme for the target. In the drop-down menu, be careful not to mistake
-  your target for a similar one that belongs to a generated Xcode project.
-* > **Note**  
-  > Ignore this step if the target associates to a non-executable Ninja target
-    like `swift-stdlib`.
-
-  Adjust the _Run_ action settings of the scheme:
-  * In the _Info_ pane, select the _Executable_ built by the Ninja target from
-    the appropriate `bin` directory (e.g. `build/Ninja-*/swift-macosx-*/bin/swift-frontend`).
-  * In the _Arguments_ pane, add the command line arguments that you want to
-    pass to the executable on launch (e.g. `path/to/file.swift -typecheck` for
+  * _Arguments_ to a Ninja target (e.g. `bin/swift-frontend`, the compiler)
+  * _Directory_ to the absolute path of the `build/Ninja-*/swift-macosx-*`
+    directory
+* Create a scheme in the workspace, making sure to select the target you just
+  created. Be *extra* careful not to choose a target from the generated Xcode
+  project you added to the workspace.
+* Spot-check your target in the settings for the _Build_ scheme action.
+* If the target is executable, adjust the settings for the _Run_ scheme action:
+  * In the _Info_ pane, select the _Executable_ produced by the Ninja target
+    from `build/Ninja-*/swift-macosx-*/bin` (e.g. `swift-frontend`).
+  * In the _Arguments_ pane, add command line arguments that you want to pass to
+    the executable on launch (e.g. `path/to/file.swift -typecheck` for
     `bin/swift-frontend`).
-  * You can optionally set the working directory for debugging in the
-    _Options_ pane.
-* Configure as many more target-scheme pairs as you need.
-
-Now you are all set! You can build, run and debug as with a native Xcode
-project. If an `update-checkout` routine or a structural change—such as when
-source files are added or deleted—happens to impact your editing experience,
-simply regenerate the Xcode projects.
-
-> **Note**  
-> * For debugging to *fully* work for a given component—say, the compiler—the
-    `build-script` invocation for the Ninja build must be arranged to
-    [build a debug variant of that component](#debugging-issues).
-> * Xcode's indexing can occasionally start slipping after switching to and back
-    from a distant branch, resulting in a noticeable slowdown. To sort things
-    out, close the workspace and delete the _Index_ directory from the
-    workspace's derived data before reopening.
+  * Optionally set a custom working directory in the _Options_ pane.
+* Follow the previous steps to create more targets and schemes per your line
+  of work.
+
+#### Regenerating the Xcode project
+
+The structure of the generated Xcode project is distinct from the underlying
+organization of the files on disk, and does not adapt to changes in the file
+system, such as file/directory additions/deletions/renames. Over the course of
+multiple `update-checkout` rounds, the resulting divergence is likely to begin
+affecting your editing experience. To fix this, regenerate the project by
+running the invocation from the <a href="#generate-xcode">first step</a>.
+
+#### Troubleshooting editing issues in Xcode
+
+* If a syntax highlighting or code action issue does not resolve itself after
+  regenerating the Xcode project, select a scheme that covers the affected area
+  and try *Product > Analyze*.
+* Xcode has been seen to sometimes get stuck on indexing after switching back
+  and forth between distant branches. To sort things out, close the workspace
+  and delete the _Index_ directory from its derived data.
 
 ### Other IDEs setup