diff --git a/Package.swift b/Package.swift index 1f2bdfc..68c58b5 100644 --- a/Package.swift +++ b/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"]), diff --git a/Package@swift-5.1.swift b/Package@swift-5.1.swift new file mode 100644 index 0000000..1f2bdfc --- /dev/null +++ b/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"]), + ] +) diff --git a/Package@swift-5.2.swift b/Package@swift-5.2.swift new file mode 100644 index 0000000..1f2bdfc --- /dev/null +++ b/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"]), + ] +) diff --git a/Package@swift-5.3.swift b/Package@swift-5.3.swift new file mode 100644 index 0000000..1f2bdfc --- /dev/null +++ b/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"]), + ] +) diff --git a/Package@swift-5.4.swift b/Package@swift-5.4.swift new file mode 100644 index 0000000..1f2bdfc --- /dev/null +++ b/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"]), + ] +) diff --git a/Package@swift-5.5.swift b/Package@swift-5.5.swift new file mode 100644 index 0000000..1f2bdfc --- /dev/null +++ b/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"]), + ] +) diff --git a/Sources/Backtrace/Backtrace.swift b/Sources/Backtrace/Backtrace.swift index 1baaf08..792eb3d 100644 --- a/Sources/Backtrace/Backtrace.swift +++ b/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.") diff --git a/Sources/Backtrace/Docs.docc/index.md b/Sources/Backtrace/Docs.docc/index.md new file mode 100644 index 0000000..6310fdc --- /dev/null +++ b/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`. diff --git a/docker/docker-compose.2004.56.yaml b/docker/docker-compose.2004.56.yaml index 10e7bd6..a18dcbe 100644 --- a/docker/docker-compose.2004.56.yaml +++ b/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 diff --git a/docker/docker-compose.2004.57.yaml b/docker/docker-compose.2004.57.yaml index cdaee57..f422b50 100644 --- a/docker/docker-compose.2004.57.yaml +++ b/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 diff --git a/docker/docker-compose.2004.main.yaml b/docker/docker-compose.2004.main.yaml index f6e24f9..53e766d 100644 --- a/docker/docker-compose.2004.main.yaml +++ b/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 diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml index 1299f6f..69eb3de 100644 --- a/docker/docker-compose.yaml +++ b/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 diff --git a/scripts/preview_docc.sh b/scripts/preview_docc.sh new file mode 100755 index 0000000..12dc3b8 --- /dev/null +++ b/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 diff --git a/scripts/sanity.sh b/scripts/soundness.sh similarity index 94% rename from scripts/sanity.sh rename to scripts/soundness.sh index baf6c46..12a7746 100755 --- a/scripts/sanity.sh +++ b/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" //===----------------------------------------------------------------------===//