Xcode - New build system explained

In the year 2017, Apple released the new build system with Xcode 9 in preview mode. One of the Swift engineers also tweeted about the experimental feature.
This indicated that something new with swift build system was being cooked. While it smelled delicious at the time but honestly it was broken for a long time (no offense :p) and Apple was finally able to release it with Xcode 10 in the year 2018.

That's about history let's dig deeper and find out what it does.

What is the Xcode new build system?

The brand new build system was written from scratch with the sole purpose of making swift builds faster. With the legacy build system, swift projects were a bit slow to compile. The new build system promised to improve swift build performance and dependency management.

Benefits of the new build system

It's strange Apple never talked about this in-depth at any of the WWDC events. I remember the WWDC event where it was introduced, that whole new build system was explained in 40 seconds. And that's the reason there aren't many blogs/articles explaining the new build system.

According to the official documentation, the new build system provides the following advantages:
  • It provides higher reliability.
  • Catches many project configuration problems.
  • Improves overall build-system performance

How to enable the new build system?

1. From Xcode

Goto File -> Project Settings and choose the new build system.

2. Command Line

You can pass the flag 'UseNewBuildSystem=YES' which enables the command-line tool to build the project using the new build system.

3. Using Flag

As per the tweet embedded at the starting of this post, it can also be enabled by setting the flag 'BuildSystemScheduleInherentlyParallelCommandsExclusively' to 'NO'.

$ defaults write com.apple.dt.Xcode BuildSystemScheduleInherentlyParallelCommandsExclusively -bool NO

How does the new build system improve build performance?

When you will enable the new build system in your project and check the difference in your project file, you will see only one difference about a flag's value being changed. So, How does it improve build performance?

Well, Apple seems to have built a framework called XCBuild.framework on top of the apple llvm and ships it with the Xcode, that's where the whole magic happens.

You can find the new framework in /Applications/Xcode.app/Contents/SharedFrameworks/XCBuild.framework/

In case, you want to dig deeper and see what API's this framework exposes. you can go to the directory '/Applications/Xcode.app/Contents/SharedFrameworks/XCBuild.framework/Versions/A/Support/xcbuild' and run 'nm xcbuild' in the terminal, this will show you the symbol tables that this framework expose.

Issues with the new build system

It's been two years since the release of the new build system and yet there are a lot of issues with the system:

1. Issues with Info.plist

If you are using the new build system make sure that plists are not added in the copy bundle resource. The system will not be able to build if files are copied multiple times in the app.

2. Cocoapods

With Cocoapods, if you are using framework in development mode you won't be able to see the changes until you clean build the project. There are many workarounds available for this but I am not discussing here as it bypasses the scope of the article.

3. Issues with the Run Script

Xcode build system tried to run some tasks in parallel and if the input for the run script phase hasn’t been generated then the build system gets confused and fails. It’s always a good idea to provide the input files to the run scripts wherever applicable.

4. Clean build folder action

Xcode 10 introduced a new method to clean the project called 'Clean build folder' which cleans the derived data folder for the project, this means that the project will rebuild all the framework if you are using Cocoapod. This can be bad and can consume a lot of build time for clean builds.

5. Issues with Xcconfig files

The conditional variable assignments in the xcconfig files might not work as expected with the new build system. In order to check the xcconfig files, Apple suggests using the following command

$ defaults write com.apple.dt.XCBuild EnableCompatibilityWarningsForXCBuildTransition -bool YES


After Xcode 10, the new build system is enabled by default. But it completely depends on your project structure whether it's useful for you or not. For most of the projects, it 
decreased the build time by almost 5-10%. 

you can always experiment with your project and find out what works best for you. For the project settings, it's all about what combinations you use. Try to play with the settings and find out what works for your project. 

I'll be posting a separate article soon for all the settings you can play with to reduce the project's build time, stay tuned, and happy reading. 


Post a Comment