### Install Mise and Project Tools

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Installs Mise, a tool version manager, and then installs the development tools specified in the project's .mise.toml file. This ensures consistent development environments.

```bash
# Install Mise (if not already installed)
curl https://mise.run | sh

# Install tools defined in .mise.toml
mise install

# Trust the configuration (required once for security)
mise trust
```

--------------------------------

### Initialize and Start Memory Tracker

Source: https://github.com/kstenerud/kscrash/blob/master/README.md

Instantiate AppMemoryTracker, set its delegate, and start monitoring memory usage. Ensure your class conforms to AppMemoryTrackerDelegate.

```swift
let memoryTracker = AppMemoryTracker()
memoryTracker.delegate = self
memoryTracker.start()
```

--------------------------------

### Configure KSCrash Standard Installation in AppDelegate

Source: https://github.com/kstenerud/kscrash/blob/master/README.md

Set up the standard crash installation, including the URL for reports and optional monitors. This code should be placed in your AppDelegate's `didFinishLaunchingWithOptions` method.

```swift
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        let installation = CrashInstallationStandard.shared
        installation.url = URL(string: "http://put.your.url.here")!

        // Install the crash reporting system
        let config = KSCrashConfiguration()
        config.monitors = [.machException, .signal]
        installation.install(with: config) // set `nil` for default config

        // Optional: Add an alert confirmation (recommended for email installation)
        installation.addConditionalAlert(
            withTitle: "Crash Detected",
            message: "The app crashed last time it was launched. Send a crash report?",
            yesAnswer: "Sure!",
            noAnswer: "No thanks"
        )

        return true
    }
}
```

--------------------------------

### Install KSCrash with Error Handling

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

The installation process now returns an error, requiring a do-catch block for proper error handling instead of a boolean success value.

```swift
do {
    try KSCrash.shared.install(with: config)
} catch {
    print("Failed to install KSCrash: \(error)")
}
```

--------------------------------

### Install and Trust Mise Tools

Source: https://github.com/kstenerud/kscrash/blob/master/Samples/CLAUDE.md

Installs and trusts the necessary tools defined in the project's Mise configuration. This is a prerequisite for other commands.

```bash
mise install
mise trust
```

--------------------------------

### Old KSCrash Installation Method

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

Shows the previous KSCrash installation method, which returned a boolean indicating success or failure.

```swift
let success = KSCrash.sharedInstance().install()
```

--------------------------------

### Configure Console Installation for KSCrash

Source: https://github.com/kstenerud/kscrash/blob/master/README.md

Set up KSCrash to print crash reports to the console. This is useful for testing and debugging.

```swift
let installation = CrashInstallationConsole.shared
installation.printAppleFormat = true // Print crash reports in Apple format for testing
```

--------------------------------

### Configure Email Installation for KSCrash

Source: https://github.com/kstenerud/kscrash/blob/master/README.md

Set up KSCrash to send crash reports via email. Specify recipient email addresses and optionally set the report style.

```swift
let installation = CrashInstallationEmail.shared
installation.recipients = ["some@email.address"] // Specify recipients for email reports
// Optional: Send Apple-style reports instead of JSON
installation.setReportStyle(.apple, useDefaultFilenameFormat: true)
```

--------------------------------

### Run Integration Tests with Tuist

Source: https://github.com/kstenerud/kscrash/blob/master/Samples/CLAUDE.md

Executes integration tests for the Sample app using Tuist, managed by Mise. Ensure tools are installed and trusted.

```bash
mise exec -- tuist test --platform ios
```

--------------------------------

### Generate Project with Tuist via Mise

Source: https://github.com/kstenerud/kscrash/blob/master/Samples/CLAUDE.md

Generates the Xcode project using Tuist, managed by Mise. Ensure tools are installed and trusted first.

```bash
mise exec -- tuist generate
```

--------------------------------

### Directory Layout for KSCrash Sidecars

Source: https://github.com/kstenerud/kscrash/wiki/In-Progress-for-Next-Release

Illustrates the file system structure for per-report and per-run sidecars within the KSCrash installation path. This layout is crucial for understanding how monitors store and access auxiliary data.

```plaintext
<installPath>/
├── Reports/
│   └── myapp-report-00789abc00000001.json
├── Sidecars/                                          (per-report)
│   ├── Watchdog/
│   │   └── 00789abc00000001.ksscr
│   └── AnotherMonitor/
│       └── 00789abc00000001.ksscr
└── RunSidecars/                                       (per-run)
    └── a1b2c3d4-e5f6-7890-abcd-ef1234567890/
        ├── Lifecycle.ksscr
        ├── System.ksscr
        └── Watchdog.ksscr

```

--------------------------------

### Check if Hang Started During Startup

Source: https://github.com/kstenerud/kscrash/wiki/In-Progress-for-Next-Release

This C code snippet checks if a detected hang began during the application's startup phases (Startup, StartupPrewarm, or Launching). It is used within the `finalizeResolvedHang()` function to determine if a hang report should be suppressed.

```c
bool startedDuringStartup = hang.transitionState <= KSCrashAppTransitionStateLaunching;
```

--------------------------------

### Build Sample App with xcodebuild

Source: https://github.com/kstenerud/kscrash/blob/master/Samples/CLAUDE.md

Builds the Sample app for iOS using the `xcodebuild` command. Can target a simulator or a specific device.

```bash
xcodebuild -scheme Sample -sdk iphonesimulator
```

```bash
xcodebuild -scheme Sample -destination 'platform=iOS Simulator,name=iPhone 15'
```

--------------------------------

### Old KSCrash Configuration Method

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

Illustrates the previous approach to configuring KSCrash by directly setting properties on the shared instance.

```swift
if let handler = KSCrash.sharedInstance() {
    handler.monitoring = KSCrashMonitorType(
        KSCrashMonitorTypeMachException.rawValue |
        KSCrashMonitorTypeSignal.rawValue |
        KSCrashMonitorTypeCPPException.rawValue
    )
    handler.deadlockWatchdogInterval = 5.0
    handler.introspectMemory = true
    handler.maxReportCount = 10
}
```

--------------------------------

### Build Swift Package (Release)

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Builds the Swift package in release mode, optimized for performance. Use this for production builds.

```bash
swift build -c release
```

--------------------------------

### Show Swift Package Structure

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Displays the structure and metadata of the Swift package, including its name, path, and tools version.

```bash
swift package describe
```

--------------------------------

### Add KSCrash Dependency via CocoaPods

Source: https://github.com/kstenerud/kscrash/blob/master/README.md

Add KSCrash to your project's Podfile for installation using CocoaPods. This specifies the version constraint for KSCrash.

```ruby
pod 'KSCrash', '~> 2.5'
```

--------------------------------

### Build Specific Swift Product

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Builds a specific product from the Swift package. Use '-c release' for release mode.

```bash
# Build specific product
swift build --product Recording
# Sample output: Building for debugging...
# Build of product 'Recording' complete!

# Build specific product in release mode
swift build -c release --product Filters
# Sample output: Building for release...
# Build of product 'Filters' complete!
```

--------------------------------

### Build Sample App with Tuist via Mise

Source: https://github.com/kstenerud/kscrash/blob/master/Samples/CLAUDE.md

Builds the Sample app for iOS using Tuist, managed by Mise. Specify the platform and configuration as needed.

```bash
mise exec -- tuist build Sample --platform ios
```

```bash
mise exec -- tuist build Sample --platform ios --configuration Debug
```

--------------------------------

### Run Integration Tests with xcodebuild

Source: https://github.com/kstenerud/kscrash/blob/master/Samples/CLAUDE.md

Executes integration tests for the Sample app using `xcodebuild`. Specify the test plan and destination.

```bash
xcodebuild test -scheme Sample -testPlan Integration -destination 'platform=iOS Simulator,name=iPhone 15'
```

--------------------------------

### Configure KSCrash with Configuration Objects

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

Replace direct property manipulation with dedicated configuration objects for setting up KSCrash. This includes monitors, deadlock watchdog, memory introspection, and report store settings.

```swift
let config = KSCrashConfiguration()
config.monitors = .productionSafe
config.deadlockWatchdogInterval = 5.0
config.enableMemoryIntrospection = true

let storeConfig = CrashReportStoreConfiguration()
storeConfig.maxReportCount = 10
config.reportStoreConfiguration = storeConfig
```

--------------------------------

### Run Swift Tests with Options

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Enables code coverage reporting, lists all tests, or runs tests concurrently for faster execution. The '--list-tests' option is deprecated.

```bash
# Run tests with code coverage
swift test --enable-code-coverage
# Enables code coverage reporting for test runs

# List all tests (note: replaced deprecated --list-tests option)
swift test list
# Sample output: Lists all test methods in the project 
# KSCrash_Tests/testUserInfo
# KSCrash_Tests/testUserInfoIfNil
# etc.

# Run tests in parallel
swift test --parallel
# Sample output: Runs tests concurrently for faster execution
```

--------------------------------

### Build Swift Package (Debug)

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Builds the Swift package in debug mode. This is the default build configuration.

```bash
swift build
```

--------------------------------

### Show Swift Package Dependencies

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Lists the external dependencies of the Swift package. This command is useful for understanding project's external libraries.

```bash
swift package show-dependencies
```

--------------------------------

### Check Swift Code Formatting

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Use this command to verify that Swift code adheres to the project's formatting standards. This is useful for CI checks.

```bash
make check-format
```

--------------------------------

### Format Swift Code

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Use this command to format Swift code according to project standards. Ensure code is formatted before committing.

```bash
make format
```

--------------------------------

### Initialize App State Tracker

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

Instantiate and register an observer for the KSCrashAppStateTracker. Ensure the observer conforms to the AppStateTrackerDelegate protocol.

```swift
let stateTracker = AppStateTracker.shared
stateTracker.addObserver(self)
```

--------------------------------

### Include BootTimeMonitor and DiscSpaceMonitor with CocoaPods

Source: https://github.com/kstenerud/kscrash/blob/master/README.md

Add these optional monitors to your project using CocoaPods if you need to track boot time or disk space. These modules require user consent for privacy.

```ruby
pod 'KSCrash/BootTimeMonitor'
pod 'KSCrash/DiscSpaceMonitor'
```

--------------------------------

### Run Swift Tests

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Executes all tests defined in the Swift package. Ensure tests pass before making changes.

```bash
swift test
```

--------------------------------

### Manually Configure Filters with KSCrash 2.0

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

For advanced users, KSCrash 2.0 requires manual configuration of the filter pipeline when working directly with `KSCrash`. This involves importing the necessary modules and creating a `CrashReportFilterPipeline`.

```swift
import KSCrashDemangleFilter
import KSCrashFilters

// Configure the filter pipeline
let pipeline = CrashReportFilterPipeline(filters: [
    CrashReportFilterDemangle(),  // Handles symbol demangling
    CrashReportFilterDoctor(),    // Adds automated diagnostics
])

// Apply the configured pipeline to the report store
reportStore.sink = pipeline
```

--------------------------------

### Execute Tools with Mise

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Runs project tools, such as Tuist, using Mise to ensure the correct, project-pinned versions are used. This prevents version conflicts.

```bash
# Run tools via mise (ensures correct version)
mise exec -- tuist generate

# Or activate mise in your shell for direct tool access
eval "$(mise activate zsh)"  # or bash/fish
tuist generate  # Now uses the pinned version
```

--------------------------------

### Include BootTimeMonitor and DiscSpaceMonitor with SPM

Source: https://github.com/kstenerud/kscrash/blob/master/README.md

Add these optional monitors to your target dependencies when using KSCrash with Swift Package Manager. These modules require user consent for privacy.

```swift
.product(name: "BootTimeMonitor", package: "KSCrash"),
.product(name: "DiscSpaceMonitor", package: "KSCrash"),
```

--------------------------------

### Run Swift Tests with Verbose Output

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Runs Swift tests and displays verbose output, which can be helpful for debugging test failures.

```bash
swift test --verbose
```

--------------------------------

### Manage Swift Package Dependencies

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Updates all dependencies to their latest allowable versions or resolves and downloads all dependencies to ensure they are at the correct versions.

```bash
# Update package dependencies
swift package update
# Updates all dependencies to their latest allowable versions

# Resolve package dependencies
swift package resolve
# Makes sure all dependencies are downloaded and at correct versions
```

--------------------------------

### Format C/C++/Objective-C Code

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Checks C/C++/Objective-C files against clang-format rules and applies automatic formatting according to project style. Shows warnings for files that don't meet standards.

```bash
# Check formatting issues
make check-format
# Sample output checks C/C++/Objective-C files against clang-format rules
# Shows warnings for files that don't meet formatting standards

# Apply automatic formatting
make format
# Automatically reformats all C/C++/Objective-C files according to project style
```

--------------------------------

### Old KSCrash Singleton Access

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

Demonstrates the older method of accessing the KSCrash singleton instance using `sharedInstance()` or an initializer.

```swift
let ksCrash = KSCrash.sharedInstance()
// or
let ksCrash = KSCrash(basePath: "path")
```

--------------------------------

### Activate Mise in Shell and Use Tuist

Source: https://github.com/kstenerud/kscrash/blob/master/Samples/CLAUDE.md

Activates Mise in your shell environment, allowing direct use of tools like Tuist without `mise exec`. Add the activation command to your shell profile.

```bash
eval "$(mise activate zsh)"  # or bash/fish

tuist generate
tuist build Sample --platform ios
```

--------------------------------

### Old Report Management Methods

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

Demonstrates the older methods for managing crash reports, including retrieving IDs, fetching reports, and deleting them directly from the shared instance.

```swift
guard let reportIDs = KSCrash.sharedInstance().reportIDs() as? [NSNumber] else { /* handle */ }
let report = KSCrash.sharedInstance().report(withID: reportIDs[0])
KSCrash.sharedInstance().deleteReport(withID: reportIDs[0])
```

--------------------------------

### Enable Demangling and Diagnostics with CrashInstallation

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

In KSCrash 2.0, using `CrashInstallation` automatically enables demangling and diagnostic filtering by default. These can be explicitly enabled or disabled.

```swift
// Both filters are enabled by default
installation.isDemangleEnabled = true  // Enable symbol demangling
installation.isDoctorEnabled = true    // Enable automated diagnostics
```

--------------------------------

### Old SPM Imports for KSCrash

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

This shows the previous way of importing KSCrash modules using SPM before the target names were simplified.

```swift
import KSCrash_Recording
import KSCrash_Recording_Tools
```

--------------------------------

### Run Specific Test with xcodebuild

Source: https://github.com/kstenerud/kscrash/blob/master/Samples/CLAUDE.md

Runs a specific integration test case using `xcodebuild`. Useful for isolating and debugging individual tests.

```bash
xcodebuild test -scheme Sample -testPlan Integration -destination 'platform=iOS Simulator,name=iPhone 15' -only-testing SampleTests/NSExceptionTests/testGenericException
```

--------------------------------

### Format Swift Code

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Checks and formats Swift files using .swift-format configuration. Requires Swift 6.0+ (included with Xcode 16+). Use '--in-place' to modify files directly.

```bash
# Check Swift formatting issues
make check-swift-format
# Checks all Swift files in Sources/, Tests/, and Samples/ directories against .swift-format configuration
# Requires Swift 6.0+ (included with Xcode 16+)

# Apply Swift formatting
make swift-format
# Automatically reformats all Swift files in Sources/, Tests/, and Samples/ according to .swift-format configuration
# Requires Swift 6.0+ (included with Xcode 16+)

# Format specific Swift file
swift format format --in-place --configuration .swift-format <file>
```

--------------------------------

### Import KSCrash for SPM

Source: https://github.com/kstenerud/kscrash/blob/master/README.md

Import the KSCrashInstallations module when using KSCrash with Swift Package Manager.

```swift
import KSCrashInstallations
```

--------------------------------

### Configure KSCrash Report Cleanup Policy

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

Set the `reportCleanupPolicy` on the `KSCrashReportStore` to define how reports are handled after transmission. Options include never deleting, deleting on success, or always deleting.

```swift
reportStore.reportCleanupPolicy = .onSuccess
```

--------------------------------

### Handle App State Transitions

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

Implement the appStateTracker delegate method to respond to application state changes. This method is called when the app transitions between states.

```swift
func appStateTracker(_ tracker: AppStateTracker, didTransitionTo state: AppTransitionState) {
    // Handle state
}
```

--------------------------------

### Access KSCrash Singleton Instance

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

KSCrash now exclusively uses a singleton pattern for access. The old sharedInstance() method and initializer with basePath are deprecated.

```swift
let ksCrash = KSCrash.shared
```

--------------------------------

### Access KSCrash Report Store

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

The report management functionality has been moved to a dedicated `KSCrashReportStore` class, accessible via `KSCrash.shared.reportStore`.

```swift
let reportStore = KSCrash.shared.reportStore
```

--------------------------------

### Run Specific Swift Test Case

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Executes a particular test case within a Swift test target. Ideal for focused debugging.

```bash
swift test --filter KSCrash_Tests/testUserInfo
```

--------------------------------

### Import KSCrash for CocoaPods

Source: https://github.com/kstenerud/kscrash/blob/master/README.md

Import the KSCrash module when using KSCrash with CocoaPods.

```swift
import KSCrash
```

--------------------------------

### Report Custom Crashes and Stack Traces

Source: https://github.com/kstenerud/kscrash/blob/master/README.md

Use this method to report custom crashes or stack traces, such as those originating from scripting languages. It allows specifying the exception name, reason, line of code, stack trace, and whether to terminate the program.

```objective-c
- (void) reportUserException:(NSString*) name
                      reason:(NSString*) reason
                  lineOfCode:(NSString*) lineOfCode
                  stackTrace:(NSArray*) stackTrace
            terminateProgram:(BOOL) terminateProgram;
```

--------------------------------

### Handle Memory Level Changes

Source: https://github.com/kstenerud/kscrash/blob/master/README.md

Implement this delegate method to receive notifications about memory changes. Respond to memory level changes by taking appropriate actions to reduce memory usage.

```swift
func appMemoryTracker(_ tracker: AppMemoryTracker, memory: AppMemory, changed changes: AppMemoryTrackerChangeType) {
    if changes.contains(.level) {
        // Respond to memory level changes
    }
}
```

--------------------------------

### Enable SIGTERM Monitoring in KSCrash 2.0

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

KSCrash 2.0 allows for optional detection of SIGTERM signals. Enable this feature by setting `config.enableSigTermMonitoring` to true.

```swift
config.enableSigTermMonitoring = true
```

--------------------------------

### Enable Memory Termination Monitoring in KSCrash 2.0

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

KSCrash 2.0 introduces memory monitoring. Enable memory termination detection by setting `config.enableMemoryTermination` to true in your configuration.

```swift
// In your configuration
config.enableMemoryTermination = true
```

--------------------------------

### Run Specific Swift Test Target

Source: https://github.com/kstenerud/kscrash/blob/master/CLAUDE.md

Executes tests only for a specified target within the Swift package. Useful for isolating test runs.

```bash
swift test --filter KSCrashCore_Tests
```

--------------------------------

### C Macro Definitions for Namespacing

Source: https://github.com/kstenerud/kscrash/blob/master/namespacer/README.md

These C macros define the namespacing mechanism. KSCRASH_NAMESPACE should be defined externally to apply the namespace. Symbols are transformed using a series of macro expansions.

```c
#ifdef KSCRASH_NAMESPACE

#define KSCRASH_NS2(NAMESPACE, SYMBOL) SYMBOL##NAMESPACE
#define KSCRASH_NS1(NAMESPACE, SYMBOL) KSCRASH_NS2(NAMESPACE, SYMBOL)
#define KSCRASH_NS(SYMBOL) KSCRASH_NS1(KSCRASH_NAMESPACE, SYMBOL)

#define AppMemory KSCRASH_NS(AppMemory)
...
```

--------------------------------

### Manage Reports Using KSCrashReportStore

Source: https://github.com/kstenerud/kscrash/wiki/Migration-Guide-for-KSCrash-1.x-to-2.0

Update your report management code to use the `KSCrashReportStore` class for retrieving report IDs, accessing reports, and deleting them. Note the change in ID type to `int64Value`.

```swift
guard let reportStore = KSCrash.shared.reportStore else { /* handle */ }
let reportIDs = reportStore.reportIDs
let report = reportStore.report(for: reportIDs[0].int64Value)
reportStore.deleteReport(with: reportIDs[0].int64Value)
```