# CPAPluginSDK — XCFramework distribution

This folder contains the CocoaPacketAnalyzer Plugin SDK and every transitive
dynamic framework a `.cpaplugin` needs at compile time.

## What's in here

```
CPAPluginSDK-X.Y.Z/
├── CPAPluginSDK.xcframework            ← the umbrella you import
├── CPADependencies.xcframework         ┐
├── CPAModels.xcframework               │
├── CPACommonTools.xcframework          │  transitive frameworks
├── CPALog.xcframework                  │  the linker needs to see
├── CPAProtocolsStringsCache.xcframework│
├── CPAKonstantsKeys.xcframework        │
├── cpa_objc_exception.xcframework      │
└── pcap.xcframework                    ┘  (libpcap, used by CPAModels)
```

Your plugin source only ever does `import CPAPluginSDK`. The other frameworks
exist for the linker — they are NOT needed at the source level because
`CPAPluginSDK` re-exports them.

## Wiring them into your plugin Xcode project

1. Drag every `.xcframework` from this folder into your project's Xcode
   navigator. Choose **Copy items if needed** and add them to your plugin
   target.
2. Open the plugin target → **General** → **Frameworks and Libraries**.
   Mark every CPA framework as **Do Not Embed**. The host CocoaPacketAnalyzer
   app provides the runtime dylibs in its `Contents/SharedFrameworks/`
   directory.
3. Open **Build Settings** → search for "Runpath Search Paths"
   (`LD_RUNPATH_SEARCH_PATHS`). Add:
   ```
   @executable_path/../Frameworks
   @loader_path/../Frameworks
   @executable_path/../SharedFrameworks
   @loader_path/../SharedFrameworks
   ```
4. Confirm:
   - **Wrapper extension** = `cpaplugin`
   - **Mach-O type** = `Bundle`
   - **macOS deployment target** ≥ the host app's deployment target

That's it. `import CPAPluginSDK` and write your analyzer.

## Verifying the install

After your first build, check that the plugin links the frameworks but does
not embed them:

```bash
otool -L MyAnalyzer.cpaplugin/Contents/MacOS/MyAnalyzer | grep CPAPluginSDK
# Expect: @rpath/CPAPluginSDK.framework/Versions/A/CPAPluginSDK ...

ls MyAnalyzer.cpaplugin/Contents/Frameworks/ 2>/dev/null
# Expect: empty or absent (host provides the dylibs)
```

If the second command lists any `CPA*.framework`, you accidentally embedded
them — go back to step 2 and set them to "Do Not Embed."

## Installing the plugin for testing

```bash
mkdir -p ~/Library/Application\ Support/CocoaPacketAnalyzer/PlugIns/
cp -R build/Debug/MyAnalyzer.cpaplugin \
    ~/Library/Application\ Support/CocoaPacketAnalyzer/PlugIns/
```

Restart CocoaPacketAnalyzer; your plugin appears in **Settings ▸ Analyzers**.
Declare an `AnalyzerSettingsConfig` (conform to `CPAPluginSettingsHosting`) and
the host renders its settings pane for you — see the Analyzer Settings article.
