Build System Release Notes for Xcode 10

Update your apps to use new features, and test your apps against changes.


Xcode 10 uses a new build system. The new build system provides improved reliability and build performance, and it catches project configuration problems that the legacy build system does not.

Although the new build system is highly compatible with existing projects, some projects may require changes due to the following:

  • The new build system has stricter checks for cycles between elements in the build in order to prevent unnecessary rebuilds.

  • It is an error for any individual file in the build to be produced by more than one build command. For example, if two targets each declare the same output file from a shell script phase, factor out the declaration of the output file into a single target.

  • If an output file which is generated by a shell script is used as an input elsewhere in the build (for example, to another shell script), then that output must be declared as an explicit output by the script that generates it; otherwise the build system may attempt to search for the file before it has been generated, causing the build to fail.

  • The legacy header map that was generated when the Always Search User Paths (ALWAYS_SEARCH_USER_PATHS) setting was YES is not supported by the new build system. Instead, set ALWAYS_SEARCH_USER_PATHS to NO and migrate to using modern header include syntax. Add any needed header files that are in the project repository to the Xcode project to ensure they are available for use in #include (via the project wide header map). Use quote-style include ("example.h") for project headers, and reserve angle-bracket include (<example.h>) for system headers.

  • The new build system passes undefined_arch as the value for the ARCH environment variable when running shell script build phases. The value was previously not well defined. Any shell scripts depending on this value must behave correctly for all defined architectures being built, available via the ARCHS environment variable.

  • The new build system uses the "clean build folder" behavior. The legacy "clean" behavior is not supported.

More details on resolving issues that the new build system detects can be found in Xcode Help.

If you need it, the legacy build system is still available in Xcode 10. To use the legacy build system, select it in the File > Project/Workspace Settings sheet. Projects configured to use the legacy build system will display an orange hammer icon in the Activity View.

New Features

  • When an .xcconfig file contains multiple assignments of the same build setting, later assignments using using $(inherited) or $(<setting_name>) will inherit from earlier assignments in the .xcconfig. The legacy build system caused every use of $(inherited) or $(<setting_name>) skip any other values defined within the .xcconfig. To detect whether your .xcconfig is affected by this improvement, run defaults write EnableCompatibilityWarningsForXCBuildTransition -bool YES in Terminal to cause Xcode to generate a warning about this situation. (40283621)

  • While a target is performing post-compilation build steps, such as linking and code signing, Xcode's new build system will begin compiling sources from targets that depend on that target, to improve build speed by using more of your available processor cores. This compilation will not start until any "Run Script" phases from the target have completed. (38772619)

  • Xcode provides improved warnings and errors for dependency cycles and other build issues detected by Xcode's new build system. (37370377)

  • In the new build system, shell scripts can't rely on the state of build artifacts not listed in other build phases (for example, the Info.plist file or .dSYM files.) Add files the script build phase depends on as explicit input dependencies to the shell script build phase. (40852184)

  • Run Script build phases now support declaring input and output files in a .xcfilelist file. This file should contain a newline-seperated list of the file paths for the inputs or outputs. Build setting references may be used in these paths. The path to a copy of the .xcfilelist file with resolved build setting references will be provided in the SCRIPT_INPUT_FILE_LIST_(#) and SCRIPT_OUTPUT_FILE_LIST_(#) environment variables of the Run Script phase. Projects which use an .xcfilelist require Xcode 10. (39241255)

  • A new Product > Perform Action > Build With Timing Summary command produces a build log with statistics about the aggregate time taken by each command in the build. These timings aid in analyzing the time taken by the build. (40069871)

  • When using the new build system, only build settings with a non-empty value are exported to shell script build phases and build rules. A build setting set to an empty value is treated the same as one which isn't set at all by both build systems. (40843445)

Known Issues

  • Incremental builds to may fail to codesign properly for non-source related changes to your project, such as resource file modifications, which can result in the app failing to launch. (41254808)

    Workaround: Change a source file within the same target to trigger the codesign process, or perform a clean build.

  • After installing a Swift toolchain, Xcode won't immediately detect the toolchain. (31360319)

    Workaround: Close and reopen the workspace.

  • The new build system doesn't support On Demand Resources (ODR). If your project uses ODR, the legacy build system can be reenabled in File > Workspace/Project Settings. (31508570)

  • When build settings are defined in an xcconfig file that inherit values using $(inherited) or $(<setting_name>), the Build Settings editor shows the last assigned value for the setting instead of the properly composed value. (28572636)

  • Targets which have multiple asset catalogs that aren't in the same build phase may produce an error regarding a "duplicate output file". (39810274)

    Workaround: Ensure that all asset catalogs are processed by the same build phase in the target.

  • The new "Build with Timing Summary" command doesn't show timings for some tasks run within the build system during the build. (39801746)

  • Custom build system plugins—including the Intel ICC compiler—are not yet supported. (32795438, 33286594)

    Workaround: If required, switch to using the legacy build system in the File > Project/Workspace Settings sheet.

  • Targets with Copy Headers build phases ordered after Compile Sources build phases may fail to build and emit a diagnostic regarding build cycles. (39880168)

    Workaround: Arrange any Copy Headers build phases before Compile Sources build phases.

  • When performing xcodebuild clean on a project that uses a customized build location outside the derived data directory, and that has older build products produced prior to Xcode 10, Xcode might report an error indicating that it won't delete directories not created by the new build system. (40427159)

    Workaround: Delete the build folder manually.

Resolved Issues

  • Localized .strings files which are encoded using UTF-16 and don't have an explicit encoding selected in the Xcode project file will now build. (41902162)

  • When a target that contains Swift code adds a new dependency on a Swift system library, Xcode will copy that runtime library into the app. (40456595)

  • Improved the performance of incremental builds with the new build system. (28580112)

  • Dependencies for Swift applications are properly tracked including CopySwiftLibs for test targets. (42285144)

  • watchOS targets might fail to install due to misconfigured project settings. Please check the VALID_ARCHS for watchOS targets to ensure they're correct. (40531052)

  • Copying a read-only file won't cause the build to fail with an error. (41813879)

  • The new build system supports build setting expansions in the advanced build location options found in Location Preferences or Project Settings. (40236969)

  • Output from shell script build phases displays in the build log. (40492041)

  • The "Clean Build Folder" command will clear errors and warnings. (39659924)

See Also

Release Notes

Interface Builder Release Notes for Xcode 10

Update your apps to use new features, and test your apps against changes.

Source Editor Release Notes for Xcode 10

Update your programming workflow to use new features, and test your workflow against changes.

Swift 4.2 Release Notes for Xcode 10

Update your code to use new language features and test your apps against changes.