Major expansion of documentation for Embedded Swift

Documentation/README.md

@@ -0,0 +1,6 @@
+Documentation for Embedded Swift
+================================
+
+Documentation for Embedded Swift can be found at these locations:
+- [in rendered form](https://swiftpackageindex.com/apple/swift-embedded-examples/documentation/embeddedswift)
+- [DocC source code](/Sources/EmbeddedSwift/Documentation.docc)

Sources/EmbeddedSwift/Documentation.docc/LanguageDetails/ABI.md → Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/ABI.md

@@ -1,10 +1,6 @@
-# ABI
+# ABI of Embedded Swift
 
-**⚠️ Embedded Swift is experimental. This document might be out of date with latest development.**
-
-**‼️ Use the latest downloadable 'Trunk Development' snapshot from swift.org to use Embedded Swift. Public releases of Swift do not yet support Embedded Swift.**
-
-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.
+Understanding the different ABI (Application Binary Interface) for Embedded Swift
 
 ## ABI stability
 
@@ -14,7 +10,7 @@ Similarly, do not mix Embedded Swift code with full Swift code, as the ABIs are
 
 ## Symbol mangling under Embedded Swift
 
-Since Swift 5.0, the stable ABI mangling schema uses the `$s` prefix on all Swift symbols. Because Embedded Swift's ABI differs from the stable ABI, and furthermore because it's not expected to be stable, Embedded Swift uses a `$e` mangling prefix. The logic and structure of the mangling stays the same, the only difference is the prefix.
+Since Swift 5.0, the stable ABI mangling scheme uses the `$s` prefix on all Swift symbols. Because Embedded Swift's ABI differs from the stable ABI, and furthermore because it's not expected to be stable, Embedded Swift uses a `$e` mangling prefix. The logic and structure of the mangling stays the same, the only difference is the prefix.
 
 ## Calling convention of Embedded Swift
 

Sources/EmbeddedSwift/Documentation.docc/Development/Status.md → Sources/EmbeddedSwift/Documentation.docc/CompilerDetails/Status.md

@@ -1,10 +1,6 @@
-# Status
+# Implementation Status
 
-**⚠️ Embedded Swift is experimental. This document might be out of date with latest development.**
-
-**‼️ Use the latest downloadable 'Trunk Development' snapshot from swift.org to use Embedded Swift. Public releases of Swift do not yet support Embedded Swift.**
-
-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.
+Implementation status of compiler and language features in Embedded Swift, comparison to standard Swift
 
 ## Embedded Swift Language Features
 

Sources/EmbeddedSwift/Documentation.docc/GettingStarted/InstallEmbeddedSwift.md

@@ -1,10 +1,10 @@
 # Install Embedded Swift
 
-Get the tools needed to use Embedded Swift.
+Get the tools needed to use Embedded Swift
 
 ## Overview
 
-Embedded Swift is an experimental and rapidly developing feature of the Swift language, as such it is only available in "Development Snapshot". 
+> Warning: Embedded Swift is experimental. Use the latest downloadable 'Trunk Development' snapshot from swift.org to use Embedded Swift. Public releases of Swift do not yet support Embedded Swift.
 
 The best way to install Swift is using [`swiftly`](http://github.com/swiftlang/swiftly), the official Swift toolchain installer and manager. For instructions on how to install `swiftly`, check out the [Getting Started](https://www.swift.org/swiftly/documentation/swiftly/getting-started) guide.
 

Sources/EmbeddedSwift/Documentation.docc/GettingStarted/Introduction.md

@@ -0,0 +1,59 @@
+# Introduction to Embedded Swift
+
+Write Swift code for microcontrollers, embedded systems, and bare-metal applications
+
+## Overview
+
+Embedded Swift is an experimental and rapidly developing feature of the Swift language that enables development of baremetal, embedded and standalone software. It's a subset of the Swift language designed for producing small, efficient binaries with minimal dependencies, making it suitable for resource-constrained environments.
+
+> Warning: Embedded Swift is experimental. Use the latest downloadable 'Trunk Development' snapshot from swift.org to use Embedded Swift. Public releases of Swift do not yet support Embedded Swift.
+
+## How does Embedded Swift differ from regular Swift?
+
+Regular Swift is not a good fit for small constrained environments like microcontrollers, mainly due to codesize and memory footprint. Regular Swift typically requires at least a few megabytes of code and data to support dynamic language features like reflection, and separately compiled generics with ABI stability. Embedded Swift, on the other hand, can be deployed to environments with as little as kilobytes of available memory. This is achieved by:
+
+- Eliminating runtime type metadata where possible
+- Removing reflection capabilities
+- Using compile-time specialization (monomorphization) for generic code
+- Minimizing dependencies on external libraries
+
+This results in properties that are a great fit for embedded software development:
+
+- **Small binaries** that can be as tiny as a few hundred bytes for "Hello World"-like programs (fully self-contained).
+- **No hidden runtime costs** – Embedded Swift's runtime library does not manage any data structures behind your back, is itself less than a kilobyte in size, and it eligible to be removed if unused.
+- **Full C/C++ interoperability** to directly interact with existing C libraries and hardware-specific code, making it easy to integrate with vendor SDKs.
+- **Modern language features** like optionals, generics, and strong type safety are all available in Embedded Swift.
+- **Full safety of Swift** is retained in Embedded Swift.
+
+For a detailed 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. Note that this is a historical document and does not capture latest development and further evolution. For an up-to-date in-depth breakdown of the language features of Embedded Swift, please see <doc:LanguageSubset>.
+
+## What Embedded Swift is and isn't
+
+- Embedded Swift **is** a way to produce small and freestanding binaries (with no, or trivial dependencies).
+- Embedded Swift **is not** a complete one-click solution to program all embedded boards and MCUs.
+- Embedded Swift **is** a compilation model that's analogous to a traditional C compiler in the sense that the compiler produces an object file (.o) that can be simply linked with your existing code, and it's not going to require you to port any libraries or runtimes.
+- Embedded Swift **is not** a HAL, it's not an SDK for development, it's not a set of libraries to program peripherals using high-level APIs. It's instead a compilation mode that's suitable for creating these components.
+
+## Platform support
+
+The Swift toolchain has the ability to produce code for almost any standard ARM and RISC-V platform, and that makes Embedded Swift versatile and not limited to specific platforms or hardware devices. This way, Embedded Swift can potentially target many different microcontroller families and embedded devices.
+
+Boards with active community support include the Raspberry Pi Pico, various STM32 development boards, and several ESP32 variants, with more platforms being regularly added as the community grows.
+
+## Interoperability with existing SDKs
+
+Software projects using Embedded Swift are typically developed in one of the following ways:
+
+1. Integrating with an existing SDK (typically in C, or C++) that provides either an embedded OS, or OS-like facilities, hardware drivers, and overall functionality that's needed for embedded software.
+
+2. Writing fully "bare-metal" code, without any pre-existing setup or SDK. This is typically done for extremely constrained environments and/or when full control of every piece of code is needed.
+
+Both the approaches are readily available in Embedded Swift, and the choice of which approach to use depends on your specific project requirements, hardware constraints, and development preferences. For integrating with existing SDKs, Swift's C/C++ interoperability makes it straightforward to call native SDK functions, while the bare-metal approach gives you complete control over every aspect of your code's execution environment.
+
+## Getting Started
+
+To start using Embedded Swift, please see the <doc:InstallEmbeddedSwift> page for installation instructions.
+
+Once you've set up the toolchain, we recommend exploring the <doc:WaysToGetStarted> page which provides various paths for getting started, including the <doc:macOSGuide> to try Embedded Swift on your development machine, and more advanced guides such as <doc:PicoGuide> for programming an actual embedded device.
+
+For details about using Embedded Swift, consult the <doc:Basics> documentation, which explains how to build code with Embedded Swift and shows integration patterns with embedded SDKs and build systems.

Sources/EmbeddedSwift/Documentation.docc/GettingStarted/LanguageSubset.md

@@ -0,0 +1,29 @@
+# Language subset
+
+Details of the Embedded Swift language subset compared to full Swift
+
+Embedded Swift is a subset of the Swift language, and some features are not available in Embedded Swift. This is necessary in order to achieve small binaries with effective dead-code elimination and minimized system dependencies.
+
+That said, *the vast majority* of the Swift language works exactly the same in Embedded Swift. This includes 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 much more.
+
+Note that there are no behavior changes in Embedded Swift compared to full Swift, and Embedded Swift is strictly a *subset* and not a *dialect*. Any code compatible with Embedded Swift will also compile and have the same semantics in full Swift.
+
+## Code-level features that are not available
+
+- **Not available**: Runtime reflection (`Mirror` APIs).
+- **Not available**: Values of protocol types ("existentials"), unless the protocol is restricted to be class-bound (derived from AnyObject). E.g. `let a: Hashable = ...` is not allowed. `Any` is also not allowed. See <doc:Existentials> for details and alternatives of existentials.
+- **Not available**: Throwing errors or `any Error` type (in contrast with "typed throws", which *is* supported in Embedded Swift).
+- **Not available**: Metatypes, e.g. `let t = SomeClass.Type` or `type(of: value)` are not allowed.
+- **Not available**: Printing and stringification of arbitrary types (which is achieved via reflection in desktop Swift).
+- **Not available**: Using non-final generic class methods. See <doc:NonFinalGenericMethods> for details on this.
+- **Not available**: Weak and unowned references.
+
+## Compilation facilities that are not available
+
+- **Not available**: Library Evolution (stable ABI), and facilities that requires Library Evolution (e.g. internal module imports)
+- **Not available**: Objective-C interoperability
+- **Not available**: Builds without WMO (whole module optimization)
+
+## Further resources
+
+The above lists are describing features that are removed from Embedded Swift *by design*. Since Embedded Swift is currently an experimental preview, there might also be  features that are not yet implemented. See the in-development status at [Embedded Swift -- Status](EmbeddedSwiftStatus.md).