Thanks for that feedback. I was hoping that the Windows instructions would be sufficient for the explanation of what was going on. The split of the components is intentional as I believe that it provides better building blocks (the pieces are setup to be composed into a final image). The desired break down is as follows:
- toolchain: the actual tools needed to compile C/C++/Swift code and inspect binaries (e.g. clang, swiftc, lld)
- sdk: the Swift supplemental content needed to build software for a platform (e.g. Windows, Android, Linux)
- developer tools: tools needed to write software (e.g. llbuild, s-p-m, SourceKit-LSP)
Currently, the last component is not available, but, I hope to add that to the builds (although some part of the build does exist currently).
You would need at least the first two items for writing Swift code.
The first item - toolchain - needs to be for the machine that you are going to be working on (currently, Windows x64 or Linux x64; Windows arm64 is experimental).
You additionally need the SDK for the platform you are building for (currently one of Windows, Android, or Linux). There is some discussion going on at Swift Linux layout considerations (aka Linux is difficult, lets go shopping) about how to deal with multiple architectures for these platforms. With the patch which led to that thread, it is possible to have these SDKs be relocatable wherever you like - you just pass along some flags to the compiler to identify where they are stored.
Finally, I suspect is the piece that most people claim is absolutely required: the developer tools. This is currently under development still and includes items for the developer not the final product. These are tied to the machine that you are building on again (just like the toolchain). It would include tools like s-p-m and SourceKit-LSP.
Why devtools is split out
The reason to split out the developer tools like this is two fold. First of all, these are high level tools which are written in Swift, and as such need the SDK to be prepared for the host, before they are usable (that is, we need the previous component for Windows before we can build these tools for Windows). Second of all, they are not part of the core toolchain, but really part of the IDE experience.
My long term vision (plan?) is to actually get the developer tools stable and then try to construct a single VSCode build which has the toolchain and devtools pre-packaged and configured. You would just add the SDK for the platform that you wish to target and can start developing :-). It should be possible to actually have a plugin in VSCode which would download the tools (much like how Xcode downloads the simulator images or Android Studio downloads pieces).
Each one of these layers is built upon the previous and it takes time to ensure that the base is solid enough to support that. I have been slowly moving through the strata building up the infrastructure to make that possible. In the mean time, I have been simultaneously trying to make all the pieces entirely relocatable, which makes it easier for others to actually experiment with the artifacts that are being published.
If the current documentation on the getting started workflow is not sufficient, I would love to have some patches to improve them and make them clearer for others. I am trying to find a way to lower the bar for others to use Swift on the platform of their choice (both for writing and running). If there are pieces which I have overlooked in the short term, I would be open to trying to smooth those out in a way that makes sense for the longer term.