Migrating to Swift 4.2

Xcode 10.0 comes with a Swift Migrator tool that helps you migrate your project to Swift 4.2.

For the previous release’s Migration Guide, see Migrating to Swift 4.

Pre-Migration Preparation

Make sure that the project that you intend to migrate builds successfully in Swift 3 or Swift 4 mode, and all its tests pass. You may need to resolve errors initially due to compiler changes.

It’s highly recommended to have your project managed under source control. This will allow you to easily review the changes that were applied via the migration assistant and to discard them and re-try the migration if needed.

You decide when and if you’d like to migrate on a per-target basis when it makes sense for your project. While migrating to Swift 4.2 is definitely encouraged, it’s not an all-or-nothing process, as Swift 3, 4, and 4.2 targets can coexist and link together.

The migration assistant does a migrator build to gather the changes, using the scheme you have selected, so the targets that will get processed are the ones that are included in the scheme. To review and modify what is included in the scheme, invoke the Edit Scheme… sheet and select the Build tab from the column on the left, and make sure all your targets and their unit tests are included.

If your project depends on other open-source projects that are provided by Carthage or CocoaPods, consult the Using Carthage/CocoaPods Projects section.

Swift Migration Assistant

When you open your project with Xcode 10 for the first time, you will see a migration opportunity item in the Issue Navigator: click it to activate a sheet asking you if you’d like to migrate. You can be reminded later or invoke the Migrator manually from the menu Edit -> Convert -> To Current Swift Syntax…

You will be presented with a list of targets to migrate. Targets that do not contain any Swift code will not be selected.

If all your selected targets are in Swift 4 mode there is only one migration workflow, but for Swift 3 targets there is a choice between two kinds of @objc Inference:

For more information and implications of these two choices, see the Xcode Help article Migrate to Swift 4 @objc inference.

Clicking Next will bring up the Generate Preview sheet and the assistant will initiate a migration build to get source changes. When this is done, you will be presented with all the changes that will be applied once you click on ‘Save’. This will also change the Swift Language Version build setting for the migrated targets to Swift 4.2.

There may have been issues with processing the targets that will negatively impact the migration process. Switch to the Report Navigator and select the Convert entry that was added; this is the conversion build log. Check the log for errors that may have showed up.

If you see errors about not being able to code-sign the target, try disabling code-signing from the build settings of the target. If you see other errors, please file a bug report and include the details. You are strongly encouraged to attach a project that illustrates the faulty migration if possible.

Swift 4.2 Migration Changes Overview

The vast majority of changes that the Migrator suggests comes from data generated by a comparison of the previous SDK and the current SDK, which may drive renaming of identifiers and types, for example; and from normal compiler fix-its.

The most prevalent SDK changes are moving global constants into static type properties and transforming string constants into Swift enumeration cases. These are handled automatically by the Migrator.

If you migrate from Swift 3 code, also see the migration changes overview from last year’s migrator from Migrating to Swift 4.

After Migration

While the migrator will take care of many mechanical changes for you, it is likely that you will need to make more manual changes to be able to build the project after applying the migrator changes.

You may see compiler errors that have associated fixits; while the migrator is designed to incorporate fixits that the Swift 4 compiler provides, some fixits may not be applied if they are not applicable 100% of the time.

Even if it compiles fine, the code that the migrator provided may not be ideal. Use your best judgement and check that the changes are appropriate for your project.

See Known Migration Issues section, for a list of issues that you may encounter while trying to migrate your project.

Known Migration Issues



Using Carthage/CocoaPods Projects

Here are some important points to consider when migrating a project with external dependencies using package managers like Carthage, CocoaPods, or the Swift Package Manager.