# How OCLP-Mod Determines macOS Version Compatibility and Selects Patches from os_data

> Learn how OCLP-Mod uses os_data as a compatibility matrix to detect your macOS kernel version and select safe hardware patches.

- Repository: [laobamac/oclp-mod](https://github.com/laobamac/oclp-mod)
- Tags: internals
- Published: 2026-03-05

---

**OCLP-Mod detects the host system's XNU kernel major version at runtime and uses the `os_data` enum as a centralized compatibility matrix to determine which hardware patches are safe to apply.**

The OCLP-Mod project (laobamac/oclp-mod) relies on precise version detection to deploy kernel extensions and root patches without compromising system stability. By mapping runtime kernel versions to the `os_data` dataset, the tool ensures that version-specific fixes—such as non-Metal GPU patches or WindowServer cache adjustments—are only activated on compatible macOS releases.

## Detecting the Host macOS Version via OSProbe

The detection logic originates in [`oclp_mod/detections/os_probe.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/detections/os_probe.py) within the `OSProbe` class. This utility interrogates the host system to extract raw kernel identifiers and marketing version strings.

### Extracting XNU Kernel Versions

The `OSProbe` class parses the kernel release string (e.g., `21.1.0`) obtained from `platform.uname()` to derive numeric version components:

- **`detect_kernel_major()`** returns the integer before the first dot (e.g., `21` for macOS Monterey).
- **`detect_kernel_minor()`** returns the integer after the first dot (e.g., `1`).

During application startup in [`oclp_mod/application_entry.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/application_entry.py), these values populate the global constants object:

```python
self.constants.detected_os = os_data.detect_kernel_major()
self.constants.detected_os_minor = os_data.detect_kernel_minor()

```

### Resolving Marketing Names and Build Numbers

Beyond kernel versions, `OSProbe` queries the system `sw_vers` command and `/System/Library/CoreServices/SystemVersion.plist` to capture human-readable identifiers:

- **`detect_os_version()`** returns the marketing version string (e.g., `"12.0"`).
- **`detect_os_build()`** returns the build identifier (e.g., `"21A5522h"`).

These are stored in `constants.detected_os_version` and `constants.detected_os_build` respectively. Helper methods such as `os_conversion.kernel_to_os()` and `os_conversion.convert_kernel_to_marketing_name()` translate raw XNU majors (e.g., `22`) into recognizable release names (e.g., `"Ventura"`).

## The os_data Enum as the Compatibility Matrix

Located in [`oclp_mod/datasets/os_data.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/datasets/os_data.py), the `os_data` class is an `IntEnum` that maps XNU kernel major versions to specific macOS releases. This design provides type-safe, readable comparisons throughout the patching engine:

```python
class os_data(enum.IntEnum):
    big_sur = 20
    monterey = 21
    ventura = 22
    sonoma = 23

```

By referencing these enum members instead of magic numbers, patch developers can write self-documenting logic such as `if detected_os >= os_data.ventura:` to gate features for macOS Ventura and newer.

## Selecting Appropriate Patches Based on os_data

Patch selection logic evaluates `constants.detected_os` against `os_data` values to determine which modifications are compatible with the running system.

### The should_apply() Pattern

Individual patch set classes implement a `should_apply()` method that returns `True` only when the host's XNU version meets the required threshold. For example, classes in [`oclp_mod/sys_patch/patchsets/shared_patches/non_metal_ioaccel.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/shared_patches/non_metal_ioaccel.py) use this pattern to conditionally enable legacy GPU support:

```python
class NonMetalIOAccelPatch:
    def should_apply(self):
        return self._xnu_major >= os_data.mojave.value

```

This declarative approach isolates version-compatibility checks from the actual patching implementation.

### Centralized Dispatch in sys_patch.py

The main patching engine in [`oclp_mod/sys_patch/sys_patch.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/sys_patch.py) uses the detected OS version to configure global behaviors. For instance, it enables KDK (Kernel Debug Kit) caching only on modern releases:

```python
if self.constants.detected_os >= os_data.os_data.ventura:
    self.requires_kdk_caching = True

```

Similarly, helper utilities like `SysPatchHelpers.disable_window_server_caching()` in [`oclp_mod/sys_patch/sys_patch_helpers.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/sys_patch_helpers.py) perform early exits for incompatible versions:

```python
if self.constants.detected_os < os_data.os_data.ventura:
    return

```

## Practical Implementation Examples

The following patterns demonstrate how OCLP-Mod integrates version detection with patch selection:

**Detecting the host OS at startup:**

```python
from oclp_mod.detections.os_probe import OSProbe

probe = OSProbe()
major = probe.detect_kernel_major()      # → 22 for Ventura

minor = probe.detect_kernel_minor()      # → 4

version = probe.detect_os_version()      # → "13.4"

build = probe.detect_os_build()          # → "22D68"

# Store in global constants

constants.detected_os = major
constants.detected_os_minor = minor
constants.detected_os_version = version
constants.detected_os_build = build

```

**Selecting patches based on OS version:**

```python
from oclp_mod.datasets import os_data

if constants.detected_os >= os_data.os_data.ventura:
    # Apply Ventura-specific patches (e.g., GPU compiler fixes)

    apply_ventura_patches()
else:
    # Apply legacy compatibility shims

    apply_legacy_patches()

```

**Implementing version-gated patch classes:**

```python
class Metal3802Patch:
    def __init__(self, xnu_major):
        self._xnu_major = xnu_major

    def should_apply(self):
        # Only required for Ventura (XNU 22) and newer

        return self._xnu_major >= os_data.ventura.value

```

## Summary

- **XNU Kernel Major as Source of Truth**: OCLP-Mod uses `OSProbe.detect_kernel_major()` to capture the host's kernel version, storing it in `constants.detected_os` for system-wide reference.
- **Enum-Based Compatibility**: The `os_data` enum in [`oclp_mod/datasets/os_data.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/datasets/os_data.py) maps kernel majors (20, 21, 22, 23) to macOS releases (Big Sur, Monterey, Ventura, Sonoma).
- **Declarative Patch Gating**: Patch classes implement `should_apply()` methods that compare the runtime kernel version against `os_data` thresholds.
- **Centralized Feature Control**: [`sys_patch.py`](https://github.com/laobamac/oclp-mod/blob/main/sys_patch.py) and helper modules use simple integer comparisons against `os_data` values to enable version-specific features like KDK caching or WindowServer modifications.

## Frequently Asked Questions

### How does OCLP-Mod detect the macOS version at runtime?

OCLP-Mod instantiates the `OSProbe` class from [`oclp_mod/detections/os_probe.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/detections/os_probe.py) at startup. This class reads `platform.uname()` to extract the kernel release string and parses it via `detect_kernel_major()` and `detect_kernel_minor()`, while `detect_os_version()` queries system plist files to obtain marketing version strings.

### What is the os_data enum and where is it defined?

The `os_data` enum is defined in [`oclp_mod/datasets/os_data.py`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/datasets/os_data.py) as an `IntEnum` that assigns integer values to macOS releases based on their XNU kernel major version (e.g., `ventura = 22`). This enum serves as the canonical reference for all version compatibility checks across the codebase.

### How do individual patch classes determine if they should run?

Patch classes implement a `should_apply()` method that compares the host's `_xnu_major` value against `os_data` enum members. If the runtime kernel version meets or exceeds the required threshold, the method returns `True`, signaling that the patch is compatible with the current macOS installation.

### Why does OCLP-Mod use XNU kernel versions instead of marketing names?

XNU kernel versions provide a stable, numeric identifier that remains consistent across beta builds and minor point releases. Marketing names (e.g., "Ventura") and version strings (e.g., "13.4") can vary or require string parsing, whereas the kernel major version (e.g., `22`) offers a reliable integer for boolean logic and range comparisons.