In https://github.com/apple/swift/pull/36327, trying to compile
library code where a struct has an unavailable stored property
or an enum with an unavailable case with associated values was made
into a hard error. Update the docs to reflect this limitation
for library authors shipping new versions of dylibs to older OSes.
It is actually valid to add an `associatedtype` requirement, even one
with constraints, to an existing protocol, provided it has availability
and a default value.
- Move the original intro into a "Background" section
- Link to SE-0193 (@inlinable) and SE-0260 (@frozen)
- Note (suggested by @Gankra) on why it's safe to add stored
properties to a struct
- Remove some bits that reference the content removed in earlier
commits
- Other minor copyediting
...and function builders, even though those haven't formally been
accepted to the language yet. (This description of property wrappers
is also a bit optimistic; at the time of this writing, they haven't
been implemented for top-level variables yet.)
Adding new protocol requirements is now a "binary compatible
source breaking change" without explicit guarantees about
source compatibility.
Removing a default from an associated type is not binary
compatible because the associated type may itself have been
added resiliently, in which case clients that predate the
associated type will not be able to instantiate a witness
table for the protocol.
- We don't allow local typealiases in inlinable code either.
- Explicitly document the places where adding or removing 'lazy'
is allowed and not allowed (it's effectively like going between
stored and computed).
- Adding associated types with defaults is now allowed.
- Adding associated types or Self requirements to a protocol that
did not already have them is a *binary-compatible source-breaking
change*.
- For non-@objc enums, adding a raw type is OK -- it's just a
compiler-synthesized RawRepresentable conformance and is not
used for layout.
- Adding/removing/re-ordering extension members does _not_
follow the rules of the type itself.
- Standardize on "inlinable" instead of "inlineable", per SE-0193.
- Standardize on "frozen enums" instead of "closed enums", even though
SE-0192 wasn't quite conclusive on this.
- Typealiases are treated as versioned entities for the purpose of
verifying availability.
- Per SE-0193, inlinable functions do not have always-emit-into-client
behavior.
- Rename the fragility attribute for properties and subscripts to
'@inlinableAccess' for now, since '@inlinable' has been implemented
for functions now. (We may still end up choosing to use the same
name for these declarations too.)
- Private and fileprivate entities cannot be '@inlinable' today.
- We implemented the always-emit-into-client change for default
arguments. They also have even stricter restrictions than most
inlinable functions.
- A struct initializer can also assign to 'self' instead of delegating
with `self.init`.
- Disallow adding new associated types to protocols for now.
- Mention that precedence groups exist.
- Mention that '@usableFromInline' exists.
- '@inlinable' can be backdated, even though all the other fragility
attributes cannot.
- Tweak TODO around '@NSManaged'.
- Tweak list of planned proposals.
This document still deserves some more drastic restructuring to
separate the near-term features from the long-term features.
JoeG (and Dmitri before him) pointed out a while back that having
/two/ ways to get something emitted into a client's module was really
more complexity than we really needed, and created a pitfall for
library authors who might choose the wrong one for their needs.
- Clear up allowed changes for associated types.
- Modifying a fixed_contents struct's properties' accessors isn't inherently
ABI-breaking, just behavior-changing like any other inlineable thing.
- Clarify what an "empty extension" is.
- Update the Pygments lexer we use for parsing Swift-like code.
- State more explicitly which highlighting should be used in which
code blocks.
- Disable highlighting altogether in certain cases (such as SIL.rst,
which has equal amounts grammar and SIL excerpts).
This should fix the warnings-as-error issues coming from Sphinx > 1.3.4.
Based on a patch by Jeremy Fergason!
https://bugs.swift.org/browse/SR-620
The main change is that @always_emit_into_client is now not considered a
versioned attribute: either you use it up front and the entity is not part
of your ABI, or you don't and it is. Everything else falls out from that.
