# Improving \`GettingStarted.md\`

**URL:** <https://forums.swift.org/t/improving-gettingstarted-md/54871>\
**Category:** Compiler\
**Tags:** gardening\
**Created:** [January 26, 2022, 4:47pm UTC](https://forums.swift.org/t/improving-gettingstarted-md/54871 "2022-01-26T16:47:36Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![filip-sakel](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/filip-sakel/32/8697_2.png) [@filip-sakel](https://forums.swift.org/u/filip-sakel)\
**Post date:** [January 26, 2022, 4:47pm UTC](https://forums.swift.org/t/improving-gettingstarted-md/54871/1 "2022-01-26T16:47:36Z")

</div>

### TL;DR

New contributors are guided to `GettingStarted.md`, which encourages Mac users to use the poorly tested, and thus unreliable, `--xcode` flag. I recommend a change in this guide prompting **all** users to build with Ninja and offer guidance on editing with VS Code.

* * *

The [GettingStarted.md](https://github.com/apple/swift/blob/main/docs/HowToGuides/GettingStarted.md) guide urges new contributors working on Mac to use the `--xcode` flag. Unfortunately, the Xcode build system is not sufficiently tested in the CI, as evident by several [issues](https://forums.swift.org/t/help-building-swift-in-xcode-error/49728) from folks using this flag, and consistent build failures over the last couple of months from personal experience. This can lead new contributors to abandon hope of building the compiler, which is already a formidable endeavor given the compiler's sheer size.

Experienced [contributors](https://forums.swift.org/t/build-swift-error-using-unsupported-xcode-version/50049/4) usually use the more reliable Ninja build system, which, as the guide admits, is also faster. It is therefore sensible to spread this knowledge to people who are already lost by updating `GettingStarted.md`. This, though, could arguably deprive folks of autocomplete support, thus moving the configuration issues from setup to development.

Contributors using Windows or building with Ninja are not sufficiently guided on how to get started with an editor other than Xcode. The existing solution, Visual Studio, also takes up significant space on disk, which may discourage people already worried by the significant disk space required to build Swift. Some community members have thus used [VS Code](https://code.visualstudio.com) with the Microsoft C/C++ extension as a more lightweight solution to Xcode and Visual Studio alike.

Therefore, I propose that we update this guide to (1) remove the Xcode-build option and (2) add a comprehensive guide for setting up VS Code with autocomplete.

* * *

Past discussion: [Error building the compiler (even with ninja) - #3 by Max\_Desiatov](https://forums.swift.org/t/error-building-the-compiler-even-with-ninja/54834/3)

CC: @Max_Desiatov @benrimmington

---

<div class="post-metadata">

**Author:** ![benrimmington](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/benrimmington/32/695_2.png) [@benrimmington](https://forums.swift.org/u/benrimmington)\
**Post date:** [January 26, 2022, 11:15pm UTC](https://forums.swift.org/t/improving-gettingstarted-md/54871/2 "2022-01-26T23:15:48Z")

</div>

I wouldn't describe myself as an "experienced" contributor. I use an Xcode workspace or package to edit code; and `utils/build-script` or `utils/run-test` in the Terminal. I tried the `--xcode` flag once, but code completion stopped working after the first build. However, in the [survey](https://forums.swift.org/t/survey-how-do-you-build-swift/24826) from May 2019, there were a few people successfully using the `--xcode` flag.

---

<div class="post-metadata">

**Author:** ![filip-sakel](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/filip-sakel/32/8697_2.png) [@filip-sakel](https://forums.swift.org/u/filip-sakel)\
**Post date:** [January 27, 2022, 11:49am UTC](https://forums.swift.org/t/improving-gettingstarted-md/54871/3 "2022-01-27T11:49:07Z")

</div>

My solution was perhaps a bit too radical. Still, until this flag is properly tested, the guide should at least warn about its instability to people who haven't experienced it themselves.

---

<div class="post-metadata">

**Author:** ![suyashsrijan](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/suyashsrijan/32/5292_2.png) [@suyashsrijan](https://forums.swift.org/u/suyashsrijan)\
**Post date:** [January 27, 2022, 3:51pm UTC](https://forums.swift.org/t/improving-gettingstarted-md/54871/4 "2022-01-27T15:51:06Z")

</div>

I really liked using VS Code over Xcode, but later I switched to CLion which I found was far superior than Xcode and VS Code. It's paid though, but if you contribute regularly the license is probably worth it. Otherwise, VS Code does the job too. It could be worth adding steps to use CLion though for those who want to use it.

---

<div class="post-metadata">

**Author:** ![TiagoLopes](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/tiagolopes/32/15279_2.png) [@TiagoLopes](https://forums.swift.org/u/TiagoLopes)\
**Post date:** [March 21, 2022, 2:18pm UTC](https://forums.swift.org/t/improving-gettingstarted-md/54871/5 "2022-03-21T14:18:47Z")

</div>

@filip-sakel Do you have autocomplete, quick-look, and jump actions when using VSCode?

---

<div class="post-metadata">

**Author:** ![filip-sakel](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/filip-sakel/32/8697_2.png) [@filip-sakel](https://forums.swift.org/u/filip-sakel)\
**Post date:** [March 21, 2022, 2:25pm UTC](https://forums.swift.org/t/improving-gettingstarted-md/54871/6 "2022-03-21T14:25:23Z")

</div>

Most of the time, yes. I’ve pretty much had the same experience with Max [here](https://forums.swift.org/t/error-building-the-compiler-even-with-ninja/54834/6) following his configuration (outlined [here](https://forums.swift.org/t/error-building-the-compiler-even-with-ninja/54834/8)).

---

<div class="post-metadata">

**Author:** ![philipturner](https://avatars.discourse-cdn.com/v4/letter/p/b5e925/32.png) [@philipturner](https://forums.swift.org/u/philipturner)\
**Post date:** [April 25, 2022, 12:46am UTC](https://forums.swift.org/t/improving-gettingstarted-md/54871/7 "2022-04-25T00:46:14Z")

</div>

The reason to use Xcode to compile the Swift compiler is mostly to use LLDB in an interactive environment, where you can see the stack trace and code files in real-time. I use "jump to definition" and breakpoints heavily when solving an entrenched AutoDiff bug, which is much faster than using the GitHub search engine. For small patches or for bisecting the massive commit history, Ninja is much faster for building. Honestly, all you would really need to do for this VS Code plugin is support jump actions and a debugger equivalent to LLDB. Autocomplete and quick-look could be left out of the initial version.

---

<div class="post-metadata">

**Author:** ![Max\_Desiatov](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/max_desiatov/32/20654_2.png) [@Max\_Desiatov](https://forums.swift.org/u/Max_Desiatov)\
**Post date:** [April 25, 2022, 10:08am UTC](https://forums.swift.org/t/improving-gettingstarted-md/54871/8 "2022-04-25T10:08:20Z")

</div>

Last time I tried, [CodeLLDB](https://github.com/vadimcn/vscode-lldb) extension worked pretty well for me in VS Code, and I was able to freely step through invocations in C++ source code. [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) extension works pretty well for "jump to definition" and autocomplete. Arguably, I find that autocomplete and navigation across definitions are much more responsive (most of the time it's immediate) with this extension than Xcode.

I'm going to add links to these extensions to `GettingStarted.md`.
