building ([current](https://www.swift.org/documentation/server/guides/building.html))

[heckj]

• Current content

🧭 North Star: show examples of how to build executables (& libraries)

• (core path: developing on Mac, running on Linux)

• how to cross-compile from macOS → Linux

  • using the linux-static-sdk
  • how to compile in Linux while on macOS (using container)
  • (reference separate article - Packaging - for building a container)

• differentiate between building for local dev & production

• build options that are common/useful for building

  • -c release —product ...
  • --static-swift-stdlib for linux (or not?)
  • other options that do something specific?
    • -Xcc -fno-omit-frame-pointer ?? better backtraces?
    • --explicit-target-dependency-import-check ?
    • --scratch-path to change from .build

• 🗺️ (Outline)

  • configuration (-c) debug & release
    • swift build - just checkin' - debug output, runable
    • swift build -c release - optimized, runnable
    • ? other CLI options while building? - other optimizations/controls that are common or useful?
      • -Xcc -fno-omit-frame-pointer for potentially improved better backtraces?
      • makes it easier to unwind stack traces with perf or gdb
      • • generally only with -c debug
      • -fomit-frame-pointer shouldn't be on by default, really, so that shouldn't be necessary, but if it is turned on for some reason then yes, adding -fno-omit-frame-pointer to turn it off again would be a good idea.
    • -Xswiftc -cross-module-optimization
      • increases code size, longer build times, but potentially better performance optimizations
      • ref: https://forums.swift.org/t/stance-on-cross-module-optimization/73288
      • • generally only with a -c release
    • --product for a focused build (aka -c release --product ...) to avoid building extra stuff
  • choosing traits (Swift 6.3+)
    • some packages started to expose controls activated by traits
    • --traits
    • swift package show-traits
  • locating binaries (bin path)
    • swift build --show-bin-path
    • swift build -c release --show-bin-path
  • building to run on other platforms
    • using a container to check Linux build
      • how to build using Swift toolchain in Linux using a container - container CLI (aka docker CLI)
        • container run --rm -it -c 4 -m 8g -v "$(pwd):/src" -w /src swift:6.2
    • (reference "how to build a container" to another article)
    • compiling with the Static Linux SDK
      • --swift-sdk ...
        • x86_64-swift-linux-musl
        • aarch64-swift-linux-musl
    • When on linux
      • compile dynamic
      • --static-swift-stdlib - do we ever want to suggest this anymore?
        • impact on backtraces - without it, backtraces aren't great?
        • 6.0 -> 6.2: with - gives readable backtraces and long link times.
        • Omitting it gives garbage backtraces and quick links
      • The --static-swift-stdlib option causes us to statically link just the Swift standard library, so you don't need to ship libswiftCore.so with your program, but your program will still dynamically link the usual libswiftCore dependencies.
      • Example use was to deliver a binary asset that can be run on a platform that might not have the Swift runtime installed. The main time was when I was producing JARs that were wrapping a Swift dynamic lib, but that dylib had statically linked the Swift stdlib.