DocC setup

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.0
+// swift-tools-version:5.6
 
 import PackageDescription
 
@@ -10,13 +10,15 @@ 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",
+        .executableTarget(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"]),
+    ]
+)

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
@@ -124,11 +124,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 +266,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/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`.

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

@@ -10,6 +10,8 @@ services:
 
   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

@@ -10,6 +10,8 @@ services:
 
   test:
     image: swift-linux-backtrace:20.04-main
+    environment:
+      - FORCE_TEST_DISCOVERY=--enable-test-discovery
 
   shell:
     image: swift-linux-backtrace:20.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/sanity.sh → 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"
 //===----------------------------------------------------------------------===//