Add initial WIP IntegrateWithZephyr document

Author: xtremekforever

.gitignore

@@ -1,6 +1,6 @@
 .DS_Store
 **/.DS_Store
-*/.build
+.build/
 */build
 */sdkconfig
 */sdkconfig.old

Sources/EmbeddedSwift/Documentation.docc/Documentation.md

@@ -190,6 +190,7 @@ The malloc/calloc/free APIs are expected to be provided by the platform. The Swi
 ### SDK Support
 
 - <doc:IntegrateWithPico>
+- <doc:IntegrateWithZephyr>
 
 ### Language Details
 

Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegrateWithZephyr.md

@@ -0,0 +1,152 @@
+# Integrating with Zephyr
+
+**⚠️ Embedded Swift is experimental. This document might be out of date with latest development.**
+
+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.
+
+Refer to the [nrfx-blink-sdk](../../../../nrfx-blink-sdk/) project for a complete working "blinky" example that can be used as a starting point. However, for a formal introduction to setting up a Swift Zephyr project and explanations into the various options, continue reading this document.
+
+## Zephyr Setup
+
+Before setting up a Swift project that works with Zephyr, you need to setup dependencies and a Zephyr workspace as per the [Getting Started Guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html). Regardless of your platform (macOS or Linux), ensure that you can build the blinky example without errors before starting with Swift integration:
+
+```bash
+cd ~/zephyrproject/zephyr
+west build -p always -b <your-board-name> samples/basic/blinky
+```
+
+By default, the `main` revision of the Zephyr sources are checked out when calling `west init`, which contains pre-release and development changes that may cause instability and changing APIs that are not desirable. To checkout a specific release version of Zephyr, use the following commands:
+
+```bash
+cd ~/zephyrproject/zephyr
+git checkout v4.1.0
+west update
+west packages pip --install
+
+# For older versions of Zephyr (pre 4.1.0), use:
+pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt
+```
+
+Refer to the [Zephyr Releases](https://docs.zephyrproject.org/latest/releases/index.html) page for more information on current and LTS releases.
+
+## Project Setup
+
+Once Zephyr is setup, the next step is to setup a project with a bridging header, `CMakeLists.txt`, `Main.swift`, and `prj.conf`:
+
+```plain
+SwiftZephyrProject/BridgingHeader.h
+SwiftZephyrProject/CMakeLists.txt
+SwiftZephyrProject/Main.swift
+SwiftZephyrProject/prj.conf
+```
+
+These are the minimum required files in order to build a Zephyr project. For example, `prj.conf` is required even if it is empty, or the project will not build.
+
+Inside of `BridgingHeader.h`, add the following content as a minimum:
+
+```c
+#pragma once
+
+#include <autoconf.h>
+```
+
+The `Main.swift` file must contain a `static func main()` as follows:
+
+```swift
+@main
+struct Main {
+  static func main() {
+    // code
+  }
+}
+```
+
+### CMakeLists.txt Setup
+
+The `CMakeLists.txt` setup is more involved and complex since target, compilation flags, and library linking must be specified for Swift. First, some initial setup and flags:
+
+```cmake
+cmake_minimum_required(VERSION 3.29)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+
+# Use the armv7em-none-none-eabi target triple for Swift
+set(CMAKE_Swift_COMPILER_TARGET armv7em-none-none-eabi)
+# Enable "wmo" as needed by Embedded Swift
+set(CMAKE_Swift_COMPILATION_MODE wholemodule)
+# FIXME: Skip checking if the compiler works
+set(CMAKE_Swift_COMPILER_WORKS true)
+
+# Create a new project called "SwiftZephyrProject" and enable "Swift" as a supported language
+project(SwiftZephyrProject Swift)
+```
+
+The following flags have been curated to work well with `armv7em-none-none-eabi` target with `swiftc`. Some flags may need to change depending on the chosen target:
+
+```cmake
+# Set global Swift compiler flags
+add_compile_options(
+    # Enable Embedded Swift
+    "$<$<COMPILE_LANGUAGE:Swift>:SHELL:-enable-experimental-feature Embedded>"
+
+    # Enable function sections to enable dead code stripping on elf
+    "$<$<COMPILE_LANGUAGE:Swift>:SHELL:-Xfrontend -function-sections>"
+
+    # Use software floating point operations matching GCC
+    "$<$<COMPILE_LANGUAGE:Swift>:SHELL:-Xcc -mfloat-abi=soft>"
+
+    # Use compacted C enums matching GCC
+    "$<$<COMPILE_LANGUAGE:Swift>:SHELL:-Xcc -fshort-enums>"
+
+    # Disable PIC
+    "$<$<COMPILE_LANGUAGE:Swift>:SHELL:-Xcc -fno-pic>"
+
+    # Add Libc include paths
+    "$<$<COMPILE_LANGUAGE:Swift>:SHELL:-Xcc -I -Xcc ${ZEPHYR_SDK_INSTALL_DIR}/arm-zephyr-eabi/picolibc/include>"
+)
+```
+
+The following block will automatically grab Zephyr compilation flags (such as `-D__ZEPHYR__=1` and `-DKERNEL`) and set them as Swift compiler definitions. This is required to successfully build Swift code that works with Zephyr:
+
+```cmake
+# Add definitions from Zephyr to -Xcc flags
+get_target_property(ZEPHYR_DEFINES zephyr_interface INTERFACE_COMPILE_DEFINITIONS)
+if(ZEPHYR_DEFINES)
+    foreach(flag ${ZEPHYR_DEFINES})
+        # Ignore expressions like "$<SOMETHING>"
+        string(FIND "${flag}" "$<" start_of_expression)
+        if(NOT start_of_expression EQUAL -1)
+            continue()
+        endif()
+
+        add_compile_options("$<$<COMPILE_LANGUAGE:Swift>:SHELL:-Xcc -D${flag}>")
+    endforeach()
+endif()
+```
+
+Finally, setup targets, libraries, and additional compile options:
+
+```cmake
+# The Swift code providing "main" needs to be in an OBJECT library (instead of STATIC library) to make sure it actually gets linker.
+# A STATIC library would get dropped from linking because Zephyr provides a default weak empty main definition.
+add_library(app_swift OBJECT Main.swift)
+
+add_dependencies(app_swift syscall_list_h_target)
+target_compile_options(app_swift PRIVATE
+    -parse-as-library
+
+    -Osize
+
+    -Xfrontend -disable-stack-protector
+
+    # FIXME: add dependency on BridgingHeader.h
+    -import-bridging-header ${CMAKE_CURRENT_LIST_DIR}/BridgingHeader.h
+)
+
+# Copy include paths from C target to Swift target
+target_include_directories(app_swift PRIVATE
+    "$<TARGET_PROPERTY:app,INCLUDE_DIRECTORIES>"
+)
+
+# Link the Swift target into the primary target
+target_link_libraries(app PRIVATE app_swift)
+```