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

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 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, these values populate the global constants object:

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, 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:

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 use this pattern to conditionally enable legacy GPU support:

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 uses the detected OS version to configure global behaviors. For instance, it enables KDK (Kernel Debug Kit) caching only on modern releases:

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 perform early exits for incompatible versions:

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:

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:

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:

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 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}