Help wanted: macOS testers for incoming PR #14 (macOS build support)

[ChenlizheMe]

We have a promising PR (#14) that adds full macOS build support to Infernux, including CMake presets, MoltenVK integration, Python runtime installation, and Hub packaging.

I don’t have a macOS machine myself, so I’m looking for someone in the community who can help test this PR on real macOS hardware (Apple Silicon or Intel).

What needs testing:

• Clone the PR branch: git clone --recursive -b feature/macos-build-support https://github.com/WendellZ524/Infernux.git
• Build using the provided release-macos CMake preset
• Run the editor: python packaging/launcher.py
• Verify basic workflows: create a cube, add a box collider + rigidbody, run the scene
• Check that the Hub can install the managed Python runtime on macOS

On a side note: Im a solo dev right now. Long-term contributors for any area (macOS, Windows, Linux, docs, testing, features, etc.) are more than welcome. Let me know if you're interested — I'd really appreciate the help!

[ChenlizheMe]

PR author has kindly provided a screen recording showing the macOS build working as expected, so I’m no longer looking for macOS testers on this specific PR. That said, I’d still love to hear from developers on other platforms, especially Linux. If anyone is interested in helping with Linux builds or any other areas (Windows, docs, testing, features, etc.), please feel free to reach out:)

[yihuang]

LLM helps me to setup the MacOS environment (using nixpkgs as package manager), shared the process here:

Build Guide — macOS (Apple Silicon)

This document describes how to build Infernux on macOS using the release-macos CMake preset.
It covers every dependency and configuration quirk encountered during setup.

---

Prerequisites

Tool	Required	Notes
CMake ≥3.20	Yes	Tested with 3.29.6
Ninja	Yes	Build system for macOS preset
Apple Clang	Yes	Ships with Xcode / CLT
Python 3.12+	Yes	Project requires ≥3.12
pybind11	Yes	Python <-> C++ binding
Vulkan SDK	Yes	Via MoltenVK (translation layer)
SPIRV-Cross	Yes	Shader reflection
zlib	Yes	Required by Assimp

---

Step 1: Install System Tools

Xcode Command Line Tools

xcode-select --install

Verify the SDK path:

xcrun --show-sdk-path
# /Library/Developer/CommandLineTools/SDKs/MacOSX*.sdk

CMake

# via Homebrew
brew install cmake

# via Nix
nix profile install nixpkgs#cmake

Ninja

Ninja is required by the release-macos preset:

# via Homebrew
brew install ninja

# via Nix
nix profile install nixpkgs#ninja

---

Step 2: Install Dependencies via Nix

The project relies on several system-level libraries. Using Nix is the cleanest way
to install them without polluting the system:

# Vulkan SDK (via MoltenVK for macOS)
nix profile install nixpkgs#vulkan-loader
nix profile install nixpkgs#vulkan-headers
nix profile install nixpkgs#vulkan-tools

# SPIRV-Cross (shader reflection)
nix profile install nixpkgs#spirv-cross

# zlib (required by Assimp)
nix profile install nixpkgs#zlib
nix profile add nixpkgs#zlib.dev    # for zlib.h headers

---

Step 3: Setup Python Environment

The project requires Python ≥ 3.12.

uv venv
uv pip install -r requirements.txt
.venv/bin/python -mensurepip
source .venv/bin/activate

Once activated, CMake's find_package(Python3) auto-detects the correct Python.

---

Step 4: Configure with CMake

The release-macos preset uses Ninja and sets CMAKE_BUILD_TYPE=Release.

CMake auto-discovers Nix packages via CMAKE_PREFIX_PATH. Just point it to
~/.nix-profile/ and CMake's find_package / find_library will locate Vulkan,
ZLIB, and SPIRV-Cross automatically — no per-dependency -D overrides needed.

Critical: Clear the build directory before each configure attempt to avoid
stale cache issues:

rm -rf out/build/*
cmake --preset release-macos \
  -DCMAKE_PREFIX_PATH="${HOME}/.nix-profile"

What CMAKE_PREFIX_PATH resolves

CMake command	Finds automatically
find_package(Vulkan)	~/.nix-profile/include/vulkan/vulkan.h + ~/.nix-profile/lib/libvulkan.dylib
find_package(ZLIB)	~/.nix-profile/include/zlib.h + ~/.nix-profile/lib/libz.dylib
find_library(spirv-cross-core)	~/.nix-profile/lib/libspirv-cross-core.a
find_library(spirv-cross-glsl)	~/.nix-profile/lib/libspirv-cross-glsl.a
find_library(spirv-cross-cpp)	~/.nix-profile/lib/libspirv-cross-cpp.a
find_library(spirv-cross-reflect)	~/.nix-profile/lib/libspirv-cross-reflect.a

---

Step 5: Build

cmake --build --preset release-macos

This command:

1. Compiles all C++ source files (engine core + pybind11 bindings)
2. Builds external dependencies (SDL3, Assimp, JoltPhysics, glslang, imgui)
3. Links _Infernux.cpython-313-darwin.so
4. Copies shared library dependencies into python/Infernux/lib/
5. Builds a Python wheel via python3 -m build --wheel
6. Installs the wheel into the venv via pip install --no-deps

Outputs

Artifact	Location
C++ native module	python/Infernux/lib/_Infernux.cpython-313-darwin.so
Python wheel	dist/infernux-0.1.6-cp313-cp313-macosx_*_arm64.whl
Bundled dylibs	python/Infernux/lib/*.dylib

---

Step 6: Verify

.venv/bin/python3 -c "import Infernux; print('✅ Infernux imported successfully')"

Expected output:

Infernux imported successfully

---

Troubleshooting

Problem: symbol not found in flat namespace '__ZTVN11spirv_cross8CompilerE'

Cause: The _Infernux.so links against SPIRV-Cross, but the static libraries
(libspirv-cross-*.a) were not found during linking.

Fix: Pass both -DCMAKE_LIBRARY_PATH (for find_library) and
-DCMAKE_SHARED_LINKER_FLAGS="-L<path>" (for the linker) pointing to the
SPIRV-Cross lib/ directory. With ~/.nix-profile/:

-DCMAKE_LIBRARY_PATH="${HOME}/.nix-profile/lib" \
-DCMAKE_SHARED_LINKER_FLAGS="-L${HOME}/.nix-profile/lib"

Problem: Could NOT find Python3 (missing: Development.Module Development.Embed)

Cause: The Python interpreter doesn't have development headers/libraries
available (no Python.h or libpython3*.dylib).

Fix: Use a Python installation that includes dev headers. On Nix, python313
includes headers. With uv/venv, explicitly pass Python3_INCLUDE_DIR and
Python3_LIBRARY as shown above.

Problem: Failed to install wheel: Package requires a different Python

Cause: CMake discovered Python 3.9 (macOS system Python), but the wheel
metadata says requires-python = ">=3.12".

Fix: Set -DPython3_EXECUTABLE to a Python 3.12+ interpreter, and ensure
it also has development headers + pybind11 installed.

---

Full One-Shot Build Script

#!/usr/bin/env bash
set -euo pipefail

cd "$(dirname "$0")"

echo "=== Setting up Python environment ==="
uv venv
uv pip install -r requirements.txt
.venv/bin/python -mensurepip
source .venv/bin/activate

echo "=== Configuring with CMake ==="
rm -rf out/build/*
cmake --preset release-macos \
  -DCMAKE_PREFIX_PATH="${HOME}/.nix-profile"

echo "=== Building ==="
cmake --build --preset release-macos

echo "=== Verifying ==="
python3 -c "import Infernux; print('✅ Build successful!')"