@@ -65,24 +65,58 @@ aid in migration?
65
65
66
66
## Effect on ABI stability
67
67
68
- Does the proposal change the ABI of existing language features? The
69
- ABI comprises all aspects of the code generation model and interaction
70
- with the Swift runtime, including such things as calling conventions,
71
- the layout of data types, and the behavior of dynamic features in the
72
- language (reflection, dynamic dispatch, dynamic casting via ` as? ` ,
73
- etc.). Purely syntactic changes rarely change existing ABI. Additive
74
- features may extend the ABI but, unless they extend some fundamental
75
- runtime behavior (such as the aforementioned dynamic features), they
76
- won't change the existing ABI.
77
-
78
- Features that don't change the existing ABI are considered out of
79
- scope for [ Swift 4 stage 1] ( README.md ) . However, additive features
80
- that would reshape the standard library in a way that changes its ABI,
81
- such as [ where clauses for associated
82
- types] ( https://github.com/apple/swift-evolution/blob/master/proposals/0142-associated-types-constraints.md ) ,
83
- can be in scope. If this proposal could be used to improve the
84
- standard library in ways that would affect its ABI, describe them
85
- here.
68
+ The ABI comprises all aspects of how code is generated for the
69
+ language and how that code interacts with the Swift runtime library.
70
+ It includes such things as calling conventions, function signatures,
71
+ the layout of data types, and the behavior of dynamic features in
72
+ the language ssuch as reflection, dynamic dispatch, and dynamic
73
+ casting. It also includes things such as the addition of functions
74
+ and types to the public symbols of a library.
75
+
76
+ Many language proposals have no direct impact on the ABI. For
77
+ example, a proposal to add the ` typealias ` declaration would have
78
+ no effect on the ABI because type aliases are not represented
79
+ dynamically and uses of them in code can be straightforwardly
80
+ translated into uses of the aliased type. Such proposals can
81
+ simply state in this section that they have no impact on the ABI.
82
+ However, if * using* the feature in code that must maintain a stable
83
+ ABI can have a surprising ABI impact, that should be discussed
84
+ in this section.
85
+
86
+ Because Swift has a stable ABI on some platforms, proposals are
87
+ generally not acceptable if they would require changes to the ABI
88
+ of existing language features or declarations. For example,
89
+ Swift could not accept a feature which, in order to work, would
90
+ require parameters with certain types to always be passed as owned
91
+ values, because parameters are not always passed as owned values
92
+ in the ABI. Proposals must be designed to avoid the need for this.
93
+ For example, the feature above might only be enabled for parameters
94
+ marked a special way, and then adding that marking to an existing
95
+ function parameter would change the ABI of that function.
96
+
97
+ Proposals are acceptable if they can be thought of as merely
98
+ * adding* to the ABI, such as by adding new kinds of declarations,
99
+ adding new modifiers or attributes that can be used on existing
100
+ kinds of declarations, or adding new types or methods to the Swift
101
+ standard library. On platforms with stable ABIs, such features
102
+ will by default require a new release of the platform in order
103
+ to work, and so their use in code that may deploy to older
104
+ releases will have to be availability-guarded. If this limitation
105
+ applies to any part of this proposal, that should be discussed
106
+ in this section.
107
+
108
+ Adding a function to the standard library does not always require
109
+ an addition to the ABI if it can be implemented using other
110
+ library functions. Library maintainers may be able to help you
111
+ with this during the code review of your implementation. Adding
112
+ a type or protocol always requires an addition to the ABI.
113
+
114
+ If a feature does require additions to the ABI, platforms with
115
+ stable ABIs may sometimes be able to back-deploy those additions
116
+ to existing releases of the platform. This is not always possible,
117
+ and in any case, it is outside the scope of the evolution process.
118
+ Proposals should usually discuss ABI stability concerns as if
119
+ it was not possible to back-deploy the necessary ABI additions.
86
120
87
121
## Effect on API resilience
88
122
0 commit comments