Improving `GettingStarted.md`

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 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 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 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 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

CC: @Max_Desiatov @benrimmington

7 Likes

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 from May 2019, there were a few people successfully using the --xcode flag.

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.

3 Likes

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.

2 Likes

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

Most of the time, yes. I’ve pretty much had the same experience with Max here following his configuration (outlined here).

1 Like

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.

Last time I tried, CodeLLDB extension worked pretty well for me in VS Code, and I was able to freely step through invocations in C++ source code. C/C++ 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.

3 Likes