Swift.org - Library Evolution in Swift

Module stability allows Swift modules built with different compiler versions to be used together in one app.

Library evolution support allows developers of binary frameworks to make additive changes to the API of their framework while remaining binary compatible with previous versions.

When to enable library evolution support

Enabling library evolution support

Xcode

Directly invoking the compiler

$ swiftc Tack.swift Barn.swift Hay.swift \
    -module-name Horse \
    -emit-module -emit-library -emit-module-interface \
    -enable-library-evolution

Library evolution model

All public declarations are ABI-public.

Declarations annotated with the @usableFromInline attribute are ABI-public, but not public in the source language; this means they can be referenced from @inlinable code, but not directly from source. This special attribute is discussed in more detail later.

Examples of resilient changes

A general principle is that ABI-private declarations (per the above definition) can be added, removed and changed oh a whim. Only what is explicitly declared to be ABI-public becomes part of the framework’s binary interface.

Top-level declarations in a source file can be re-ordered, and moved between source files in the same framework. Members inside a type or extension can be re-ordered, with the exception of stored properties and enum cases in structs and enums declared @frozen, respectively.
For example, in the following, we have a top-level function, followed by a class with two methods. The function and the class can appear in any order, and the two methods inside the class can be re-ordered without breaking binary compatibility:

public func sum<T : Sequence>(_ seq: T) -> Int
      where T.Element == Int {
    return array.reduce(0, (+))
  }

  open class NetworkHandle {
    open func open() {}
    open func close() {}
  }

This could instead have been written with the two top-level declarations reversed without any impact on the ABI of the framework:

// The declarations of NetworkHandle and sum have been reordered.
  // This does NOT have any impact on the binary interface of
  // of the framework.
  open class NetworkHandle {
    open func open() {}
    open func close() {}
  }

  public func sum<T : Sequence>(_ seq: T) -> Int
      where T.Element == Int {
    return array.reduce(0, (+))
  }

In constrast, in the following @frozen enum definition, the two case declarations cannot be re-ordered, but the two methods can. Further, the relative ordering of the methods and the cases can change:

@frozen public enum Shape {
    // These cases of an @frozen enum cannot be reordered.
    // The order of the cases with repect to each other
    // is part of the framework's binary interface.
    case rect(w: Int, h: Int)
    case circle(radius: Int)
  
    // The order that these methods are declared
    // can be reordered. Their ordering is NOT
    // part of the framework's binary interface.
    public func area() -> Int {...}
    public func circumference() -> Int {...}
  }

Declarations can be added at the top level of a source file.

Members can be added to class, struct and enum types as long as the container type is not declared @frozen. If the type is @frozen, stored properties or enum cases cannot be added. Any other kind of member can be added without restriction.

An immutable property can become mutable. The binary interface to a property is a set of accessor functions, so introducing mutability is equivalent to adding a new declaration – the setter.
For example, suppose we have a struct defining a read-only computed property fahrenheit:

public struct Temperature {
  public var celsius: Int
  public var fahrenheit: Int { (celsius * 9) / 5 + 32 }
}

A new version of the library could add a setter to fahrenheit:

public struct Temperature {
    public var celsius: Int
    public var fahrenheit: Int {
      get { (celsius * 9) / 5 + 32 }
      set { celsius = ((newValue - 32) * 5) / 9 }
    }
  }

New protocol requirements can be added to protocols, as long as the new requirement has a default implementation defined in a protocol extension.
For example, let’s say we have a PointLike protocol:

public protocol PointLike {
  var x: Int { get }
  var y: Int { get }
}

A new version of the library could add a new property requirement z to the protocol, with a default implementation returning 0:

public protocol PointLike {
  var x: Int { get }
  var y: Int { get }
  var z: Int { get }
}

extension PointLike {
  public var z: Int { 0 }
}

Adding new associated types is binary compatible if the associated type has a default specified in the protocol itself:

public protocol PointLike {
  var x: Int { get }
  var y: Int { get }
  var z: Int { get }

  associatedtype Magnitude = Double
  
  var magnitude: Magnitude { get }
}

There is an important caveat here. Recall that Swift allows all protocols to be used as generic constraints. Additionally, protocols that do not define associated types or Self requirements can be used as types. This limitation exists purely in the source language, and does not affect the binary interface of values of protocol type.
In the above example, the previous version of PointLike did not have any associated types of Self requirements, while the new version has an associated type. So in fact, while this change is binary compatible, it is not source compatible. For this reason, it is best to only add new associated types or Self requirements to protocols that already have associated types or Self requirements. This way, you can be sure clients do not have existing uses of the protocol as a type.

ABI-private declarations can be removed from the top level of a source file. Since they can never be referenced directly from outside the framework, they do not affect the framework’s binary interface.

ABI-private members can be removed from class, struct and enum types, provided the container type is not @frozen. If the type is @frozen, stored properties or enum cases cannot be removed. Any other kind of member can be removed without restriction.

Private and internal declarations and members can become public or @usableFromInline. Classes and class members that are public can be made open.

The implementation of a public declaration can be changed, as long as the new implementation is compatible with existing expected behavior. For example, a function’s body might be replaced with a more efficient algorithm producing the same result. Or, a stored property can be changed into a computed property, as long as the computed property has the same observed behavior.
For example, the following implementation of Temperature is binary compatible with the one we saw earlier:

public struct Temperature {
  public var celsius: Int {
    get { ((fahrenheit - 32) * 5) / 9 }
    set { fahrenheit = (newValue * 9) / 5 + 32 }
  }
  public var fahrenheit: Int
}

This would not be binary compatible if Temperature was @frozen, however.

New protocol conformances can be added to classes, structs, and enums. (Even if they’re @frozen.)
For example, recall our frozen enum Shape from earlier:

@frozen public enum Shape {
  case rect(w: Int, h: Int)
  case circle(radius: Int)
}

We can make it conform to the standard library’s CustomStringConvertible protocol:

@frozen public enum Shape : CustomStringConvertible {
  case rect(w: Int, h: Int)
  case circle(radius: Int)
  
  public var description: String { ... }
}

Alternatively, we could have defined the conformance with an extension, like this:

extension Shape : CustomStringConvertible {
  public var description: String { ... }
}

Conformances to ABI-private protocols can be removed.

A superclass can be inserted between two existing classes. For example, say a class Widget inherits from a class Gadget in version 1:

public class Gadget {}
public class Widget : Gadget {}

we can add a new class Gizmo in version 2 inheriting from Gadget, and simultaneously change Widget to inherit from Gizmo:

public class Gadget {}
public class Gizmo : Gadget {}
public class Widget : Gizmo {}

Examples of non-resilient changes

Removing an ABI-public declaration is not allowed, because existing client code can reference those declarations; either via source, or the framework’s inlinable functions that were emitted into the client. For example, imagine a framework published this code:

@usableFromInline func doInternalThing() { ... }

  @inlinable public func doPublicThing() {
    doInternalThing()
  }

The function doInternalThing() is ABI-public, and cannot be removed, because an existing client application may have inlined the body of the doPublicThing() function, which is @inlinable.

A mutable ABI-public property cannot become immutable. In the binary interface, this would mean removing the ABI-public setter function, which is not allowed.

Adding or removing a stored property from a @frozen struct, even if the property is private, fileprivate or internal.

Adding or removing the @frozen attribute on a struct, enum or class is not allowed.

Changes to a protocol’s list of refined protocols are not allowed.

Changes to the interface of a declaration are not allowed either. This includes the following:
Changing the type of a property
Changing the return type or parameter types of a function
Adding a parameter to a function’s parameter list (even if a default value is provided)
Removing a parameter from a function’s parameter list
Adding or removing generic constraints to a generic type or function’s where clause

Changing a default argument expression does not technically break binary compatibility, however since default argument expressions are inlined at the call site, existing clients will continue to use the old default argument value until recompiled.

Selectively opting out of library evolution

Inlinable functions

While the stored properties of a @frozen struct need not be ABI-public, the types of those stored properties must be ABI-public types. This means that ABI-private structs and enums are never be part of a framework’s binary interface, because they cannot be recursively contained in an ABI-public @frozen type.
So the following is legal, because the type of Widget.id is Int, which is ABI-public:

@frozen
  public struct Widget {
    private let id: Int
  }

However, a similar declaration except where the id property has a custom private type ID is not:

@frozen
  public struct Widget {
    private let id: ID
  }
    
  fileprivate struct ID {
    private let id: Int
  }

To make the above compile, the definition of ID can be changed to be public or @usableFromInline.

If any stored properties in the struct have initial value expressions, those initial value expressions are compiled as if they are @inlinable, meaning the initial value can only be expressed in terms of references to other ABI-public declarations.
For example, the following is legal, because doInternalThing() is @usableFromInline:

@usableFromInline
  func doInternalThing() -> Int { ... }
    
  public struct Widget {
    private let id: Int = doInternalThing()
  }

But this is not:

func doInternalThing() -> Int { ... }
    
  public struct Widget {
    private let id: Int = doInternalThing()
  }

Platform support

Objective-C interoperability

• macOS 10.15

• iOS 13.0

• tvOS 13.0

• watchOS 6.0

Interaction with -enable-testing

Implementation of library evolution

Resilience boundary

Structs and enums

References

• Blog post: ABI stability and more

• WWDC talk: Binary frameworks in Swift

• Specification document: LibraryEvolution.rst

• Evolution proposal: SE-0193 Cross-module inlining and specialization

• Evolution proposal: SE-0260 Library evolution for stable ABIs

• Evolution proposal: SE-0192 Non-exhaustive enums

• Evolution pitch: Modify accessors

• LLVM Developer’s Meeting talk: Implementing Swift generics