[static-linux-sdk] Update "Getting Started with the Static Linux SDK" (#1120)

* [authors] add incertum

Signed-off-by: Melissa Kilby <[email protected]>

* [static-linux-sdk] Update "Getting Started with the Static Linux SDK"

Enhance clarity and transparency by adding more details about dependency management when using the Static Linux SDK, especially regarding the dependencies bundled with it.

Co-authored-by: Alastair Houghton <[email protected]>
Signed-off-by: Melissa Kilby <[email protected]>

* [static-linux-sdk] Update "Getting Started with the Static Linux SDK"

Add a comment contrasting the Linux SDK with Apple platforms.

Co-authored-by: Evan Wilde <[email protected]>
Signed-off-by: Melissa Kilby <[email protected]>

---------

Signed-off-by: Melissa Kilby <[email protected]>
Co-authored-by: Alastair Houghton <[email protected]>
Co-authored-by: Evan Wilde <[email protected]>

Author: 3 people

_data/authors.yml

@@ -533,3 +533,9 @@ umeshbatra13:
   name: Umesh Batra
   github: umeshbatra13
   about: "Umesh Batra is a member of the engineering team at Apple working on Password Monitoring and other Security Services."
+
+incertum:
+  name: Melissa Kilby
+  email: [email protected]
+  github: incertum
+  about: "Melissa Kilby works on the Swift for Linux Server team at Apple."

documentation/articles/static-linux-getting-started.md

@@ -2,7 +2,7 @@
 layout: page
 date: 2024-06-04 12:00:00
 title: Getting Started with the Static Linux SDK
-author: [al45tair]
+author: [al45tair, incertum, etcwilde]
 ---
 
 It's well known that Swift can be used to build software for Apple
@@ -24,12 +24,30 @@ with no external dependencies at all (not even the C library), which
 means that it will run on _any_ Linux distribution as the only thing
 it depends on is the Linux system call interface.
 
+This portability comes at a cost, namely that everything your program
+depends on must be statically linked. There is no support for dynamic
+linking whatsoever — even the `dlopen()` function will not work.
+
+A result of this design choice is that the Static Linux SDK uses a
+“bring your own dependencies” model, similar to that you might be used
+to with the Swift Package Manager. You cannot use system libraries,
+but must either rely on the handful of common libraries supplied with
+the Static SDK (see below), or build any extras yourself.
+
 Additionally, the Static Linux SDK can be used from any platform
 supported by the Swift compiler and package manager; this means that
 you can develop and test your program on macOS before building and
 deploying it to a Linux-based server, whether running locally or
 somewhere in the cloud.
 
+Finally, for those wondering about an equivalent for Apple platforms,
+no such static SDK exists. Building a fully static executable is not
+possible on Apple's operating systems because, unlike Linux, the
+Darwin kernel's system call table is not part of the ABI. This design
+requires all system calls to be routed through the dynamic library
+`libsystem.dylib`, fundamentally preventing a 100% statically linked
+binary.
+
 ### Static vs Dynamic Linking
 
 _Linking_ is the process of taking different pieces of a computer
@@ -255,7 +273,7 @@ in another, or a pointer type will be imported as `OpaquePointer`
 rather than `UnsafePointer<FOO>`.
 
 If you do find yourself needing to make these kinds of adjustments,
-you can make your local copy of the package dependency editable by
+you can make your [local copy](https://developer.apple.com/documentation/xcode/editing-a-package-dependency-as-a-local-package) of the package dependency editable by
 doing
 
 ```console
@@ -265,3 +283,69 @@ $ swift package edit SomePackage
 and then editing the files in the `Packages` directory that appears in
 your program's source directory.  You may wish to consider raising PRs
 upstream with any fixes you may have.
+
+If your project makes use of C or C++ language libraries, you may need
+to take additional steps. The Static SDK for Linux includes a small
+handful of very common dependencies (e.g.
+[libxml2](https://gitlab.gnome.org/GNOME/libxml2/-/wikis/home),
+[zlib](https://www.zlib.net/) and [curl](https://curl.se/)). There is
+a high bar for adding dependencies to the SDK itself, because it makes
+the SDK image larger, and means the SDK must be updated to track the
+versions of those dependencies.
+
+The Static SDK includes an SBOM, in [SPDX format](https://spdx.dev/),
+that you can use to determine exactly what is present in any given
+release of the Static SDK for Linux. For instance, using the `bom`
+tool, you can display the SBOM using a command like:
+
+```console
+$ bom document outline ~/.swiftpm/swift-sdks/swift-6.1.2-RELEASE-static-linux-0.0.1.artifactbundle/sbom.spdx.json
+              _      
+ ___ _ __   __| |_  __
+/ __| '_ \ / _` \ \/ /
+\__ \ |_) | (_| |>  < 
+|___/ .__/ \__,_/_/\_\
+    |_|               
+
+ 📂 SPDX Document SBOM-SPDX-648fa59a-9d9d-476f-9183-78d57d847c31
+  │ 
+  │ 📦 DESCRIBES 1 Packages
+  │ 
+  ├ Swift statically linked SDK for [email protected]
+  │  │ 🔗 7 Relationships
+  │  ├ GENERATED_FROM PACKAGE [email protected]
+  │  ├ GENERATED_FROM PACKAGE [email protected]
+  │  ├ GENERATED_FROM PACKAGE [email protected]
+  │  ├ GENERATED_FROM PACKAGE [email protected]
+  │  ├ GENERATED_FROM PACKAGE [email protected]
+  │  ├ GENERATED_FROM PACKAGE boringssl@fips-20220613
+  │  └ GENERATED_FROM PACKAGE [email protected]
+  │ 
+  └ 📄 DESCRIBES 0 Files
+```
+
+If your project has additional C/C++ dependencies, the process is the
+same as using any static library you’ve built yourself in any other
+context. You must ensure the static library (`.a` file) is in the
+linker’s search path. Additionally, if you intend to call the
+library's functions directly from your Swift code, you must also add
+its header files to the compiler's include path. The only
+Swift-specific part is that you will need a module map for the
+library, but this is also true outside of the Static SDK for Linux
+(see [Mixing Swift and
+C++](https://www.swift.org/documentation/cxx-interop/)).
+
+Some of the dependencies bundled in the Static SDK may be pulled in by
+Swift’s runtime libraries, if you use the functionality that requires
+them — for instance, Foundation Networking uses `libcurl` and
+`libcurl` uses `libz` — but because of the way static linking works,
+you will generally only “pay for what you use”.
+
+You may be able to override the versions of libraries that ship with
+the Static SDK by placing a newer build of the library earlier in the
+linker’s search path. Note however that where other libraries that
+ship with the Static SDK have been built against the library in
+question, your new build will need to be ABI compatible with the
+version that shipped in the Static SDK, since the other libraries in
+the Static SDK will have been built against the headers from the
+version that they ship with.