Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add an ABI Stability vision document. #2510

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Add an ABI Stability vision document. #2510

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dc9504d
Add an ABI Stability vision document.
al45tair Jul 2, 2024
a349525
Add a section about declaring ABI stability.
al45tair Jul 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 45 additions & 2 deletions visions/abi-stability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,9 @@ based on system versions.

Like Apple platforms, Windows is ABI stable at the API layer; SPIs are
not officially ABI stable (though in practice they may be), and
neither is the system call interface itself.
neither is the system call interface itself. Note, though, that there
is a wrinkle here---the C/C++ runtime is _not_ part of the Windows
API, and does not form part of the ABI boundary.

Windows has a platform-wide exception handling mechanism (Structured
Exception Handling or SEH), which means that the operating system
Expand All @@ -108,7 +110,12 @@ unwinding, but instead relies on knowledge of the standard function
prologue and epilogue. This creates problems for tail call
optimization, which is also needed for Swift Concurrency. While we
have *a* solution in place, we need to be convinced that it's the
*right* solution before declaring ABI stability on Windows.
*right* solution before declaring ABI stability on Windows. Also
unlike other systems, SEH unwinding can be triggered by *asynchronous*
exceptions, which can occur during the prologue or epilogue, which
means we can't simply declare that e.g. async functions don't need to
follow the standard ABI here (since we aren't in charge of when these
might happen).

Windows DLLs also have some interesting design features that need to
be borne in mind here. In particular, symbols exported from DLLs can
Expand Down Expand Up @@ -191,6 +198,42 @@ package builds take this approach, but have to restrict themselves as
a result to a small subset of libraries that are known to be ABI
stable.

## Declaring ABI Stability

Supported platforms for Swift must have a Platform Owner. Because a
declaration of ABI stability for a platform has implications for
compiler and runtime engineers who do not develop on that platform, we
intend to set a high bar for declaring ABI stability. As such, to
become officially ABI stable:

1. The Platform Owner will raise a Swift Evolution proposal for
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is a "Platform"? Is "Linux" a platform, or are "Debian", "Fedora", and "Arch Linux" separate platforms? At least between Debian and Arch, there is a considerable difference in their release strategies that impact the ABI stories, ranging from, "libraries should be held stable for one or two releases" to "rolling-release. ABI is whatever you happened to have downloaded at the moment. Partial-upgrades are not supportable".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think Linux probably is a platform, but I appreciate it's a complicated case and will require some special handling.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose it's pertinent to that discussion that the proposal in the draft Vision Document is that, for Linux, Swift should be ABI stable at its top surface (Swift runtime/standard library and core libraries, as well as code built with the Swift compiler itself), rather than that we're trying to somehow achieve ABI stability across the board for any library you might choose to use — the latter is effectively impossible because of the problems you point out (different distros taking different approaches, some libraries not really having good ABI stability themselves and so on).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm 100% on-board with nailing down the calling conventions, but still have questions about the library ABI/binary compatibility story.

Will we be requiring full bi-directional binary compatibility like on Darwin where you can build against a new runtime and run it on older runtimes (assuming minimum deployment targets work out) as well as building against older runtimes and running it on newer runtimes?
Or are we okay with something more like glibc/libstdc++ where something built against the older runtime will continue working on newer runtimes, but not the other way around?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally I think we should aim high here; if we can make Swift itself work the way it does on Darwin, that's actually quite a compelling feature for Linux development — Swift programs won't have the deployment problems that C/C++ programs do.

I realise that's not easy and will require @availability support and some kind of Swift minimum target version support from the compiler too.

platform ABI stability. The actual proposal could come from
someone other than the Platform Owner, but if so, the Platform
Owner will be asked to indicate their support for the proposal.

2. The proposal should address, at a minimum:

- Calling conventions, including `async`.
- Layout of data structures.
- Representations of scalar types (e.g. size of `Int`/`UInt`).
- API availability mechanisms.
- Linkage issues (particularly regarding dynamic libraries).

It is acceptable, and indeed encouraged, to refer to other
documentation (e.g. the Itanium ABI, documents in the `doc`
directory in the Swift repo), as well as to the behaviour of
existing ABI stable platforms.

3. The proposal should also address any unique platform features
that may be relevant (e.g. Windows DLL behaviour, exception
handling concerns and so on).

4. The Platform Steering Group will review the proposal. If the
PSG and the Platform Owner agree that all relevant concerns have
been met, the platform will be declared ABI Stable and all future
changes to the compiler, runtime or standard library will be
expected to maintain ABI stability for that platform.

## Goals

* Swift should support existing platform ABI stability mechanisms,
Expand Down