Skip to content

[embedded] Update UserManual.md and EmbeddedSwiftStatus.md with some additional information #71523

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

Merged
merged 1 commit into from
Feb 13, 2024
Merged

[embedded] Update UserManual.md and EmbeddedSwiftStatus.md with some additional information #71523

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
14 changes: 9 additions & 5 deletions docs/EmbeddedSwift/EmbeddedSwiftStatus.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ For an introduction and motivation into Embedded Swift, please see "[A Vision fo

This status table describes which of the following standard library features can be used in Embedded Swift:

| **Swift Standard Library Feature** | **Currently Supported In Embedded Swift** |
|---------------------------------------------|-----------------------------------------------------|
| **Swift Standard Library Feature** | **Currently Supported In Embedded Swift?** |
Copy link
Contributor

Choose a reason for hiding this comment

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

Fun fact, you don't need to pad the columns out. Markdown will render this nicely:

| **Foo** | **Bar** |
|-|-|
| Alpha. | Beta. |
| Gamma delta epsilon eridani. | Live long and prosper. |
Foo Bar
Alpha. Beta.
Gamma delta epsilon eridani. Live long and prosper.

|------------------------------------------------------------|-----------------------------------------------------|
| Array (dynamic heap-allocated container) | Yes |
| Array slices | Yes |
| assert, precondition, fatalError | Partial, only StaticStrings can be used as a failure message |
Expand Down Expand Up @@ -46,6 +46,10 @@ This status table describes which of the following standard library features can

This status table describes which of the following Swift features can be used in Embedded Swift:

| **Swift Feature** | **Currently Supported In Embedded Swift** |
|---------------------------------------------|-----------------------------------------------------|
| Swift Concurrency | Partial, experimental (basics of actors and tasks work in single-threaded concurrency mode) |
| **Swift Feature** | **Currently Supported In Embedded Swift?** |
|------------------------------------------------------------|-----------------------------------------------------|
| Swift Concurrency | Partial, experimental (basics of actors and tasks work in single-threaded concurrency mode) |
| C interop | Yes |
| C++ interop | Yes |
| ObjC interop | No, intentionally unsupported long-term |
| Library Evolution | No, intentionally unsupported long-term |
28 changes: 27 additions & 1 deletion docs/EmbeddedSwift/UserManual.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,32 @@ Segment __TEXT: 16384
...
```

## Conditionalizing compilation for Embedded Swift

It's often useful to have source code be compilable under both regular Swift and Embedded Swift. The following syntax is available for that (but note that as the rest of Embedded Swift, it's experimental, subject to change and not considered source stable):

```swift
func sayHello() {
#if hasFeature(Embedded)
Copy link
Member

Choose a reason for hiding this comment

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

$Embedded; hasFeature doesn't check if the feature is enabled if I recall correctly

Copy link
Contributor

Choose a reason for hiding this comment

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

This is an important distinction we should call out because user guidance is to use hasFeature(), not $.

Or maybe there should be a targetEnvironment(embedded) condition.

print("I'm Embedded Swift")
#else
print("I'm regular Swift")
#endif
}
```

Additionally, you can also use an attribute (also experimental, and not source stable) to make entire functions, types and other declarations unavailable in Embedded Swift. This can be particularly useful to explicitly mark your own code (and also entire types and conformances) that relies on features unavailable in Embedded Swift, e.g. existentials or strings -- it is explicitly allowed to use those in unavailable contexts:

```swift
@_unavailableInEmbedded
func useAnExistential(_: Any) { ... }

@_unavailableInEmbedded
extension MyStruct: CustomStringConvertible {
var description: String { return "..." }
}
```

## Embedded Swift is a subset of Swift

Embedded Swift is a subset of the Swift language, and some features are not available in Embedded Swift, however features are available, including: Generics, protocols, enums with associated values, tuples, optionals, classes (instances are allocated on the heap and refcounted just like in regular Swift), inheritance, runtime polymorphism, arrays (heap-allocated copy-on-write just like in regular Swift) and many more.
Expand All @@ -119,7 +145,7 @@ Traditional library build and use model of Swift is that library code is compile

The library model in Embedded Swift works slightly differently: All Swift source code of a library is promoted into being inlineable and visible to client builds (this is necessary for generic code, and beneficial for optimizations for non-generic code), and ends up serialized into the .swiftmodule, the interface of the library. Therefore, the compiled code of a library is never needed, and doesn't even need to be produced. For example:

```
```bash
# Build the library, only as a .swiftmomodule. Notice that we never build the .o or .a for the library.
$ swiftc -target <target> -enable-experimental-feature Embedded -wmo \
a.swift b.swift -module-name MyLibrary -emit-module -emit-module-path ./MyLibrary.swiftmodule
Expand Down