Specify operation of auditing tool using llvm-objdump

Author: daniel-grumberg

proposals/XXXX-swiftpm-static-library-binary-target-non-apple-platforms.md

@@ -1,7 +1,7 @@
 # Binary Static Library Dependencies
 
 * Proposal: [SE-NNNN](NNNN-filename.md)
-* Authors:
+* Authors: [Daniel Grumberg](https://github.com/daniel-grumberg), [Max Desiatov](https://github.com/MaxDesiatov), [Franz Busch](https://github.com/FranzBusch)
 * Review Manager: TBD
 * Status: **Awaiting implementation**
 
@@ -21,7 +21,7 @@
 
 Swift continues to grow as a cross-platform language supporting a wide variety of use cases from [programming embedded device](https://www.swift.org/blog/embedded-swift-examples/) to [server-side development](https://www.swift.org/documentation/server/) across a multitude of [operating systems](https://www.swift.org/documentation/articles/static-linux-getting-started.html). 
 However, currently SwiftPM supports linking against binary dependencies on Apple platforms only.
-This proposal aims to make it possible to provide static library dependencies on non-Apple platforms.
+This proposal aims to make it possible to provide static library dependencies exposing a C interface on non-Apple platforms.
 
 Swift-evolution thread: 
 
@@ -37,7 +37,7 @@ In the current version of SwiftPM, binary targets support the following:
 
 We aim here to bring a subset of the XCFramework capabilities to non-Apple platforms in a safe way.
 
-While this proposal is specifically focused on binary static library dependencies without unresolved external symbols on non-Apple platforms,
+While this proposal is specifically focused on binary static library dependencies without unexpected unresolved external symbols on non-Apple platforms,
 it tries to do so in a way that will not prevent broader future support for static libraries and dynamically linked libraries.
 
 ## Proposed solution
@@ -50,7 +50,7 @@ The artifact manifest would encode the following information for each variant:
 * Enough information to be able to use the library's API in the packages source code, 
   i.e., headers and module maps for libraries exporting a C-based interface.
 
-Additionnaly, we propose the addition of an auditing tool that can validate the library artifact is safe to use across the platforms supported by the Swift project.
+Additionnaly, we propose the addition of an auditing tool that can validate the library artifact is safe to use across the Linux-based platforms supported by the Swift project.
 Such a tool would ensure that people do not accidentally distribute artifacts that require dependencies that are not met on the various deployment platforms.
 
 ## Detailed design
@@ -120,13 +120,20 @@ Without proper auditing it would be very easy to provide binary static library a
 
 We propose the introduction of a new tool that can validate the "safety" of a binary library artifact across the platforms it supports and the corresponding runtime environment.
 
-In this proposal we restrict ourselves to static libraries that do not have any external dependencies.
+In this proposal we restrict ourselves to static libraries that do not have any external dependencies beyond the C standard library and runtime.
 To achieve this we need to be able to detect validate this property across the three object file formats used in static libraries on our supported platforms: [Mach-O](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/CodeFootprint/Articles/MachOOverview.html#//apple_ref/doc/uid/20001860-BAJGJEJC) on Apple platforms, [ELF](https://refspecs.linuxfoundation.org/elf/elf.pdf) on Linux-based platforms, and [COFF](https://learn.microsoft.com/en-us/windows/win32/debug/pe-format) on Windows.
 All three formats express references to external symbols as _relocations_ which reside in a single section of each object file.
 
-The tool would scan every object file in the static library and construct a complete list of symbols defined and referenced across the entire library.
+We propose adding the `llvm-objdump` to the toolchain to provide the capability to inspect relocations across all three supported object file formats. The tool would use `llvm-objdump` every object file in the static library and construct a complete list of symbols defined and referenced across the entire library.
+Additionally, the tool would construct a simple C compiler invocation to derive to generate a default linker invocation.
+This would be used to derive the libraries linked by default in a C program, these libraries would then be scanned to contribute to the list of defined symbols.
 The tool would then check that the referenced symbols list is a subset of the set of defined symbols and emit an error otherwise.
 
+This would be sufficient to guarantee that all symbols from the static library would be available at runtime for statically linked executables or for ones running on the build host. 
+To ensure maximum runtime compatibility we would also provide a Linux-based Docker image that uses the oldest supported `glibc` for a given Swift version.
+As `glibc` is backwards compatible, a container running the audit on a given static library would ensure that the version of `glibc` on any runtime platform would be compatible with the binary artifact.
+This strategy as been succesfully employed in the Python community with [`manylinux`](https://peps.python.org/pep-0513/).
+
 ## Security
 
 This proposal brings the security implications outlined in [SE-0272](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0272-swiftpm-binary-dependencies.md#security) to non-Apple platforms, 
@@ -139,19 +146,16 @@ No current package should be affected by this change since this is only an addit
 
 ## Future directions
 
-### Extend binary compatibility guarantees
+### Support Swift static libraries
 
-This proposal makes no guarantees regarding the availability of symbols in the runtime environment and therefore the auditing tool validates that all referenced symbols in the binary dependency are already resolved.
-In the future we would like to provide more exhaustive guarantees about core system libraries and symbols that are guaranteed to be present on supported runtime environments, e.g. `libc.so`.
-This is very similar to the [`manylinux`](https://peps.python.org/pep-0513/) effort in the Python community, but the standardization effort would need to extend to Apple platforms and Windows platforms.
-Specifically we would extend the auditing tool to allow unresolved external symbols to symbols that are known to exist.
+To do this we would extend the static library binary artifact manifest to provide a `.swiftinterface` file that can be consumed by the Swift compiler to import the Swift APIs.
+Additionally we would extend the auditing tool to validate the usage of Swift standard library and runtime symbols, e.g., from `libSwiftCore`.
 
-### Support Swift static libraries (needs fact checking)
+### Extend binary compatibility guarantees
 
-Today Swift static libraries can not be fully statically linked.
-However, once binary compatibility guarantees are extended to include Swift SDK symbols,
-static libraries exposing a purely Swift API should be supported.
-To do this we would extend the static library binary artifact manifest to provide a `.swiftinterface` file that can be consumed by the Swift compiler.
+This proposal limits itself to providing facilities for binary compatibility only with the C standard library and runtime.
+In the future we could provide a system to allow binary artifact distributors to specify additional linkage dependencies for their binary artifacts.
+These would be used to customize the operation of the audit tool and perform automatic linking of them in any client target that depends on the binary artifact, in the same way [CMake](https://cmake.org/cmake/help/v4.0/prop_tgt/INTERFACE_LINK_LIBRARIES.html) propagates link dependencies transitively.
 
 ### Add support for dynamically linked dependencies