17 Feb 20205 min read

Managing toolchains in Xcode

Swift development isn't slowing down in any way new versions are being released a few times a year. New releases do not only contain some minor fixes and improvements but we also often get some new features as well. Most important, however, we want to prepare our applications for a new Swift version. Even though we, developers, are not forced to use the newest Swift version right away when it is released it might be still good to be ready for it. Especially if your application depends on some third party frameworks since those will rather sooner than later be updated to support the new Swift version. Usually, we can compile them anyway with backward compatibility by setting older Swift versions for that framework but sometimes the new version of Swift brings a great addition that it is just too good not to use that.

How can we give a new Swift version that has not been released with the latest available Xcode yet? Or maybe you are short on free disk space (sooner or later we all know that feeling I think 😭) and do not want to install a new version of Xcode yet? Toolchains take way less space (around 2-3 GB) compared to Xcode... version 11.3 of Xcode is now like 16 GB? That's quite a lot and having like 2 or even 3 versions of Xcode installed might not be possible for some of us, especially if one uses his MacBook not just for single project development but also for some other stuff as well.

Xcode comes by default with the latest stable toolchain release of the Swift, thankfully it supports using alternative toolchains instead of default one out of the box. All we have to do is install the alternative toolchain that is available to download from swift.org website.

Just keep in mind that to submit your application to the App Store you must build it using the version of Swift that comes included within Xcode - using default toolchain that is. But it might be still worth installing...

Everyone that has tried SwiftUI has probably noticed how hard it is sometimes to find an issue with our code as the error messages are misleading most of the time. So if you haven't given up on it yet and can't wait for the new diagnostics why not give it a try right now?

Installing alternative Toolchain

From the official Swift website we can download snapshots from the master branch which are rather not recommended for our daily development as they have not gone through the full testing that is performed for official releases.

The better option would be more stable snapshots that come from branch for a specified swift version. For the moment of writing this article, it would be 5.2 snapshots.

Just download the chosen toolchain package and simply follow the installer steps. We can choose to install alternative toolchains into one of the two locations:

Right after installing a new toolchain you will notice a new submenu under the Xcode menu where you can easily change the currently enabled toolchain.

Toolchains submenu

You can also see installed alternative toolchains under Toolchains pane of Components preferences in Xcode as you can see in the image below. You can also choose which toolchain you want to use as well as validate its signature or remove it. There is no way to remove the default toolchain.

Toolchains in Components

When an alternative toolchain is chosen you will notice an icon in the activity view in the Workspace toolbar. Once enabled, Xcode will use the selected custom toolchain for building your project's swift code as well as for debugging, syntax coloring and code completion.

Alternative Toolchain indicator

Custom toolchain from the command line

Enabling alternative toolchain with the above methods affects Xcode only, so if you use xcodebuild or ie. a Fastlane to build your project, it will still use the default toolchain (the one from the currently selected Xcode).

You can check currently selected toolchain with this command

swift --version

it should print something similar to this:

Apple Swift version 5.1.3 (swiftlang-1100.0.282.1 clang-1100.0.33.15)
Target: x86_64-apple-darwin19.3.0

To use the alternative toolchain you can run xcrun and xcodebuild with a -toolchain flag like this:

xcodebuild -toolchain NAME
xcrun --toolchain NAME

where NAME is either an identifier or name of the toolchain, ie. xcodebuild --toolchain swift.

You could also export it to your current terminal session with a command:

export TOOLCHAINS=swift

or if you want to keep the alternative toolchain for all terminal sessions you can add it to your PATH

export PATH=/Library/Developer/Toolchains/swift-latest.xctoolchain/usr/bin:"${PATH}"


So today we learned how to use alternative toolchains in both Xcode and command line. You could also setup CI to use custom one to be one step ahead and test your frameworks and applications against new Swift versions. Also, if you would like to contribute to Swift repository, you can build your toolchain snapshots to test your changes.

While installing and using alternative toolchains you must be also aware that it might be unstable and it might be incompatible with the Xcode version you are using.

I hope you might find this article useful. If you enjoy my articles, please follow me on Twitter and thank you for reading!