# iKSCrash — B4i Wrapper for KSCrash 2.x

A B4i library wrapper around [KSCrash 2.x](https://github.com/kstenerud/KSCrash),
the ultimate iOS crash reporter.

---

## Files included

| File | Destination | Purpose |
|------|-------------|---------|
| `iKSCrash.h` | Mac server `Libs/` | Wrapper header (also source for B4iH2XML) |
| `iKSCrash.m` | Xcode project | Wrapper implementation |
| `iKSCrash.xml` | IDE `Libraries/` | B4i autocomplete / compiler descriptor |
| `iKSCrash.a` | Mac server `Libs/` | Compiled static library (you build this) |

---

## Build steps (Mac + Xcode required)

### 1 — Create a new Xcode Static Library target

1. **File → New → Project → iOS → Static Library**  
   Name it `iKSCrash`.

2. Add KSCrash via **Swift Package Manager**:  
   *File → Add Packages…*  
   URL: `https://github.com/kstenerud/KSCrash.git`  
   Version: `2.5.1` (or *Up to Next Major*)  
   Products to add: **KSCrashRecording**, **KSCrashInstallations**,
   **KSCrashFilters**, **KSCrashSinks**

3. Add `iKSCrash.h` and `iKSCrash.m` to the target.

4. Under **Build Settings**:
   - **Architectures**: `arm64` only (the B4i Mac server requires arm64)
   - **Build Active Architecture Only**: `No`
   - **Mach-O Type**: `Static Library`

5. Build for a real device (not Simulator). The output `iKSCrash.a` will be in
   the Derived Data products folder.

### 2 — Extract the KSCrash static libraries

KSCrash SPM products also compile to `.a` files you need alongside your wrapper.
After building, find them in Derived Data under  
`Build/Products/Debug-iphoneos/`:
- `libKSCrashRecording.a`
- `libKSCrashInstallations.a`
- `libKSCrashFilters.a`
- `libKSCrashSinks.a`

### 3 — Copy to Mac server

Copy all five `.a` files **and** `iKSCrash.h` to:
```
~/Documents/B4i-MacServer/Libs/
```

### 4 — Copy XML to IDE

Copy `iKSCrash.xml` to the B4i IDE `Libraries` folder on your Windows/Mac
development machine.

---

## Basic B4i Usage

```vb
' Declare the object (module level)
Dim Crash As KSCrashInstallation

Sub Application_Start (Nav As NavigationController)
    ' 1. Install the crash reporter — call ONCE, as early as possible
    Crash.Install

    ' 2. Point it at your crash-collection server
    Crash.SetReportUrl("https://yourserver.com/api/crashes")

    ' 3. Tag this session with useful metadata
    Crash.SetUserInfoKey("version", "1.0.0")
    Crash.SetUserInfoKey("userId", "12345")

    ' 4. Check if we crashed last time
    If Crash.DidCrashLastLaunch Then
        Log("App crashed on the previous launch!")
        Log("Pending reports: " & Crash.PendingReportCount)
        ' Optionally prompt the user before sending
        Crash.SendAllReports("Crash")
    End If
End Sub

' This event fires after SendAllReports completes
Sub Crash_ReportsSent(Success As Boolean, ReportCount As Int)
    If Success Then
        Log("Sent " & ReportCount & " crash report(s) successfully.")
    Else
        Log("Failed to send crash reports.")
    End If
End Sub
```

---

## Advanced Usage

### Custom monitor set
```vb
' Enable only signal + ObjC exception monitors
Crash.InstallWithMonitors("signal,objcException")
```

### Zombie / use-after-free detection
```vb
Crash.SetZombieTrackingEnabled(True)
```

### Memory introspection (richer reports)
```vb
Crash.SetIntrospectMemory(True)
```

### Report a scripting-language exception
```vb
Dim trace As String = "myScript.lua:42 in function 'doSomething'" & Chr(10) & _
                      "myScript.lua:10 in main chunk"
Crash.ReportCustomException("LuaError", "attempt to index nil value", _
    "Lua", "myScript.lua:42", trace, False)
```

### Print reports to console (debug only)
```vb
Crash.PrintAllReportsToConsole
```

### Delete all pending reports
```vb
Crash.DeleteAllReports
```

---

## Notes

- **KSCrash 2.x** uses a Swift Package with Objective-C/C/Swift mixed sources.
  The wrapper is pure Objective-C so it integrates cleanly with the B4i
  static-library build system.
- KSCrash must be installed **before any other initialisation** so it can catch
  early-launch crashes. `Application_Start` is the right place.
- The `SendAllReports` event parameter (`"Crash"` in the example) must match
  the prefix of your event sub (`Crash_ReportsSent`).
- Zombie tracking adds a small overhead to every object deallocation.
  Enable it for debug/beta builds; consider disabling for release.
- The `mainThreadDeadlock` monitor is **unstable** per KSCrash docs — use only
  for targeted debugging sessions.