Skip to content

Commit 2993e77

Browse files
dempseyatgithubdempseyatgithub
committed
Add proposal to formalize 'language mode' terminology
Proposal to formalize the term 'language mode' in tool options and Swift PM APIs.
1 parent 433548a commit 2993e77

File tree

1 file changed

+266
-0
lines changed

1 file changed

+266
-0
lines changed

‎proposals/nnnn-formalize-language-mode-terminology.md

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# Pitch: Formalize ‘language mode’ terminology
2+
3+
* Proposal: [SE-NNNN](nnnn-formalize-language-mode-terminology.md)
4+
* Author: [James Dempsey](https://github.com/dempseyatgithub)
5+
* Review Manager: TBD
6+
* Status: **Awaiting review**
7+
* Implementation: [apple/swift-package-manager#7620](https://github.com/apple/swift-package-manager/pull/7620)
8+
* Review: ([first pitch](https://forums.swift.org/t/pitch-formalize-swift-language-mode-naming-in-tools-and-api/71733)), ([second pitch](https://forums.swift.org/t/pitch-2-formalize-language-mode-naming-in-tools-and-api/72136))
9+
10+
## Introduction
11+
The term "Swift version” can refer to either the toolchain/compiler version or the language mode. This ambiguity is a consistent source of confusion. This proposal formalizes the term _language mode_ in tool options and APIs.
12+
13+
## Proposed Solution
14+
The proposed solution is to use the term _language mode_ for the appropriate Swift compiler option and Swift Package Manager APIs. Use of "Swift version" to refer to language mode will be deprecated or obsoleted as needed.
15+
16+
### Terminology
17+
The term _language mode_ has been consistently used to describe this compiler feature since it was introduced with Swift 4.0 and is an established term of art in the Swift community.
18+
19+
The **Alternatives Considered** section contains a more detailed discussion of the term's history and usage.
20+
21+
### Swift compiler option
22+
Introduce a `-language-mode` option that has the same behavior as the existing `-swift-version` option, while de-emphasizing the `-swift-version` option in help and documentation.
23+
24+
#### Naming note
25+
The proposed compiler option uses the term 'language mode' instead of 'Swift language mode' because the context of the usage strongly implies a Swift language mode. The intent is that the `languageMode()` compiler condition described in **Future directions** would also use that naming convention for the same reason.
26+
27+
### Swift Package Manager
28+
Introduce four Swift Package Manager API changes limited to manifests \>= 6.0:
29+
30+
#### 1. A new Package init method that uses the language mode terminology
31+
32+
```swift
33+
@available(_PackageDescription, introduced: 6)
34+
Package(
35+
name: String,
36+
defaultLocalization: [LanguageTag]? = nil.
37+
platforms: [SupportedPlatform]? = nil,
38+
products: [Product] = [],
39+
dependencies: [Package.Dependency] = [],
40+
targets: [Target] = [],
41+
swiftLanguageModes: [SwiftLanguageMode]? = nil,
42+
cLanguageStandard: CLanguageStandard? = nil,
43+
cxxLanguageStandard: CXXLanguageStandard? = nil
44+
)
45+
```
46+
47+
Add a new `init` method to `Package` with the following changes from the current `init` method:
48+
49+
- The paramater `swiftLanguageVersions` is renamed to `swiftLanguageModes`
50+
- The parameter type is now an optional array of `SwiftLanguageMode` values instead of `SwiftVersion` values
51+
52+
The existing init method will be marked as obsolete and renamed allowing the compiler to provide a fix-it.
53+
54+
#### 2. Rename `swiftLanguageVersions` property to `swiftLanguageModes`
55+
Rename the public `Package` property `swiftLanguageVersions` to `swiftLanguageModes`. Add a `swiftLanguageVersions` computed property that accesses `swiftLanguageModes` for backwards compatibility.
56+
57+
58+
#### 3. Rename `SwiftVersion` enum to `SwiftLanguageMode`
59+
Rename the `SwiftVersion` enum to `SwiftLanguageMode`. Add `SwiftVersion` as a type alias for backwards compatibility.
60+
61+
62+
#### 4. Update API accepted in [SE-0435: Swift Language Version Per Target](https://github.com/apple/swift-evolution/blob/main/proposals/0435-swiftpm-per-target-swift-language-version-setting.md):
63+
64+
```swift
65+
public struct SwiftSetting {
66+
// ... other settings
67+
68+
@available(_PackageDescription, introduced: 6.0)
69+
public static func swiftLanguageMode(
70+
_ mode: SwiftLanguageMode,
71+
_ condition: BuildSettingCondition? = nil
72+
)
73+
```
74+
75+
If both proposals are implemented in the same release, the accepted SE-0435 API would be added with the proposed naming change.
76+
77+
#### Naming note
78+
79+
In Swift PM manifests, multiple languages are supported. For clarity, there is existing precedent for parameter and enum type names to have a language name prefix.
80+
81+
For example the Package `init` method currently includes:
82+
83+
```swift
84+
...
85+
swiftLanguageVersions: [SwiftVersion]? = nil,
86+
cLanguageStandard: CLanguageStandard? = nil,
87+
cxxLanguageStandard: CXXLanguageStandard? = nil
88+
...
89+
```
90+
91+
For clarity and to follow the existing precedent, the proposed Swift PM APIs will be appropriately capitalized versions of "Swift language mode".
92+
93+
## Detailed design
94+
95+
### New swift compiler option
96+
A new `-language-mode` option will be added with the same behavior as the existing `-swift-version` option.
97+
98+
The `-swift-version` option will continue to work as it currently does, preserving backwards compatibility.
99+
100+
The `-language-mode` option will be presented in the compiler help.
101+
102+
The `-swift-version` option will likely be supressed from the top-level help of the compiler. More investigation is needed on the details of this.
103+
104+
### Swift Package Manager
105+
Proposed Swift Package Manager API changes are limited to manifests \>= 6.0:
106+
107+
### New Package init method and obsoleted init method
108+
A new `init` method will be added to `Package` that renames the `swiftLanguageVersions` parameter to `swiftLanguageModes` with the type of the parameter being an optional array of `SwiftLanguageMode` values instead of `SwiftVersion` values:
109+
110+
```swift
111+
@available(_PackageDescription, introduced: 6)
112+
Package(
113+
name: String,
114+
defaultLocalization: [LanguageTag]? = nil.
115+
platforms: [SupportedPlatform]? = nil,
116+
products: [Product] = [],
117+
dependencies: [Package.Dependency] = [],
118+
targets: [Target] = [],
119+
swiftLanguageModes: [SwiftLanguageMode]? = nil,
120+
cLanguageStandard: CLanguageStandard? = nil,
121+
cxxLanguageStandard: CXXLanguageStandard? = nil
122+
)
123+
```
124+
125+
126+
The existing init method will be marked as obsoleted and renamed, allowing the compiler to provide a fix-it:
127+
128+
```
129+
@available(_PackageDescription, introduced: 5.3, obsoleted: 6, renamed:
130+
"init(name:defaultLocalization:platforms:pkgConfig:providers:products:
131+
dependencies:targets:swiftLanguageModes:cLanguageStandard:
132+
cxxLanguageStandard:)")
133+
public init(
134+
name: String,
135+
...
136+
swiftLanguageVersions: [SwiftVersion]? = nil,
137+
cLanguageStandard: CLanguageStandard? = nil,
138+
cxxLanguageStandard: CXXLanguageStandard? = nil
139+
) {
140+
```
141+
142+
#### Obsoleting existing init method
143+
The existing method must be obsoleted because the two methods are ambiguous when the default value for `swiftLanguageVersions` / `swiftLanguageModes` is used:
144+
145+
```
146+
Package ( // Error: Ambiguous use of 'init'
147+
name: "MyPackage",
148+
products: ...,
149+
targets: ...
150+
)
151+
```
152+
153+
This follows the same approach used by all past revisions of the Package `init` method.
154+
155+
See the **Source compatibiity** section for more details about this change.
156+
157+
### Rename `swiftLanguageVersions` property to `swiftLanguageModes`
158+
Rename the `Package` public property `swiftLanguageVersions` to `swiftLanguageModes`. Introduce a computed property named `swiftLanguageModes` that accesses the renamed stored property for backwards compatibility.
159+
160+
The computed property will be annotated as obsoleted in Swift 6, renamed to `swiftLanguageModes`.
161+
162+
For packages with swift tools version less than 6.0, accessing the `swiftLanguageModes` property will continue to work.
163+
For 6.0 and later, that access will be an error with a fix-it to use the new property name.
164+
165+
```swift
166+
@available(_PackageDescription, obsoleted: 6, renamed: "swiftLanguageModes")
167+
public var swiftLanguageVersions: [SwiftVersion]? {
168+
get { swiftLanguageModes }
169+
set { swiftLanguageModes = newValue }
170+
}
171+
```
172+
173+
See the **Source compatibiity** section for more details about this change.
174+
175+
### Rename `SwiftVersion` enum to `SwiftLanguageMode`
176+
Rename the existing `SwiftVersion` enum to `SwiftLanguageMode` with `SwiftVersion` added back as a type alias for backwards compatibility.
177+
178+
This change will not affect serializaiton of PackageDescription types. Serialization is handled by converting PackageDescription types into separate, corresponding Codable types. The existing serialization types will remain as-is.
179+
180+
181+
### Rename API added in SE-0435
182+
The API in the newly-accepted [SE-0435](https://github.com/apple/swift-evolution/blob/main/proposals/0435-swiftpm-per-target-swift-language-version-setting.md) will change to use the _language mode_ terminology:
183+
184+
```swift
185+
public struct SwiftSetting {
186+
// ... other settings
187+
188+
@available(_PackageDescription, introduced: 6.0)
189+
public static func swiftLanguageMode(
190+
_ mode: SwiftLanguageMode,
191+
_ condition: BuildSettingCondition? = nil
192+
)
193+
```
194+
195+
The name of the function is `swiftLanguageMode()` instead of `languageMode()` to keep naming consistent with the `swiftLanguageModes` parameter of the Package init method. The parameter label `mode` is used to follow the precedent set by `interoperabilityMode()` in `SwiftSetting`.
196+
197+
## Source compatibility
198+
The new Package `init` method and obsoleting of the existing `init` method will cause source breakage for package manifests that specify the existing `swiftLanguageVersions` parameter when updating to swift tools version 6.0
199+
200+
A search of manifest files in public repositories suggests that about 10% of manifest files will encounter this breakage.
201+
202+
Because the obsoleted `init` method is annotated as `renamed` the compiler will automatically provide a fix-it to update to the new `init` method.
203+
204+
Renaming the public `swiftLanguageVersions` property of `Package` preserves backwards compatibility by introducing a computed property with that name. Because this proposal already contains a necessary breaking change as detailed above, the computed property will also be marked as obsoleted in 6.0 and annotated as `renamed` to provide a fix-it.
205+
206+
Searching manifest files in public repositories suggests that accessing the `swiftLanguageVersions` property directly is not common. Making both breaking changes at once results in applying at most two fix-its to a manifest file instead of one.
207+
208+
## ABI compatibility
209+
This proposal has no effect on ABI stability.
210+
211+
## Future directions
212+
This proposal originally included the proposed addition of a `languageMode()` compilation condition to further standardize on the terminology and allow the compiler to check for valid language mode values.
213+
214+
That functionality has been removed from this proposal with the intent to pitch it seperately. Doing so keeps this proposal focused on the tools, including the source breaking API changes. The future direction is purely additive and would focus on the language change.
215+
216+
## Alternatives considered
217+
218+
### Alternate terminology
219+
220+
In the pitch phase, a number of terms were suggested as alternatives for _language mode_. Some concerns were also expressed that the term _language mode_ may be too broad and cause future ambiguity.
221+
222+
The intent of this proposal is to formalize established terminology in tool options and APIs.
223+
224+
The term _language mode_ is a long-established term of art in the Swift community to describe this functionality in the compiler.
225+
226+
This includes the [blog post](https://www.swift.org/blog/swift-4.0-released/) annoucing the functionality as part of the release of Swift 4 in 2017 (emphasis added):
227+
228+
> With Swift 4, you may not need to modify your code to use the new version of the compiler. The compiler supports two _language modes_…
229+
230+
> The _language mode_ is specified to the compiler by the -swift-version flag, which is automatically handled by the Swift Package Manager and Xcode.
231+
>
232+
> One advantage of these _language modes_ is that you can start using the new Swift 4 compiler and migrate fully to Swift 4 at your own pace, taking advantage of new Swift 4 features, one module at a time.
233+
234+
Usage also includes posts in the last year from LSG members about Swift 6 language mode:
235+
236+
- [Design Priorities for the Swift 6 Language Mode](https://forums.swift.org/t/design-priorities-for-the-swift-6-language-mode/62408/27)
237+
- [Progress toward the Swift 6 language mode](https://forums.swift.org/t/progress-toward-the-swift-6-language-mode/68315)
238+
239+
Finally, searching for "language modes" and "language mode" in the Swift forums found that at least 90% of the posts use the term in this way. Many of the remaining posts use the term in the context of Clang.
240+
241+
#### Alternatives mentioned
242+
243+
Alternate terms raised as possibilities were:
244+
- _Edition_: a term used by Rust for a similar concept
245+
- _Standard_: similar to C or C++ standards
246+
Language standards tend to be associated with a written specification, which Swift does not currently have.
247+
Using the term _standard_ would preclude using the term in the future to describe a formal standard.
248+
249+
250+
#### Potential overload of _language mode_
251+
Some reviewers raised concern that Embedded Swift could be considered a language mode and lead to future ambiguity.
252+
253+
On consideration, this concern is mitigated in two ways:
254+
255+
1. As noted above, the term _language mode_ is a well-established term of art in the Swift community.
256+
257+
2. The term _Embedded Swift_ already provides an unambiguous, concise name that can be discussed without requiring a reference to modes.
258+
259+
This is demonstrated by the following hypothetical FAQ based on the Embedded Swift vision document:
260+
> _What is Embedded Swift?_
261+
> Embedded Swift is a subset of Swift suitable for restricted environments such as embedded and low-level environments.
262+
>
263+
> _How do you enable Embedded Swift?_
264+
> Pass the `-embedded` compiler flag to compile Embedded Swift.
265+
266+
Considering these alternatives, it seems likely that introducing a new term to replace the long-established term _language mode_ and potentially giving the existing term a new meaning would lead to more ambiguity than keeping and formalizing the existing meaning of _language mode_.

0 commit comments

Comments
 (0)