Move demangle filter to an optional module (#540)

* Move demangle to an optional filter * Fix code * Fix package * Add to sample * Fix format * Fix test * Add privacy info * Add subspec * Add demangling to installations * Add tests * Fix Swift demangle returning non-nil on failure * Add scheme * Add protocol pragma mark * Update README * Fix format * Fix missing import * Fix README
kstenerud · Aug 26, 2024 · 9b9f2c2 · 9b9f2c2
1 parent 2edefa5
commit 9b9f2c2
Show file tree

Hide file tree

Showing 56 changed files with 530 additions and 57 deletions.
diff --git a/.clang-format-ignore b/.clang-format-ignore
@@ -1,5 +1,5 @@
 Sources/KSCrashRecordingCore/KSObjCApple.h
-Sources/KSCrashRecordingCore/llvm/*
-Sources/KSCrashRecordingCore/llvm/*/*
-Sources/KSCrashRecordingCore/swift/*
-Sources/KSCrashRecordingCore/swift/*/*
+Sources/KSCrashDemangleFilter/llvm/*
+Sources/KSCrashDemangleFilter/llvm/*/*
+Sources/KSCrashDemangleFilter/swift/*
+Sources/KSCrashDemangleFilter/swift/*/*
diff --git a/.swiftpm/xcode/xcshareddata/xcschemes/KSCrash-Package.xcscheme b/.swiftpm/xcode/xcshareddata/xcschemes/KSCrash-Package.xcscheme
@@ -91,6 +91,20 @@
                ReferencedContainer = "container:">
             </BuildableReference>
          </BuildActionEntry>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "DemangleFilter"
+               BuildableName = "DemangleFilter"
+               BlueprintName = "DemangleFilter"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
       </BuildActionEntries>
    </BuildAction>
    <TestAction
@@ -204,6 +218,16 @@
                ReferencedContainer = "container:">
             </BuildableReference>
          </TestableReference>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "KSCrashDemangleFilterTests"
+               BuildableName = "KSCrashDemangleFilterTests"
+               BlueprintName = "KSCrashDemangleFilterTests"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </TestableReference>
       </Testables>
    </TestAction>
    <LaunchAction

diff --git a/KSCrash.podspec b/KSCrash.podspec
@@ -50,6 +50,7 @@ Pod::Spec.new do |s|
     installations.dependency 'KSCrash/Filters'
     installations.dependency 'KSCrash/Sinks'
     installations.dependency 'KSCrash/Recording'
+    installations.dependency 'KSCrash/DemangleFilter'
 
     configure_subspec.call(installations)
   end
@@ -72,6 +73,12 @@ Pod::Spec.new do |s|
     configure_subspec.call(disc_space_monitor)
   end
 
+  s.subspec 'DemangleFilter' do |demangle_filter|
+    demangle_filter.dependency 'KSCrash/Recording'
+
+    configure_subspec.call(demangle_filter)
+  end
+
   s.subspec 'ReportingCore' do |reporting_core|
     reporting_core.dependency 'KSCrash/Core'
     reporting_core.ios.frameworks = 'SystemConfiguration'

diff --git a/Package.swift b/Package.swift
@@ -43,6 +43,10 @@ let package = Package(
       name: "BootTimeMonitor",
       targets: [Targets.bootTimeMonitor]
     ),
+    .library(
+      name: "DemangleFilter",
+      targets: [Targets.demangleFilter]
+    ),
   ],
   targets: [
     .target(
@@ -112,6 +116,7 @@ let package = Package(
         .target(name: Targets.filters),
         .target(name: Targets.sinks),
         .target(name: Targets.recording),
+        .target(name: Targets.demangleFilter),
       ],
       resources: [
         .copy("Resources/PrivacyInfo.xcprivacy")
@@ -134,14 +139,6 @@ let package = Package(
       ],
       resources: [
         .copy("Resources/PrivacyInfo.xcprivacy")
-      ],
-      cSettings: [
-        .headerSearchPath("swift"),
-        .headerSearchPath("swift/Basic"),
-        .headerSearchPath("llvm"),
-        .headerSearchPath("llvm/ADT"),
-        .headerSearchPath("llvm/Config"),
-        .headerSearchPath("llvm/Support"),
       ]
     ),
     .testTarget(
@@ -217,6 +214,31 @@ let package = Package(
         ]
     ),
 
+    .target(
+      name: Targets.demangleFilter,
+      dependencies: [
+        .target(name: Targets.recording),
+      ],
+      resources: [
+        .copy("Resources/PrivacyInfo.xcprivacy")
+      ],
+      cSettings: [
+        .headerSearchPath("swift"),
+        .headerSearchPath("swift/Basic"),
+        .headerSearchPath("llvm"),
+        .headerSearchPath("llvm/ADT"),
+        .headerSearchPath("llvm/Config"),
+        .headerSearchPath("llvm/Support"),
+      ]
+    ),
+    .testTarget(
+        name: Targets.demangleFilter.tests,
+        dependencies: [
+            .target(name: Targets.demangleFilter),
+            .target(name: Targets.recording),
+        ]
+    ),
+
     .target(
       name: Targets.testTools,
       dependencies: [
@@ -237,6 +259,7 @@ enum Targets {
   static let core = "KSCrashCore"
   static let discSpaceMonitor = "KSCrashDiscSpaceMonitor"
   static let bootTimeMonitor = "KSCrashBootTimeMonitor"
+  static let demangleFilter = "KSCrashDemangleFilter"
   static let testTools = "KSCrashTestTools"
 }
 

diff --git a/README.md b/README.md
@@ -177,9 +177,9 @@ installation.sendAllReports { reports, completed, error in
 }
 ```
 
-### Optional Modules
+### Optional Monitors
 
-KSCrash includes two optional modules: `BootTimeMonitor` and `DiscSpaceMonitor`. These modules are not included by default and must be explicitly added if needed. They contain privacy-concerning APIs that require showing crash reports to the user before sending this information off the device.
+KSCrash includes two optional monitor modules: `BootTimeMonitor` and `DiscSpaceMonitor`. These modules are not included by default and must be explicitly added if needed. They contain privacy-concerning APIs that require showing crash reports to the user before sending this information off the device.
 
 To include these modules:
 
@@ -199,6 +199,26 @@ If these modules are linked, they act automatically and require no additional se
 
 For more information, see Apple's documentation on [Disk space APIs](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api#4278397) and [System boot time APIs](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api#4278394).
 
+### Optional Demangling
+
+KSCrash has an optional module that provides demangling for both C++ and Swift symbols: `DemangleFilter`. This module contains a KSCrash filter (`CrashReportFilterDemangle`) that can be used for demangling symbols in crash reports during the `sendAllReports` call *(if this filter is added to the filters pipeline)*.
+
+This module is used automatically if you use the `Installations` API. If you want to avoid demangling, you can set `isDemangleEnabled` in the `CrashInstallation` instance to `false`.
+
+If you don't use the `Installations` API, you can include this module manually:
+
+- With CocoaPods:
+  ```ruby
+  pod 'KSCrash/DemangleFilter'
+  ```
+
+- With SPM, add to your target dependencies:
+  ```swift
+  .product(name: "DemangleFilter", package: "KSCrash"),
+  ```
+
+The `CrashReportFilterDemangle` class also has a static API that you can use yourself in case you need to demangle a C++ or Swift symbol.
+
 ## What's New?
 
 ### Out-of-Memory Crash Detection
@@ -292,6 +312,7 @@ KSCrash is structured into several modules, divided into public and private APIs
 
 - **DiscSpaceMonitor**: `KSCrashDiscSpaceMonitor` - Monitors available disk space.
 - **BootTimeMonitor**: `KSCrashBootTimeMonitor` - Tracks device boot time.
+- **DemangleFilter**: `KSCrashDemangleFilter` - Demangle symbols in crashes as part of reporing pipeline.
 
 ### Private API Modules
 

diff --git a/Samples/Common/Package.swift b/Samples/Common/Package.swift
@@ -38,6 +38,7 @@ let package = Package(
       dependencies: [
         .product(name: "Recording", package: "KSCrash"),
         .product(name: "Reporting", package: "KSCrash"),
+        .product(name: "DemangleFilter", package: "KSCrash"),
         .product(name: "Logging", package: "swift-log"),
       ]
     ),

diff --git a/Samples/Common/Sources/CrashTriggers/KSCrashTriggersList.mm b/Samples/Common/Sources/CrashTriggers/KSCrashTriggersList.mm
@@ -30,6 +30,15 @@
 #import <signal.h>
 #import <stdexcept>
 
+namespace sample_namespace
+{
+class Report
+{
+   public:
+    static void crash() { throw std::runtime_error("C++ exception"); }
+};
+}  // namespace sample_namespace
+
 @implementation KSCrashTriggersList
 
 + (void)trigger_nsException_genericNSException
@@ -46,7 +55,7 @@ + (void)trigger_nsException_nsArrayOutOfBounds
 
 + (void)trigger_cpp_runtimeException
 {
-    throw std::runtime_error("C++ exception");
+    sample_namespace::Report::crash();
 }
 
 + (void)trigger_mach_badAccess

diff --git a/Samples/Common/Sources/LibraryBridge/ReportingSample.swift b/Samples/Common/Sources/LibraryBridge/ReportingSample.swift
@@ -28,6 +28,7 @@ import Foundation
 import KSCrashRecording
 import KSCrashFilters
 import KSCrashSinks
+import KSCrashDemangleFilter
 import Logging
 
 public class ReportingSample {
@@ -58,6 +59,7 @@ public class ReportingSample {
 
     public static func sampleLogToConsole() {
         KSCrash.shared.sink = CrashReportFilterPipeline(filtersArray: [
+            CrashReportFilterDemangle(),
             SampleFilter(),
             SampleSink(),
         ])