Update README.md for archiving

Do not build Demangle on Swift 5.9 or above

.spi.yml

@@ -0,0 +1,4 @@
+version: 1
+builder:
+  configs:
+    - documentation_targets: [Backtrace]

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.0
+// swift-tools-version:5.6
 
 import PackageDescription
 
@@ -10,14 +10,16 @@ let package = Package(
             targets: ["Backtrace"]
         ),
     ],
-    dependencies: [],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
+    ],
     targets: [
         .target(name: "Backtrace",
                 dependencies: ["CBacktrace"]),
         .target(name: "CBacktrace",
                 dependencies: []),
-        .target(name: "Sample",
-                dependencies: ["Backtrace"]),
+        .executableTarget(name: "Sample",
+                          dependencies: ["Backtrace"]),
         .testTarget(name: "BacktraceTests",
                     dependencies: ["Backtrace"]),
     ]

Package@swift-5.0.swift

@@ -0,0 +1,24 @@
+// swift-tools-version:5.0
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-backtrace",
+    products: [
+        .library(
+            name: "Backtrace",
+            targets: ["Backtrace"]
+        ),
+    ],
+    dependencies: [],
+    targets: [
+        .target(name: "Backtrace",
+                dependencies: ["CBacktrace"]),
+        .target(name: "CBacktrace",
+                dependencies: []),
+        .target(name: "Sample",
+                dependencies: ["Backtrace"]),
+        .testTarget(name: "BacktraceTests",
+                    dependencies: ["Backtrace"]),
+    ]
+)

Package@swift-5.1.swift

@@ -0,0 +1,24 @@
+// swift-tools-version:5.0
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-backtrace",
+    products: [
+        .library(
+            name: "Backtrace",
+            targets: ["Backtrace"]
+        ),
+    ],
+    dependencies: [],
+    targets: [
+        .target(name: "Backtrace",
+                dependencies: ["CBacktrace"]),
+        .target(name: "CBacktrace",
+                dependencies: []),
+        .target(name: "Sample",
+                dependencies: ["Backtrace"]),
+        .testTarget(name: "BacktraceTests",
+                    dependencies: ["Backtrace"]),
+    ]
+)

Package@swift-5.2.swift

@@ -0,0 +1,24 @@
+// swift-tools-version:5.0
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-backtrace",
+    products: [
+        .library(
+            name: "Backtrace",
+            targets: ["Backtrace"]
+        ),
+    ],
+    dependencies: [],
+    targets: [
+        .target(name: "Backtrace",
+                dependencies: ["CBacktrace"]),
+        .target(name: "CBacktrace",
+                dependencies: []),
+        .target(name: "Sample",
+                dependencies: ["Backtrace"]),
+        .testTarget(name: "BacktraceTests",
+                    dependencies: ["Backtrace"]),
+    ]
+)

Package@swift-5.3.swift

@@ -0,0 +1,24 @@
+// swift-tools-version:5.0
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-backtrace",
+    products: [
+        .library(
+            name: "Backtrace",
+            targets: ["Backtrace"]
+        ),
+    ],
+    dependencies: [],
+    targets: [
+        .target(name: "Backtrace",
+                dependencies: ["CBacktrace"]),
+        .target(name: "CBacktrace",
+                dependencies: []),
+        .target(name: "Sample",
+                dependencies: ["Backtrace"]),
+        .testTarget(name: "BacktraceTests",
+                    dependencies: ["Backtrace"]),
+    ]
+)

Package@swift-5.4.swift

@@ -0,0 +1,24 @@
+// swift-tools-version:5.0
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-backtrace",
+    products: [
+        .library(
+            name: "Backtrace",
+            targets: ["Backtrace"]
+        ),
+    ],
+    dependencies: [],
+    targets: [
+        .target(name: "Backtrace",
+                dependencies: ["CBacktrace"]),
+        .target(name: "CBacktrace",
+                dependencies: []),
+        .target(name: "Sample",
+                dependencies: ["Backtrace"]),
+        .testTarget(name: "BacktraceTests",
+                    dependencies: ["Backtrace"]),
+    ]
+)

Package@swift-5.5.swift

@@ -0,0 +1,24 @@
+// swift-tools-version:5.0
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-backtrace",
+    products: [
+        .library(
+            name: "Backtrace",
+            targets: ["Backtrace"]
+        ),
+    ],
+    dependencies: [],
+    targets: [
+        .target(name: "Backtrace",
+                dependencies: ["CBacktrace"]),
+        .target(name: "CBacktrace",
+                dependencies: []),
+        .target(name: "Sample",
+                dependencies: ["Backtrace"]),
+        .testTarget(name: "BacktraceTests",
+                    dependencies: ["Backtrace"]),
+    ]
+)

README.md

@@ -1,3 +1,6 @@
+> [!IMPORTANT]  
+> This library is now archived as backtracing is built into Swift 5.9+
+
 # Backtrace
 
 This Swift package provides support for automatically printing crash backtraces of Swift programs.
@@ -7,8 +10,8 @@ When this gap is closed at the language runtime level, this library will become
 
 ## Usage
 
-When building web-services and daemons, direct usage of this library is discouraged. 
-Instead, use [swift-service-lifecycle](https://github.com/swift-server/swift-service-lifecycle) which helps manage the application lifecycle including setting up backtraces hooks when needed. 
+**Note**: You do not need this library on Linux as of Swift 5.9, which has
+built-in backtracing support.
 
 Add `https://github.com/swift-server/swift-backtrace.git` as a dependency in your `Package.swift`.
 

Sources/Backtrace/Backtrace.swift

@@ -2,7 +2,7 @@
 //
 // This source file is part of the SwiftLinuxBacktrace open source project
 //
-// Copyright (c) 2019-2020 Apple Inc. and the SwiftLinuxBacktrace project authors
+// Copyright (c) 2019-2022 Apple Inc. and the SwiftLinuxBacktrace project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -12,7 +12,21 @@
 //
 //===----------------------------------------------------------------------===//
 
-#if os(Linux)
+// Swift 5.9 has its own built-in backtracing support in the runtime;
+// we don't want to activate this library if we're using 5.9 or above.
+#if swift(>=5.9) && !os(Windows)
+public enum Backtrace {
+    @available(*, deprecated, message: "This is no longer needed in Swift 5.9")
+    public static func install() {}
+
+    @available(*, deprecated, message: "This is no longer needed in Swift 5.9")
+    public static func install(signals: [CInt]) {}
+
+    @available(*, deprecated, message: "This method will be removed in the next major version.")
+    public static func print() {}
+}
+
+#elseif os(Linux)
 import CBacktrace
 import Glibc
 
@@ -124,11 +138,13 @@ public enum Backtrace {
         #endif
     }
 
+    /// Signal selection unavailable on Windows. Use ``install()-484jy``.
     @available(*, deprecated, message: "signal selection unavailable on Windows")
     public static func install(signals: [CInt]) {
         Backtrace.install()
     }
 
+    /// Install the backtrace handler on default signals.
     public static func install() {
         // Install a last-chance vectored exception handler to capture the error
         // before the termination and report the stack trace.  It is unlikely
@@ -264,8 +280,10 @@ public enum Backtrace {
 
 #else
 public enum Backtrace {
+    /// Install the backtrace handler on default signals. Available on Windows and Linux only.
     public static func install() {}
 
+    /// Install the backtrace handler on specific signals. Available on Linux only.
     public static func install(signals: [CInt]) {}
 
     @available(*, deprecated, message: "This method will be removed in the next major version.")

Sources/Backtrace/Demangle.swift

@@ -12,6 +12,10 @@
 //
 //===----------------------------------------------------------------------===//
 
+// Swift 5.9 has its own built-in backtracing support in the runtime;
+// we don't want to activate this library if we're using 5.9 or above.
+#if !(swift(>=5.9) && !os(Windows))
+
 #if os(Linux)
 import Glibc
 #elseif os(Windows)
@@ -55,3 +59,5 @@ internal func _stdlib_demangleName(_ mangledName: String) -> String {
     }
 }
 #endif
+
+#endif

Sources/Backtrace/Docs.docc/index.md

@@ -0,0 +1,34 @@
+# ``Backtrace``
+
+Provides support for automatically printing crash backtraces of Swift programs.
+
+## Overview
+
+The Backtrace library is designed to fill a gap in backtraces support for Swift on non-Darwin platforms.
+When this gap is closed at the language runtime level, this library will become redundant and be deprecated.
+
+## Getting started
+
+When building web-services and daemons, direct usage of this library is discouraged.
+Instead, use [swift-service-lifecycle](https://github.com/swift-server/swift-service-lifecycle) which helps manage the application lifecycle including setting up backtraces hooks when needed.
+
+Add `https://github.com/swift-server/swift-backtrace.git` as a dependency in your `Package.swift`.
+
+### Crash backtraces
+
+In your `main.swift`, do:
+
+```swift
+import Backtrace
+
+// Do this first
+Backtrace.install()
+```
+
+Finally, for Swift < 5.2, make sure you build your application with debug symbols enabled. Debug symbols are automatically included for Swift 5.2 and above.
+
+```
+$ swift build -c release -Xswiftc -g
+```
+
+When your app crashes, a stacktrace will be printed to `stderr`.

Sources/Sample/main.swift

@@ -15,11 +15,15 @@
 import Backtrace
 #if canImport(Darwin)
 import Darwin
-#elseif os(Linux)
+#elseif canImport(Glibc)
 import Glibc
+#elseif canImport(Musl)
+import Musl
 #endif
 
+#if swift(<5.9) || os(Windows)
 Backtrace.install()
+#endif
 
 func raiseSignal(_ signal: Int32) {
     raise(signal)

Tests/BacktraceTests/BacktraceTests.swift

@@ -20,6 +20,10 @@ public final class BacktraceTests: XCTestCase {
         try XCTSkipIf(true, "test is only supported on Linux")
         #endif
 
+        #if swift(>=5.9)
+        try XCTSkipIf(true, "test is not supported on Swift 5.9")
+        #endif
+
         let expectedError = UUID().uuidString
         let stderr = try runSample(reason: expectedError)
         print(stderr)
@@ -34,6 +38,10 @@ public final class BacktraceTests: XCTestCase {
         try XCTSkipIf(true, "test is only supported on Linux")
         #endif
 
+        #if swift(>=5.9)
+        try XCTSkipIf(true, "test is not supported on Swift 5.9")
+        #endif
+
         let stderr = try runSample(reason: "SIGILL")
         print(stderr)
 
@@ -46,6 +54,10 @@ public final class BacktraceTests: XCTestCase {
         try XCTSkipIf(true, "test is only supported on Linux")
         #endif
 
+        #if swift(>=5.9)
+        try XCTSkipIf(true, "test is not supported on Swift 5.9")
+        #endif
+
         let stderr = try runSample(reason: "SIGSEGV")
         print(stderr)
 
@@ -58,6 +70,10 @@ public final class BacktraceTests: XCTestCase {
         try XCTSkipIf(true, "test is only supported on Linux")
         #endif
 
+        #if swift(>=5.9)
+        try XCTSkipIf(true, "test is not supported on Swift 5.9")
+        #endif
+
         let stderr = try runSample(reason: "SIGBUS")
         print(stderr)
 
@@ -70,6 +86,10 @@ public final class BacktraceTests: XCTestCase {
         try XCTSkipIf(true, "test is only supported on Linux")
         #endif
 
+        #if swift(>=5.9)
+        try XCTSkipIf(true, "test is not supported on Swift 5.9")
+        #endif
+
         let stderr = try runSample(reason: "SIGFPE")
         print(stderr)
 

docker/Dockerfile

@@ -19,8 +19,8 @@ RUN apt-get update && apt-get install -y lsof dnsutils netcat-openbsd net-tools
 # ruby and jazzy for docs generation
 RUN apt-get update && apt-get install -y ruby ruby-dev libsqlite3-dev build-essential
 # jazzy no longer works on older version of ubuntu as ruby is too old.
-RUN if [ "${ubuntu_version}" = "focal" ] ; then echo "gem: --no-document" > ~/.gemrc ; fi
-RUN if [ "${ubuntu_version}" = "focal" ] ; then gem install jazzy ; fi
+RUN if [ "${ubuntu_version}" = "jammy" ] ; then echo "gem: --no-document" > ~/.gemrc ; fi
+RUN if [ "${ubuntu_version}" = "jammy" ] ; then gem install jazzy ; fi
 
 # tools
 RUN mkdir -p $HOME/.tools

docker/docker-compose.2004.56.yaml

@@ -11,6 +11,8 @@ services:
 
   test:
     image: swift-linux-backtrace:20.04-5.6
+    environment:
+      - FORCE_TEST_DISCOVERY=--enable-test-discovery
 
   shell:
     image: swift-linux-backtrace:20.04-5.6

docker/docker-compose.2004.57.yaml

@@ -6,10 +6,13 @@ services:
     image: swift-linux-backtrace:20.04-5.7
     build:
       args:
-        base_image: "swiftlang/swift:nightly-main-focal"
+        ubuntu_version: "focal"
+        swift_version: "5.7"
 
   test:
     image: swift-linux-backtrace:20.04-5.7
+    environment:
+      - FORCE_TEST_DISCOVERY=--enable-test-discovery
 
   shell:
     image: swift-linux-backtrace:20.04-5.7

docker/docker-compose.2004.main.yaml

@@ -1,15 +0,0 @@
-version: "3"
-
-services:
-
-  runtime-setup:
-    image: swift-linux-backtrace:20.04-main
-    build:
-      args:
-        base_image: "swiftlang/swift:nightly-main-focal"
-
-  test:
-    image: swift-linux-backtrace:20.04-main
-
-  shell:
-    image: swift-linux-backtrace:20.04-main

docker/docker-compose.2204.510.yaml

@@ -0,0 +1,17 @@
+version: "3"
+
+services:
+
+  runtime-setup:
+    image: swift-linux-backtrace:22.04-5.10
+    build:
+      args:
+        base_image: "swiftlang/swift:nightly-5.10-jammy"
+
+  test:
+    image: swift-linux-backtrace:22.04-5.10
+    environment:
+      - FORCE_TEST_DISCOVERY=--enable-test-discovery
+
+  shell:
+    image: swift-linux-backtrace:22.04-5.10

docker/docker-compose.2204.58.yaml

@@ -0,0 +1,18 @@
+version: "3"
+
+services:
+
+  runtime-setup:
+    image: swift-linux-backtrace:22.04-5.8
+    build:
+      args:
+        ubuntu_version: "jammy"
+        swift_version: "5.8"
+
+  test:
+    image: swift-linux-backtrace:22.04-5.8
+    environment:
+      - FORCE_TEST_DISCOVERY=--enable-test-discovery
+
+  shell:
+    image: swift-linux-backtrace:22.04-5.8

docker/docker-compose.2204.59.yaml

@@ -0,0 +1,18 @@
+version: "3"
+
+services:
+
+  runtime-setup:
+    image: swift-linux-backtrace:22.04-5.9
+    build:
+      args:
+        ubuntu_version: "jammy"
+        swift_version: "5.9"
+
+  test:
+    image: swift-linux-backtrace:22.04-5.9
+    environment:
+      - FORCE_TEST_DISCOVERY=--enable-test-discovery
+
+  shell:
+    image: swift-linux-backtrace:22.04-5.9

docker/docker-compose.2204.main.yaml

@@ -0,0 +1,17 @@
+version: "3"
+
+services:
+
+  runtime-setup:
+    image: swift-linux-backtrace:22.04-main
+    build:
+      args:
+        base_image: "swiftlang/swift:nightly-main-jammy"
+
+  test:
+    image: swift-linux-backtrace:22.04-main
+    environment:
+      - FORCE_TEST_DISCOVERY=--enable-test-discovery
+
+  shell:
+    image: swift-linux-backtrace:22.04-main

docker/docker-compose.yaml

@@ -22,13 +22,13 @@ services:
       - CAP_NET_RAW
       - CAP_NET_BIND_SERVICE
 
-  sanity:
+  soundness:
     <<: *common
-    command: /bin/bash -cl "./scripts/sanity.sh"
+    command: /bin/bash -cl "./scripts/soundness.sh"
 
   test:
     <<: *common
-    command: /bin/bash -cl "swift test -c release -Xswiftc -g -Xswiftc -warnings-as-errors $${SANITIZER_ARG-}"
+    command: /bin/bash -cl "swift test -c release -Xswiftc -g -Xswiftc -warnings-as-errors $${FORCE_TEST_DISCOVERY-} $${SANITIZER_ARG-}"
 
   # util
 

scripts/preview_docc.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+##===----------------------------------------------------------------------===##
+##
+## This source file is part of the SwiftLinuxBacktrace open source project
+##
+## Copyright (c) 2022 Apple Inc. and the SwiftLinuxBacktrace project authors
+## Licensed under Apache License v2.0
+##
+## See LICENSE.txt for license information
+## See CONTRIBUTORS.txt for the list of SwiftLinuxBacktrace project authors
+##
+## SPDX-License-Identifier: Apache-2.0
+##
+##===----------------------------------------------------------------------===##
+
+##===----------------------------------------------------------------------===##
+##
+## This source file is part of the Swift Distributed Actors open source project
+##
+## Copyright (c) 2018-2019 Apple Inc. and the Swift Distributed Actors project authors
+## Licensed under Apache License v2.0
+##
+## See LICENSE.txt for license information
+## See CONTRIBUTORS.md for the list of Swift Distributed Actors project authors
+##
+## SPDX-License-Identifier: Apache-2.0
+##
+##===----------------------------------------------------------------------===##
+
+swift package --disable-sandbox preview-documentation --target $1

scripts/soundness.sh

@@ -3,7 +3,7 @@
 ##
 ## This source file is part of the SwiftLinuxBacktrace open source project
 ##
-## Copyright (c) 2017-2018 Apple Inc. and the SwiftLinuxBacktrace project authors
+## Copyright (c) 2017-2022 Apple Inc. and the SwiftLinuxBacktrace project authors
 ## Licensed under Apache License v2.0
 ##
 ## See LICENSE.txt for license information
@@ -19,7 +19,7 @@ here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
 function replace_acceptable_years() {
     # this needs to replace all acceptable forms with 'YEARS'
-    sed -e 's/2017-2018/YEARS/' -e 's/2019-2020/YEARS/' -e 's/2019/YEARS/' -e 's/2020/YEARS/'
+    sed -e 's/20[12][78901]-20[12][89012]/YEARS/' -e 's/2019/YEARS/' -e 's/202[012]/YEARS/'
 }
 
 printf "=> Checking linux tests... "
@@ -57,7 +57,7 @@ for language in swift-or-c bash dtrace; do
   matching_files=( -name '*' )
   case "$language" in
       swift-or-c)
-        exceptions=( -name Package.swift -o -path './Sources/CBacktrace/*' )
+        exceptions=( -name Package.swift -o -name 'Package@*.swift' -o -path './Sources/CBacktrace/*' )
         matching_files=( -name '*.swift' -o -name '*.c' -o -name '*.h' )
         cat > "$tmp" <<"EOF"
 //===----------------------------------------------------------------------===//