Update Embedded Swift macOS guides (#147)

Combines and updates the documentation for trying out Embedded Swift on macOS.

Fixes #146

Author: andre-richter

Sources/EmbeddedSwift/Documentation.docc/GuidedExamples/macOSGuide.md

@@ -19,25 +19,49 @@ And building it into an executable can be done by calling the `swiftc` compiler
 $ swiftc HelloEmbedded.swift -o HelloEmbedded -enable-experimental-feature Embedded -wmo
 ```
 
-This will produce a regular executable binary, but notice that it's very small in size and that it also *does not actually depend on the Swift runtime in the OS* (all Embedded Swift binaries carry their runtime+stdlib dependencies within):
+This will produce a regular executable binary, and we can execute it right away:
+
+```shell
+$ ./HelloEmbedded
+Hello, Embedded Swift 😊
+```
+Hooray! Our first *host-side* Embedded Swift program is working!
+
+## Details
+
+Looking closer, this binary *does not actually depend on the Swift runtime in the OS* (all Embedded Swift binaries carry their runtime+stdlib dependencies within), but it is still a *dynamically-linked executable*, so it's not fully standalone in the embedded sense:
 
 ```shell
-$ ls -al
--rwxr-xr-x    1 kuba  staff    18K May 16 17:19 HelloEmbedded*
--rw-r--r--    1 kuba  staff    59B May 16 17:16 HelloEmbedded.swift
 $ otool -L HelloEmbedded
 HelloEmbedded:
-  /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1000.0.0)
+        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1000.0.0)
 ```
 
-Let's run it:
+However, the singular object file that was used to build this executable was produced by the compiler in the same fashion that a real embedded build would. If we ask the compiler and linker to minimize the size of the outputs and to remove any unused code, we can observe that the binary has no dependencies other than `putchar` from `libSystem` and that the machine code section is very small (176 bytes in the `__text` section):
 
 ```shell
-$ ./HelloEmbedded
-Hello, Embedded Swift 😊
+$ swiftc HelloEmbedded.swift -o HelloEmbedded -enable-experimental-feature Embedded -wmo -Osize -Xlinker -dead_strip
+
+$ nm -um HelloEmbedded
+                 (undefined) external _putchar (from libSystem)
+
+$ size -m HelloEmbedded
+Segment __TEXT: 16384
+        Section __text: 176
+...
 ```
 
-Hooray! Our first *host-side* Embedded Swift program is working!
+In contrast, if compiled without the Embedded Swift flags, we can see the dependencies on the Swift runtime in the OS:
+
+```shell
+$ swiftc HelloEmbedded.swift -o HelloEmbedded
+
+$ otool -L HelloEmbedded
+HelloEmbedded:
+        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1000.0.0)
+        /usr/lib/swift/libswiftCore.dylib (compatibility version 1.0.0, current version 0.0.0)
+        /usr/lib/swift/libswiftSwiftOnoneSupport.dylib (compatibility version 1.0.0, current version 0.0.0)
+```
 
 ## Where to go next
 

Sources/EmbeddedSwift/Documentation.docc/UsingEmbeddedSwift/Basics.md

@@ -76,31 +76,3 @@ It's very common to integrate with existing SDKs in embedded development. This t
 Most embedded SDKs provide a build system integration, commonly with CMake, Make, or their own custom build scripts. At the most basic level, it's always possible to manually call the compiler (`swiftc`) as described above from any build system. This will produce a .o file for the entire Swift module, and then a .o file can typically be directly used in the build system.
 
 For details and concrete examples of how to integrate with more common platforms, SDKs and build systems, see <doc:IntegratingWithPlatforms>.
-
-### Building a macOS Embedded Swift program:
-
-It's also possible to build in Embedded Swift mode for regular non-embedded operating systems, like macOS. This is very useful for testing purposes, or if you just want to observe and experiment with Embedded Swift. A simple source code like this:
-
-```swift
-print("Hello, embedded world!")
-```
-
-...can be compiled using the `-enable-experimental-feature Embedded` flag (the implicit `-target` matches the host OS):
-
-```bash
-$ swiftc hello.swift -enable-experimental-feature Embedded -wmo
-$ ./hello
-Hello, embedded world!
-```
-
-Note that the resulting executable is still a *dynamically-linked executable*, so it's not fully standalone in the embedded sense. Namely is still uses `putchar` from Libsystem. But the singular object file that was used to build this executable was produced by the compiler in the same fashion that a real embedded build would. If we ask the compiler and linker to minimize the size of the outputs and to remove any unused code, we can observe that the binary has no other dependencies other than `putchar` and that the machine code section is very small (172 bytes in the `__text` section):
-
-```bash
-$ swiftc hello.swift -enable-experimental-feature Embedded -wmo -Osize -Xlinker -dead_strip
-$ nm -um ./hello
-                 (undefined) external _putchar (from libSystem)
-$ size -m ./hello
-Segment __TEXT: 16384
-  Section __text: 172
-...
-```