You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Documentation: [How to use Environment-Dependent Shared Libraries](https://github.com/swiftlang/swift-package-manager/blob/b586467575580f2365e8f5a29c949379724db795/Documentation/EDSLs.md)
7
+
* Documentation: [How to use Environment-Constrained Shared Libraries](https://github.com/swiftlang/swift-package-manager/blob/b586467575580f2365e8f5a29c949379724db795/Documentation/ECSLs.md)
SwiftPM currently has no support for non-system binary library dependencies on Linux. This proposal adds support for **Environment Dependent Shared Libraries**, which are a type of dynamic library that is shared across a fleet of machines and can be upgraded without recompiling and redeploying all applications running on those machines. We will distribute Environment Dependent Shared Libraries through the existing `.artifactbundle` format.
12
+
SwiftPM currently has no support for non-system binary library dependencies on Linux. This proposal adds support for **Environment Constrained Shared Libraries**, which are a type of dynamic library that is shared across a fleet of machines and can be upgraded without recompiling and redeploying all applications running on those machines. We will distribute Environment Constrained Shared Libraries through the existing `.artifactbundle` format.
Example Producer: [swift-edsl-example](https://github.com/tayloraswift/swift-edsl-example)
16
+
Example Producer: [swift-ECSL-example](https://github.com/tayloraswift/swift-ECSL-example)
17
17
18
-
Example Consumer: [swift-edsl-example-client](https://github.com/tayloraswift/swift-edsl-example-client)
18
+
Example Consumer: [swift-ECSL-example-client](https://github.com/tayloraswift/swift-ECSL-example-client)
19
19
20
20
## Motivation
21
21
@@ -30,51 +30,54 @@ While macOS has Dynamic Library support through XCFrameworks, on Linux we curren
30
30
31
31
On Linux, there are a lot of obstacles to having fully general support for Dynamic Libraries. Swift is not ABI stable on Linux, and Linux itself is not a single platform but a wide range of similar platforms that provide few binary compatibility guarantees. This means it is pretty much impossible for a public Swift library to vend precompiled binaries that will Just Work for everyone, and we are not going to try to solve that problem in this proposal.
32
32
33
-
Instead, we will focus on **Environment Dependent Shared Libraries** (EDSLs). We choose this term to emphasize the distinction between our use case and fully general Dynamic Libraries.
33
+
Instead, we will focus on **Environment Constrained Shared Libraries** (ECSLs). We choose this term to emphasize the distinction between our use case and fully general Dynamic Libraries.
34
34
35
-
### Organization-Defined Platforms (ODPs)
35
+
### Target environment
36
36
37
-
Unlike fully general Dynamic Libraries, you would distribute Environment Dependent Shared Libraries strictly for internal consumption within an organization, or to a small set of paying clients.
37
+
Unlike fully general Dynamic Libraries, you would distribute Environment Constrained Shared Libraries strictly for controlled consumption within a known environment, such as a fleet of servers maintained by a single organization.
38
38
39
-
The organization that distributes an EDSL is responsible for defining what exactly constitutes a “platform” for their purposes. An Organization-Defined Platform (ODP) is not necessarily an operating system or architecture, or even a specific distribution of an operating system. A trivial example of two ODPs might be:
39
+
ECSLs are an advanced tool, and maintaining the prerequisite environment to deploy them safely is neither trivial nor recommended for most users.
40
40
41
-
1. Ubuntu 24.04 with the Swift 6.0.3 runtime installed at `/home/ubuntu/swift`
42
-
2. Ubuntu 24.04 with the Swift 6.0.3 runtime installed at `/home/ubuntu/swift-runtime`
41
+
The organization that distributes an ECSL is responsible for defining what exactly constitutes a “platform” for their purposes. An organization-defined platform is not necessarily an operating system or architecture, or even a specific distribution of an operating system. A trivial example of two such platforms might be:
43
42
44
-
Concepts like Platform Triples are not sufficient to describe an ODP. Even though both ODPs above would probably share the Triple `aarch64-unknown-linux-gnu`, Swift code compiled (without `--static-swift-stdlib`) for one would never be able to run on the other.
43
+
1. Ubuntu 24.04 with the Swift 6.1.2 runtime installed at `/home/ubuntu/swift`
44
+
2. Ubuntu 24.04 with the Swift 6.1.2 runtime installed at `/home/ubuntu/swift-runtime`
45
45
46
-
Organizations add and remove ODPs as needed, and trying to define a global registry of all possible ODPs is a non-goal.
46
+
Concepts like Platform Triples are not sufficient to describe an ECSL deployment target. Even though both “platforms” above would probably share the Triple `aarch64-unknown-linux-gnu`, Swift code compiled (without `--static-swift-stdlib`) for one would never be able to run on the other.
47
47
48
-
To keep things simple, we identify ODPs by the URL of the Artifact Bundle that contains the EDSL.
48
+
Organizations will add and remove environments as needed, and trying to define a global registry of all possible environments is a non-goal.
49
49
50
-
### Creating EDSLs
50
+
The proposed ECSL distribution format does not support shipping multiple variants of ECSLs targeting multiple environments in the same Artifact Bundle, nor does it specify a standardized means for identifying the environment in which a particular ECSL is intended to execute in.
51
+
Users are responsible for computing the correct URL of the Artifact Bundle for the environment they are building for, possibly within the package manifest. Swift tooling will not, on its own, diagnose or prevent the installation of an incompatible ECSL.
51
52
52
-
To compile an EDSL, you just need to build an ordinary SwiftPM library product with the `-enable-library-evolution` flag. This requires no modifications to SwiftPM.
53
+
### Creating ECSLs
53
54
54
-
You would package an EDSL as an `.artifactbundle` just as you would an executable, with the following differences:
55
+
To compile an ECSL, you just need to build an ordinary SwiftPM library product with the `-enable-library-evolution` flag. This requires no modifications to SwiftPM.
56
+
57
+
You would package an ECSL as an `.artifactbundle` just as you would an executable, with the following differences:
55
58
56
59
- The `info.json` must have `schemaVersion` set to `1.2` or higher.
57
60
- The artifact type must be `library`, a new enum case introduced in this proposal.
58
61
- The artifact must have exactly one variant in the `variants` list, and the `supportedTriples` field is forbidden.
59
62
- The artifact payload must include the `.swiftinterface` file corresponding to the actual library object.
60
63
61
-
Because SwiftPM is not (and cannot be) aware of a particular organization’s ODPs, this enforces the requirement that each ODP must have its own Artifact Bundle.
64
+
Because SwiftPM is not (and cannot be) aware of a particular organization’s set of deployment environments, this enforces the requirement that each environment must have its own Artifact Bundle.
62
65
63
-
The organization that distributes the EDSL is responsible for upholding ABI stability guarantees, including the exact Swift compiler and runtime versions needed to safely consume the EDSL.
66
+
The organization that distributes the ECSL is responsible for upholding ABI stability guarantees, including the exact Swift compiler and runtime versions needed to safely consume the ECSL.
64
67
65
68
66
-
### Consuming EDSLs
69
+
### Consuming ECSLs
67
70
68
-
To consume an EDSL, you would add a `binaryTarget` to your `Package.swift` manifest, just as you would for an executable. Because ODPs are identified by the URL of the Artifact Bundle, there are no new fields in the `PackageDescription` API.
71
+
To consume an ECSL, you would add a `binaryTarget` to your `Package.swift` manifest, just as you would for an executable. Because organizations are responsible for defining their set of supported environments, they are also responsible for defining the URLs that the Artifact Bundles for each environment are hosted under, so there are no new fields in the `PackageDescription` API.
69
72
70
-
We expect that the logic for selecting the correct EDSL for a given ODP would live within the `Package.swift` file, that it would be highly organization-specific, and that it would be manipulated using existing means such as environment variables.
73
+
We expect that the logic for selecting the correct ECSL for a given environment would live within the `Package.swift` file, that it would be highly organization-specific, and that it would be manipulated using existing means such as environment variables.
71
74
72
75
73
-
### Deploying EDSLs
76
+
### Deploying ECSLs
74
77
75
-
Deploying EDSLs does not involve SwiftPM or Artifact Bundles at all. You would deploy an EDSL by copying the latest binaries to the appropriate `@rpath` location on each machine in your fleet. The `@rpath` location is part of the ODP definition, and is not modeled by SwiftPM.
78
+
Deploying ECSLs does not involve SwiftPM or Artifact Bundles at all. You would deploy an ECSL by copying the latest binaries to the appropriate `@rpath` location on each machine in your fleet. The `@rpath` location is part of the organization-specific environment definition, and is not modeled by SwiftPM.
76
79
77
-
Some organizations might choose to forgo the `@rpath` mechanism entirely and simply install the EDSLs in a system-wide location.
80
+
Some organizations might choose to forgo the `@rpath` mechanism entirely and simply install the ECSLs in a system-wide location.
78
81
79
82
80
83
## Detailed design
@@ -111,7 +114,7 @@ Below is an example of an `info.json` file for an Artifact Bundle containing a s
111
114
}
112
115
```
113
116
114
-
The artifact must have exactly one variant in the `variants` list, and the `supportedTriples` field is forbidden. An EDSL Artifact Bundle can contain multiple libraries at the top level.
117
+
The artifact must have exactly one variant in the `variants` list, and the `supportedTriples` field is forbidden. An ECSL Artifact Bundle can contain multiple libraries at the top level.
115
118
116
119
Below is an example of the layout of an Artifact Bundle containing a single library called `MyLibrary`. Only the `info.json` must appear at the root of the Artifact Bundle; all other files can appear at whatever paths are defined in the `info.json`, as long as they are within the Artifact Bundle.
117
120
@@ -123,12 +126,12 @@ Below is an example of the layout of an Artifact Bundle containing a single libr
123
126
📝 info.json
124
127
```
125
128
126
-
A macOS Artifact Bundle would contain a `.dylib` instead of a `.so`. EDSLs will be supported on macOS, although we expect this will be an exceedingly rare use case.
129
+
A macOS Artifact Bundle would contain a `.dylib` instead of a `.so`. ECSLs will be supported on macOS, although we expect this will be an exceedingly rare use case.
127
130
128
131
129
132
## Security
130
133
131
-
EDSLs are not intended for public distribution, and are not subject to the same security concerns as public libraries. Organizations that distribute EDSLs are responsible for ensuring that the EDSLs are safe to consume.
134
+
ECSLs are not intended for public distribution, and are not subject to the same security concerns as public libraries. Organizations that distribute ECSLs are responsible for ensuring that the ECSLs are safe to consume.
132
135
133
136
134
137
## Impact on existing packages
@@ -138,19 +141,19 @@ There will be no impact on existing packages. All Artifact Bundle schema changes
138
141
139
142
## Alternatives considered
140
143
141
-
### Extending Platform Triples to model ODPs
144
+
### Extending Platform Triples to model deployment targets
142
145
143
146
SwiftPM currently uses Platform Triples to select among artifact variants when consuming executables. This is workable because it is usually feasible to build executables that are portable across the range of platforms encompassed by a single Platform Triple.
144
147
145
-
We could extend Platform Triples to model ODPs, but this would privilege a narrow set of predefined deployment architectures, and if you wanted to add a new ODP, you would have to modify SwiftPM to teach it to recognize the new ODP.
148
+
We could extend Platform Triples to model ECSL deployment targets, but this would privilege a narrow set of predefined deployment architectures, and if you wanted to add a new environment, you would have to modify SwiftPM to teach it to recognize the new environment.
146
149
147
-
### Supporting multiple variants of an EDSL in the same Artifact Bundle
150
+
### Supporting multiple variants of an ECSL in the same Artifact Bundle
148
151
149
-
We could allow an Artifact Bundle to contain multiple variants of an EDSL, but we would still need to support a way to identify those variants, which in practice makes SwiftPM aware of ODPs.
152
+
We could allow an Artifact Bundle to contain multiple variants of an ECSL, but we would still need to support a way to identify those variants, which in practice forces SwiftPM to become aware of organization-defined environments.
150
153
151
-
We also don’t see much value in this feature, as you would probably package and upload EDSLs using one CI/CD workflow per ODP anyway. Combining artifacts would require some kind of synchronization mechanism to await all pipelines before fetching and merging bundles.
154
+
We also don’t see much value in this feature, as you would probably package and upload ECSLs using one CI/CD workflow per environment anyway. Combining artifacts would require some kind of synchronization mechanism to await all pipelines before fetching and merging bundles.
152
155
153
-
One benefit of merging bundles would be that it reduces the number of checksums you need to keep track of, but we expect that most organizations will have a very small number of ODPs, with new ODPs continously phasing out old ODPs.
156
+
One benefit of merging bundles would be that it reduces the number of checksums you need to keep track of, but we expect that most organizations will have a very small number of supported environments, with new environments continously phasing out old environments.
154
157
155
158
### Using a different `ArtifactType` name besides `library`
0 commit comments