mirror of
https://github.com/apple/swift.git
synced 2025-12-14 20:36:38 +01:00
[docs] GettingStarted: Misc improvements to the Xcode setup instructions
This commit is contained in:
Anthony Latsis
@@ -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.
|
||||
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).
|
||||
|
||||
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 />
|
||||
> **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.
|
||||
|
||||
> **Warning**
|
||||
> Adding both `Swift.xcodeproj` and `LLVM.xcodeproj` *might* slow down the IDE
|
||||
and is not recommended unless you know what you're doing.
|
||||
* <p id="generate-xcode">
|
||||
Generate the Xcode project with
|
||||
|
||||
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.
|
||||
```sh
|
||||
utils/build-script --swift-darwin-supported-archs "$(uname -m)" --xcode --clean`.
|
||||
```
|
||||
|
||||
* 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 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.
|
||||
* 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.
|
||||
|
||||
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.
|
||||
#### Regenerating the Xcode project
|
||||
|
||||
> **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.
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user