Documentation

Author: ole

CMakeLists.txt

@@ -35,24 +35,27 @@ endif ()
 include(pico_sdk_import.cmake)
 
 # Configure Swift. This must happen before `project()`. I don't know why.
+# Use nightly Swift compiler, configured for Embedded Swift.
+# Find path to swiftc and store it in swiftc_Path
 execute_process(
     COMMAND xcrun --toolchain "${Swift_Toolchain}" --find swiftc
     OUTPUT_VARIABLE swiftc_Path
     OUTPUT_STRIP_TRAILING_WHITESPACE
 )
-# Use nightly Swift compiler, configured for Embedded Swift.
 set(CMAKE_Swift_COMPILER
     "${swiftc_Path}"
 )
 set(CMAKE_Swift_FLAGS
-    # - WMO is always required for Embedded Swift.
+    # Whole-module optimization is always required for Embedded Swift.
     "-enable-experimental-feature Embedded -wmo -target armv6m-none-none-eabi"
 )
-# Disable CMAKE Swift compiler check. The compiler check always fails for
-# Embedded Swift because it tries to compile a Swift program that includes
-# `print()`, which isn't available in Embedded Swift.
+# Disable CMake’s automatic Swift compiler check. The compiler check always 
+# fails for Embedded Swift because it tries to compile a Swift program that 
+# includes `print()`, which isn't available in Embedded Swift.
 set(CMAKE_Swift_COMPILER_FORCED TRUE)
 
+# === Begin project configuration
+
 project(PicoLinksSwift LANGUAGES C CXX Swift)
 
 # Initialize the Raspberry Pi Pico SDK

README.md

@@ -12,35 +12,42 @@ A proof of concept for executing Embedded Swift code on the [Raspberry Pi Pico](
 ### Software
 
 - Host OS: macOS 13.x or 14.x
+  
+  Tested on macOS 13.6.2. It’ll probably work on Linux with minimal modifications to tell CMake how to find the Swift toolchain, but I haven’t tested this.
 
-- A recent nightly Swift toolchain from [swift.org](https://www.swift.org/download/). Tested with the December 7, 2023 toolchain.
+- A recent nightly Swift toolchain from [swift.org](https://www.swift.org/download/). Tested with the Xcode toolchain from December 7, 2023.
 
 - A clone of the [Raspberry Pi Pico C/C++ SDK](https://github.com/raspberrypi/pico-sdk/):
 
   ```sh
-  # This project expects to find pico-sdk in a sibling directory to itself.
   cd ..
   git clone https://github.com/raspberrypi/pico-sdk.git
   cd pico-sdk/
   git submodule update --init
   cd ..
   ```
 
+  This project expects to find the SDK in a sibling directory named `pico-sdk`. You can change this below if your SDK is in a different place.
+
+- The GCC compiler for ARM embedded platforms
+
 - [CMake](https://cmake.org/) and [Ninja](https://ninja-build.org/):
 
   ```sh
   brew install cmake ninja
   ```
 
+  The Pico SDK uses CMake as its build system and we’re piggybacking on that. The Swift library is also built with CMake. The unfortunate consequence is that we can’t easily use a [SwiftPM](https://www.swift.org/package-manager/) package for the Swift library as we’d have to tell CMake how to build the package.
+
 ## Configuration
 
 Open the file `CMakeLists.txt` in the root folder. Edit these two lines to match your setup:
 
 ```cmake
 …
-    set(PICO_SDK_PATH "${CMAKE_CURRENT_LIST_DIR}/../pico-sdk")
+set(PICO_SDK_PATH "${CMAKE_CURRENT_LIST_DIR}/../pico-sdk")
 …
-    set(Swift_Toolchain "org.swift.59202312071a")
+set(Swift_Toolchain "org.swift.59202312071a")
 …
 ```
 
@@ -54,7 +61,11 @@ cmake -G Ninja ..
 ninja
 ```
 
-This produces the executable `PicoLinksSwift.elf` in the `build` directory. You have two options to copy this to the Pico:
+This produces the executable `PicoLinksSwift.elf` in the `build` directory.
+
+## Running on the Pico
+
+You have two options to copy the executable to the Pico:
 
 1. Via the USB Mass Storage interface: use the provided `build/elf2uf2/elf2uf2` tool to convert the `.elf` file to `.uf2`.
 2. Via the debug probe. I use [probe.rs](https://probe.rs/) for this, which is a tool from the Rust community, but it works in this context too:

main.c

@@ -8,7 +8,7 @@ int main()
     stdio_init_all();
     printf("main() start\n");
 #ifndef PICO_DEFAULT_LED_PIN
-#warning blink example requires a board with a regular LED
+#warning Program requires a board with a regular LED (e.g. *not* the Pico W as its LED is wired to the Wi-Fi chip)
 #else
     const uint LED_PIN = PICO_DEFAULT_LED_PIN;
     gpio_init(LED_PIN);