Skip to content

Commit 669c81c

Browse files
rauhulrauhul
authored
Add documentation catalog (#118)
Initial pass at migrating documentation from swiftlang/swift to a more accessible location and reformatting it into a docc catalog. I've added a number of placeholder pages for additional documentation to be written. Community members are very welcome to help contribute to this documentation.
1 parent 06cac28 commit 669c81c

17 files changed

+1037
-0
lines changed

‎.spi.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
version: 1
2+
builder:
3+
configs:
4+
- documentation_targets:
5+
- EmbeddedSwift

‎Package.resolved

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"originHash" : "ffbd64644921de7b1a9cb8b17d9ecb480b14c4b6487677314b16730c1b12221b",
3+
"pins" : [
4+
{
5+
"identity" : "swift-docc-plugin",
6+
"kind" : "remoteSourceControl",
7+
"location" : "https://github.com/swiftlang/swift-docc-plugin",
8+
"state" : {
9+
"revision" : "85e4bb4e1cd62cec64a4b8e769dcefdf0c5b9d64",
10+
"version" : "1.4.3"
11+
}
12+
},
13+
{
14+
"identity" : "swift-docc-symbolkit",
15+
"kind" : "remoteSourceControl",
16+
"location" : "https://github.com/swiftlang/swift-docc-symbolkit",
17+
"state" : {
18+
"revision" : "b45d1f2ed151d057b54504d653e0da5552844e34",
19+
"version" : "1.0.0"
20+
}
21+
}
22+
],
23+
"version" : 3
24+
}

‎Package.swift

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// swift-tools-version: 6.0
2+
3+
import PackageDescription
4+
5+
let package = Package(
6+
name: "swift-embedded-examples",
7+
products: [
8+
.library(name: "EmbeddedSwift", targets: ["EmbeddedSwift"])
9+
],
10+
dependencies: [
11+
.package(
12+
url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0")
13+
],
14+
targets: [
15+
.target(name: "EmbeddedSwift")
16+
])

‎Sources/EmbeddedSwift/Documentation.docc/BuildSystemSupport/IntegrateWithBazel.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Integrate with Bazel
2+
3+
🚧 Under construction...

‎Sources/EmbeddedSwift/Documentation.docc/BuildSystemSupport/IntegrateWithCMake.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Integrate with CMake
2+
3+
🚧 Under construction...

‎Sources/EmbeddedSwift/Documentation.docc/BuildSystemSupport/IntegrateWithMake.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Integrate with Make
2+
3+
🚧 Under construction...

‎Sources/EmbeddedSwift/Documentation.docc/BuildSystemSupport/IntegrateWithSwiftPM.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Integrate with SwiftPM
2+
3+
🚧 Under construction...

‎Sources/EmbeddedSwift/Documentation.docc/BuildSystemSupport/IntegrateWithXcode.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Integrate with Xcode
2+
3+
🚧 Under construction...
4+
5+
> Warning: Embedded Swift integration with Xcode is still under development and
6+
> subject to change.

‎Sources/EmbeddedSwift/Documentation.docc/Development/Status.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Status
2+
3+
**⚠️ Embedded Swift is experimental. This document might be out of date with latest development.**
4+
5+
**‼️ Use the latest downloadable 'Trunk Development' snapshot from swift.org to use Embedded Swift. Public releases of Swift do not yet support Embedded Swift.**
6+
7+
For an introduction and motivation into Embedded Swift, please see "[A Vision for Embedded Swift](https://github.com/swiftlang/swift-evolution/blob/main/visions/embedded-swift.md)", a Swift Evolution document highlighting the main goals and approaches.
8+
9+
## Embedded Swift Language Features
10+
11+
| **Language Feature** | **Currently Supported In Embedded Swift** |
12+
|-------------------------------------------------------|------------------------------------------------------------------------------------|
13+
| *Anything not listed below* | Yes |
14+
| Library Evolution (resilience) | No, intentionally unsupported long-term |
15+
| Objective-C interoperability | No, intentionally unsupported long-term |
16+
| Non-WMO builds | No, intentionally unsupported long-term (WMO should be used) |
17+
| Existentials (values of protocol types) | Only class-bound existentials (for protocols derived from AnyObject) are supported |
18+
| Any | No, currently disallowed |
19+
| AnyObject | Yes |
20+
| Metatypes | No, currently only allowed as unused arguments (type hints) |
21+
| Untyped throwing | No, intentionally unsupported long-term (typed throwing should be used instead) |
22+
| Weak references, unowned references | No |
23+
| Non-final generic class methods | No, intentionally unsupported long-term, see <[Embedded Swift -- Non-final generic methods](NonFinalGenericMethods.md)>|
24+
| Parameter packs (variadic generics) | No, not yet supported |
25+
26+
## Embedded Standard Library Breakdown
27+
28+
This status table describes which of the following standard library features can be used in Embedded Swift:
29+
30+
| **Swift Standard Library Feature** | **Currently Supported In Embedded Swift?** |
31+
|------------------------------------------------------------|-----------------------------------------------------|
32+
| Array (dynamic heap-allocated container) | Yes |
33+
| Array slices | Yes |
34+
| assert, precondition, fatalError | Partial, only StaticStrings can be used as a failure message |
35+
| Bool, Integer types, Float types | Yes |
36+
| Codable, Encodable, Decodable | No |
37+
| Collection + related protocols | Yes |
38+
| Collection algorithms (sort, reverse) | Yes |
39+
| CustomStringConvertible, CustomDebugStringConvertible | Yes, except those that require reflection (e.g. Array's .description) |
40+
| Dictionary (dynamic heap-allocated container) | Yes |
41+
| Floating-point conversion to string | No |
42+
| Floating-point parsing | No |
43+
| FixedWidthInteger + related protocols | Yes |
44+
| Hashable, Equatable, Comparable protocols | Yes |
45+
| InputStream, OutputStream | No |
46+
| Integer conversion to string | Yes |
47+
| Integer parsing | Yes |
48+
| KeyPaths | Partial (only compile-time constant key paths to stored properties supported, only usable in MemoryLayout and UnsafePointer APIs) |
49+
| Lazy collections | Yes |
50+
| ManagedBuffer | Yes |
51+
| Mirror (runtime reflection) | No, intentionally unsupported long-term |
52+
| Objective-C bridging | No, intentionally unsupported long-term |
53+
| Optional | Yes |
54+
| print / debugPrint | Partial (only String, string interpolation, StaticStrings, integers, pointers and booleans, and custom types that are CustomStringConvertible) |
55+
| Range, ClosedRange, Stride | Yes |
56+
| Result | Yes |
57+
| Set (dynamic heap-allocated container) | Yes |
58+
| SIMD types | Yes |
59+
| StaticString | Yes |
60+
| String (dynamic) | Yes |
61+
| String interpolations | Partial (only strings, integers, booleans, and custom types that are CustomStringConvertible can be interpolated) |
62+
| Unicode | Yes |
63+
| Unsafe\[Mutable\]\[Raw\]\[Buffer\]Pointer | Yes |
64+
| VarArgs | No |
65+
66+
## Non-stdlib Features
67+
68+
This status table describes which of the following Swift features can be used in Embedded Swift:
69+
70+
| **Swift Feature** | **Currently Supported In Embedded Swift?** |
71+
|------------------------------------------------------------|-----------------------------------------------------|
72+
| Synchronization module | Partial (only Atomic types, no Mutex) |
73+
| Swift Concurrency | Partial, experimental (basics of actors and tasks work in single-threaded concurrency mode) |
74+
| C interop | Yes |
75+
| C++ interop | Yes |
76+
| ObjC interop | No, intentionally unsupported long-term |
77+
| Library Evolution | No, intentionally unsupported long-term |

0 commit comments

Comments
 (0)