Metadata-Version: 2.4
Name: kdk_storage
Version: 0.0.1
Summary: A library for working with a directory with KDK's
Project-URL: Homepage, https://github.com/nixerr/kdk_storage
Author-email: Valentin Shilnenkov <vshilnenkov@protonmail.com>
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# kdk_storage

A small Python library for working with a directory of Apple **Kernel Debug Kits** (KDKs).

It scans a folder full of installed KDKs, sorts them by version (handling beta ordering), and gives you a simple API to locate the kernel and driver (kext) binaries inside any given KDK.

## What is a KDK?

A [Kernel Debug Kit](https://developer.apple.com/download/all/?q=Kernel%20Debug%20Kit) is a package Apple ships for each macOS build that contains the (usually unstripped) kernel and kext binaries used for kernel debugging and research. When installed, each KDK lives in its own directory named like:

```
KDK_15.5_24F74.kdk
```

`kdk_storage` treats a parent folder holding many such directories as a single addressable *storage*.

## Installation

Requires Python >= 3.9. The project is built with [Hatchling](https://hatch.pypa.io/).

```bash
pip install .
```

or, for development:

```bash
pip install -e .
```

## Usage

```python
from pathlib import Path
from kdk_storage import KDKStorage

# Point at the directory that contains your KDK_* folders.
storage = KDKStorage(Path("/Library/Developer/KDKs"))

# List available versions (optionally skipping betas).
print(storage.get_versions_list(skip_betas=False))
# ['15.4_24E248', '15.5_24F74', ...]

# Human-readable listing that marks betas.
for line in storage.get_versions_list_to_print(skip_betas=False):
    print(line)
# 15.5_24F74
# 15.6_24G5054d (beta)

# Resolve a kernel binary for a version.
kernel = storage.kernel("15.5_24F74", "kernel")
print(kernel.binary)        # full path to the kernel Mach-O
print(kernel.is_macho_fat())  # True if it's a fat/universal binary
```

### Partial version matching

`KDKStorage.kernel()` accepts a partial version string. If the argument isn't an exact match but is a substring of exactly one available version, that version is used:

```python
storage.kernel("24F74", "kernel")   # matches 15.5_24F74
```

If the substring is ambiguous (matches more than one version) or matches none, `kernel()` returns `None`.

### Working with drivers

Given a specific `KDK`, you can also resolve a driver (kext) binary:

```python
kdk = storage.hashmap_versions["15.5_24F74"]
driver = kdk.driver("AppleACPIPlatform")
print(driver.binary)  # path to the kext's Mach-O under Contents/MacOS
```

## API overview

| Class | Purpose |
| --- | --- |
| `KDKStorage` | Scans a directory of KDKs, sorts them by version, and resolves kernels/drivers. |
| `KDK` | A single Kernel Debug Kit directory; knows its version and whether it's a beta. |
| `KDKElement` | Base class for a binary inside a KDK. Provides `is_macho_fat()`. |
| `Kernel` | A kernel binary under `System/Library/Kernels`. |
| `Driver` | A kext binary under `System/Library/Extensions/<name>.kext/Contents/MacOS`. |

### Version ordering

KDKs are sorted by their numeric version components, with two tie-breaking rules:

- A **beta** build (detected when the last character of the version string is a lowercase letter, e.g. `24G5054d`) sorts *before* the corresponding release build.
- Otherwise the build identifier (the part after `_`) is compared lexicographically.

## License

MIT © Valentin Shilnenkov
