Declaring Library Version Dependencies¶

Swift 2’s availability model includes the notion of a minimum deployment target, the version of an OS that must be present for the program being compiled to run at all. For example, a program compiled with a minimum deployment target of iOS 9.2 will not launch on iOS 9.0.

The generalized model above suggests being able to make similar guarantees for individual libraries. For example, a client program may depend on version 1.1 of the “Magician” library; trying to run using version 1.0 will result in errors. By declaring this at compile-time, the client code can omit @available and #available checks that are satisfied by the minimum library version.

Both the syntax and enforcement of this feature are not covered by this document.

Syntax #1: Attributes¶

@available(1.2)
public func summonDemons()

@available(1.0) @inlineable(1.2)
public func summonElves()

Using the same attribute for both publishing and using versioned APIs helps tie the feature together and enforces a consistent set of rules. However, there are several other annotations described later in this document that also need versioning information, and it may not be obvious what the version number means outside the context of available.

Syntax #2: Version Blocks¶

#version(1.2)
public func summonDemons()

#version(1.0) {}
#version(1.2) { @inlineable }
public func summonElves()

Since there are potentially many annotations on a declaration that need versioning information, it may make sense to group them together in some way. Only certain annotations would support being versioned in this way.

Syntax #3: The public modifier¶

public(1.2) func summonDemons()

/* @inlineable ?? */
public(1.0) func summonElves()

Putting the version on the public modifier is the most concise option. However, there’s no obvious syntax here for adding versions to other annotations that may apply to a declaration.

(Also, at one point there was a proposal to tag API only intended for certain clients using a similar syntax: public("Foundation"), for example, for APIs only meant to be used by Foundation. These could then be stripped out of the public interface for a framework before being widely distributed. But that could easily use an alternate syntax.)

Top-Level Functions¶

A versioned top-level function is fairly restricted in how it can be changed. The following changes are permitted:

• Changing the body of the function.
• Changing internal parameter names (i.e. the names used within the function body, not the labels that are part of the function’s full name).
• Reordering generic requirements (but not the generic parameters themselves).
• Adding a default argument expression to a parameter.
• Changing or removing a default argument is a binary-compatible source-breaking change.
• The @discardableResult and @warn_unqualified_access attributes may be added to a function without any additional versioning information.

No other changes are permitted; the following are particularly of note:

• A versioned function may not change its parameters or return type.
• A versioned function may not change its generic requirements.
• A versioned function may not change its external parameter names (labels).
• A versioned function may not add, remove, or reorder parameters, whether or not they have default arguments.
• A versioned function that throws may not become non-throwing or vice versa.
• The @noescape attribute may not be added to or removed from a parameter. It is not a versioned attribute and so there is no way to guarantee that it is safe when a client deploys against older versions of the library.

public struct Point2D {
  var x, y: Double
  public init(x: Double, y: Double) { /*…*/ }
}

extension Point2D {
  @inlineable public func distance(to other: Point2D) -> Double {
    let deltaX = self.x - other.x
    let deltaY = self.y - other.y
    return sqrt(deltaX*deltaX + deltaY*deltaY)
  }
}

public struct Point2D {
  var r, theta: Double
  public init(x: Double, y: Double) { /*…*/ }
}

Top-Level Variables and Constants¶

Given a versioned module-scope variable declared with var, the following changes are permitted:

• Adding (but not removing) a public setter to a computed variable.
• Adding or removing a non-public, non-versioned setter.
• Changing from a stored variable to a computed variable, or vice versa, as long as a previously versioned setter is not removed.
• Changing the body of an accessor.
• Adding or removing an observing accessor (willSet or didSet) to/from an existing variable. This is effectively the same as modifying the body of a setter.
• Changing the initial value of a stored variable.
• Adding or removing weak from a variable with Optional type.
• Adding or removing unowned from a variable.
• Adding or removing @NSCopying to/from a variable.

If a public setter is added after the property is first exposed (whether the property is stored or computed), it must be versioned independently of the property itself.

Additionally, for a module-scope constant declared with let, the following changes are permitted:

• Changing the value of the constant.

It is not safe to change a let constant into a variable or vice versa. Top-level constants are assumed not to change for the entire lifetime of the program once they have been initialized.

Structs¶

Swift structs are a little more flexible than their C counterparts. By default, the following changes are permitted:

• Reordering any existing members, including stored properties.
• Adding any new members, including stored properties.
• Changing existing properties from stored to computed or vice versa.
• Changing the body of any methods, initializers, or accessors.
• Adding or removing an observing accessor (willSet or didSet) to/from an existing property. This is effectively the same as modifying the body of a setter.
• Removing any non-public, non-versioned members, including stored properties.
• Adding a new protocol conformance (with proper availability annotations).
• Removing conformances to non-public protocols.

The important most aspect of a Swift struct is its value semantics, not its layout.

It is not safe to add or remove mutating or nonmutating from a member or accessor within a struct. These modifiers are not versioned attributes and as such there is no safety guarantee for a client deploying against an earlier version of the library.

@available(1.1)
extension Wand : MagicType {/*…*/}

extension Wand : @available(1.1) MagicType {/*…*/}

Enums¶

By default, a library owner may add new cases to a public enum between releases without breaking binary compatibility. As with structs, this results in a fair amount of indirection when dealing with enum values, in order to potentially accommodate new values. More specifically, the following changes are permitted:

• Adding a new case.
• Reordering existing cases is a binary-compatible source-breaking change. In particular, if an enum is RawRepresentable, changing the raw representations of cases may break existing clients who use them for serialization.
• Adding a raw type to an enum that does not have one.
• Removing a non-public, non-versioned case.
• Adding any other members.
• Removing any non-public, non-versioned members.
• Adding a new protocol conformance (with proper availability annotations).
• Removing conformances to non-public protocols.

Adding or removing the @objc attribute from an enum is not permitted; this affects the enum’s memory representation and is not backwards-compatible.

Protocols¶

There are very few safe changes to make to protocols and their members:

• A new non-type requirement may be added to a protocol, as long as it has an unconstrained default implementation.
• A new associated type may be added to a protocol, as long as it has a default. As with any other declarations, newly-added associated types must be marked with @available specifying when they were introduced.
• A default may be added to an associated type.
• A new optional requirement may be added to an @objc protocol.
• All members may be reordered, including associated types.
• Changing internal parameter names of function and subscript requirements is permitted.
• Reordering generic requirements is permitted (but not the generic parameters themselves).
• The @discardableResult and @warn_unqualified_access attributes may be added to a function requirement without any additional versioning information.

All other changes to the protocol itself are forbidden, including:

• Making an existing requirement optional.
• Making a non-@objc protocol @objc or vice versa.
• Adding or removing constraints from an associated type.
• Removing a default from an associated type.

Protocol extensions may be more freely modified; see below.

Classes¶

Because class instances are always accessed through references, they are very flexible and can change in many ways between releases. Like structs, classes support all of the following changes:

• Reordering any existing members, including stored properties.
• Changing existing properties from stored to computed or vice versa.
• Changing the body of any methods, initializers, or accessors.
• Adding or removing an observing accessor (willSet or didSet) to/from an existing property. This is effectively the same as modifying the body of a setter.
• Removing any non-public, non-versioned members, including stored properties.
• Adding a new protocol conformance (with proper availability annotations).
• Removing conformances to non-public protocols.

Omitted from this list is the free addition of new members. Here classes are a little more restrictive than structs; they only allow the following changes:

• Adding a new convenience initializer.
• Adding a new designated initializer, if the class is not open.
• Adding a deinitializer.
• Adding new, non-overriding method, subscript, or property.
• Adding a new overriding member, though if the class is open the type of the member may not deviate from the member it overrides. Changing the type could be incompatible with existing overrides in subclasses.

Finally, classes allow the following changes that do not apply to structs:

• A class may be marked open if it is not already marked final.
• A class may be marked final if it is not already marked open.
• Removing an explicit deinitializer. (A class with no declared deinitializer effectively has an implicit deinitializer.)
• “Moving” a method, subscript, or property up to its superclass. The declaration of the original member must remain along with its original availability, but its body may consist of simply calling the new superclass implementation.
• A non-final override of a method, subscript, property, or initializer may be removed as long as the generic parameters, formal parameters, and return type exactly match the overridden declaration. Any existing callers should automatically use the superclass implementation.
• Within an open class, any public method, subscript, or property may be marked open if it is not already marked final.
• Any public method, subscript, or property may be marked final if it is not already marked open.
• @IBOutlet, @IBAction, and @IBInspectable may be added to a member without providing any extra version information. Removing any of these is a binary-compatible source-breaking change if the member remains @objc, and disallowed if not.
• Likewise, @IBDesignable may be added to a class without providing any extra version information. Removing it is considered a binary-compatible source-breaking change.
• Changing a class’s superclass A to another class B, if class B is a subclass of A and class B, along with any superclasses between it and class A, were introduced in the latest version of the library.

Other than those detailed above, no other changes to a class or its members are permitted. In particular:

• open may not be removed from a class or its members.
• final may not be removed from a class or its members. (The presence of final enables optimization.)
• dynamic may not be added to or removed from any members. Existing clients would not know to invoke the member dynamically.
• A final override of a member may not be removed, even if the type matches exactly; existing clients may be performing a direct call to the implementation instead of using dynamic dispatch.
• @objc and @nonobjc may not be added to or removed from the class or any existing members.
• @NSManaged may not be added to or removed from any existing members.

Extensions¶

Non-protocol extensions largely follow the same rules as the types they extend. The following changes are permitted:

• Adding new extensions and removing empty extensions (that is, extensions that declare neither members nor protocol conformances).
• Moving a member from one extension to another within the same module, as long as both extensions have the exact same constraints.
• Moving a member from an unconstrained extension to the declaration of the base type, provided that the declaration is in the same module. The reverse is permitted for all members except stored properties, although note that moving all initializers out of a type declaration may cause a new one to be implicitly synthesized.
• Adding a new protocol conformance (with proper availability annotations).
• Removing conformances to non-public protocols.

Adding, removing, reordering, and modifying members follow the same rules as the base type; see the sections on structs, enums, and classes above.

Operators¶

Operator declarations are entirely compile-time constructs, so changing them does not have any affect on binary compatibility. However, they do affect source compatibility, so it is recommended that existing operators are not changed at all except for the following:

• Making a non-associative operator left- or right-associative.

Any other change counts as a binary-compatible source-breaking change.

Operator declarations are not versioned.

Typealiases¶

Public typealiases within structs, enums, and protocols may be used for protocol conformances (to satisfy associated type requirements), not only within the library but within client modules as well. Therefore, changing a member typealias in any way is not permitted; while it will not break existing clients, they cannot recompile their code and get correct behavior.

Top-level typealiases only exist at compile-time, so changing the underlying type of one is a binary-compatible source-breaking change. However, if the typealias is used in the type of any versioned entity in a library, it may be an actual breaking change and would not be permitted.

It is always permitted to change the use of a public typealias to its underlying type, and vice versa, at any location in the program.

Neither top-level nor member typealiases are versioned.

A Unifying Theme¶

So far this document has talked about ways to give up flexibility for several different kinds of declarations: @inlineable for functions, @fixedContents for structs, etc. Each of these has a different set of constraints it enforces on the library author and promises it makes to clients. However, they all follow a common theme of giving up the flexibility of future changes in exchange for improved performance and perhaps some semantic guarantees. Therefore, all of these attributes are informally referred to as “fragility attributes”.

Given that these attributes share several characteristics, we could consider converging on a single common attribute, say @fixed, @inline, or @fragile. However, this may be problematic if the same declaration has multiple kinds of flexibility.

Inlineable Code¶

By default, the availability context for a library always includes the latest version of the library itself, since that code is always distributed as a unit. However, this is not true for functions that have been marked inlineable (see Inlineable Functions above). Inlineable code must be treated as if it is outside the current module, since once it’s inlined it will be.

For inlineable code, the availability context is exactly the same as the equivalent non-inlineable code except that the assumed version of the containing library is the version attached to the @inlineable attribute, or the version of the library in which the entity was introduced, and any library version dependencies or minimum deployment target must be specified explicitly using @available. Code within this context must be treated as if the containing library were just a normal dependency.

A versioned inlineable function still has an exported symbol in the library binary, which may be used when the function is referenced from a client rather than called. This version of the function is not subject to the same restrictions as the version that may be inlined, and so it may be desirable to compile a function twice: once for inlining, once for maximum performance.

If the body of an inlineable function is used in any way by a client module (say, to determine that it does not read any global variables), that module must take care to emit and use its own copy of the function. This is because analysis of the function body may not apply to the version of the function currently in the library.

Local Availability Contexts¶

Swift availability contexts aren’t just at the declaration level; they also cover specific regions of code inside function bodies as well. These “local” constructs are formed using the #available construct, which performs a dynamic check.

In theory, it would be legal to allow code dominated by a #available check to take advantage of additional fragility information introduced by the more restrictive dependencies that were checked for. However, this is an additional optimization that may be complicated to implement (and even to represent properly in SIL), and so it is not a first priority.

Other Promises About Types¶

Advanced users may want to promise more specific things about various types. These are similar to the internal effects attribute we have for functions, except that they can be enforced by the compiler.

• trivial: Promises that assignment just requires a fixed-size bit-for-bit copy without any indirection or reference-counting operations.
• maximumFootprint(sizeInBits: N, alignmentInBits: A): Promises that the type’s size and required alignment are at most N bits and A bits, respectively. (Both may be smaller.)
• fixedSize: Promises that the type has some size known at compile-time, allowing optimizations like promoting allocations to the stack. Only applies to fixed-contents structs and closed enums, which can already infer this information; the explicit annotation allows it to be enforced.

Collectively these features are known as “performance assertions”, to underscore the fact that they do not affect how a type is used at the source level, but do allow for additional optimizations. We may also expose some of these qualities to static or dynamic queries for performance-sensitive code.

All of these features need to be versioned, just like the more semantic fragility attributes above. The exact spelling is not proposed by this document.

Deployments¶

Related to the concept of a resilience domain is a deployment. While a resilience domain allows related libraries to be compiled more efficiently, a deployment groups related libraries together to present semantic version information to clients. The simplest example of this might be an OS release: OS X 10.10.0 contains Foundation version 1151.16 and AppKit version 1343. A deployment thus acts as a “virtual dependency”: clients that depend on OS X 10.10 can rely on the presence of both of the library versions above.

The use of deployments allows clients to only have to think about aggregate dependencies, instead of listing every library they might depend on. It also allows library authors to build many versions of a library within a larger release cycle, as well as allowing a vendor to bundle together many libraries with uncoordinated release schedules and release them as a logical unit.

There are lots of details to figure out here, including how to distribute this information. In particular, just like libraries publish the history of their own APIs, a deployment must publish the history of their included library versions, i.e. not just that OS X 10.10 contains Foundation 1151.16 and AppKit 1343, but also that OS X 10.9 contains Foundation 1056 and AppKit 1265, and that OS X 10.8 contains Foundation 945.0 and AppKit 1187, and so on, back to the earliest version of the deployment that is supported.

Automatic Versioning¶

A possible extension of this “checker” would be a tool that automatically generates versioning information for entities in a library, given the previous public interface of the library. This would remove the need for versions on any of the fragility attributes, and declaring versioned API would be as simple as marking an entity public. Obviously this would also remove the possibility of human error in managing library versions.

However, making this tool has a number of additional difficulties beyond the simple checker tool:

• The tool must be able to read past library interface formats. This is true for a validation tool as well, but the cost of failure is much higher. Similarly, the past version of a library must be available to correctly compile a new version.
• Because the information goes into a library’s public interface, the versioning tool must either be part of the compilation process, modify the interface generated by compilation, or produce a sidecar file that can be loaded when compiling the client. In any case, it must produce information in addition to consuming it.
• Occasionally a library owner may want to override the inferred versions. This can be accomplished by providing explicit versioning information, as described above.
• Bugs in the tool manifest as bugs in client programs.

Because this tool would require a fair amount of additional work, it is not part of this initial model. It is something we may decide to add in the future.

Subclass and base both conform to protocol¶

// Library, version 1
class Elf {}
protocol Summonable {}

// Client, version 1
class ShoemakingElf : Elf, Summonable {}

// Library, version 2
@available(2.0)
extension Elf : Summonable {}

Now ShoemakingElf conforms to Summonable in two different ways, which may be incompatible (especially if Summonable had associated types or requirements involving Self).

Additionally, the client can’t even remove ShoemakingElf‘s conformance to Summonable, because it may itself be a library with other code depending on it. We could fix that with an annotation to explicitly inherent the conformance of Summonable from the base class, but even that may not be possible if there are incompatible associated types involved (because changing a member typealias is not a safe change).

One solution is to disallow adding a conformance for an existing protocol to an open class.

Recompiling changes a protocol’s implementation¶

// Library, version 1
protocol MagicType {}
protocol Wearable {}
func use<T: MagicType>(_ item: T) {}

// Client, version 1
struct Amulet : MagicType, Wearable {}
use(Amulet())

// Library, version 2
protocol MagicType {
  @available(2.0)
  func equip() { print("Equipped.") }
}

extension Wearable where Self: MagicType {
  @available(2.0)
  func equip() { print("You put it on.") }
}

func use<T: MagicType>(_ item: T) { item.equip() }

Before the client is recompiled, the implementation of equip() used for Amulet instances can only be the default implementation, i.e. the one that prints “Equipped”. However, recompiling the client will result in the constrained implementation being considered a “better” match for the protocol requirement, thus changing the behavior of the program.

This should never change the meaning of a program, since the default implementation for a newly-added requirement should always be correct. However, it may have significantly different performance characteristics or side effects that would make the difference in behavior a surprise.

This is similar to adding a new overload to an existing set of functions, which can also change the meaning of client code just by recompiling. However, the difference here is that the before-recompilation behavior was never requested or acknowledged by the client; it’s just the best the library can do.

A possible solution here is to require the client to acknowledge the added requirement in some way when it is recompiled.

(We do not want to perform overload resolution at run time to find the best possible default implementation for a given type.)