| KosmicKrisp |
| ########### |
| |
| KosmicKrisp is a Vulkan conformant implementation for macOS on Apple Silicon |
| hardware. It is implemented on top of Metal 4, which requires macOS 26 and up. |
| |
| No iOS support is present as of now. However, iOS was taken into consideration |
| during development to support A14 Bionic GPUs and upwards. |
| |
| Building |
| ******** |
| |
| The following build instructions assume Homebrew as the package manager to |
| install dependencies. Homebrew homepage https://brew.sh/ |
| Homebrew install command line: |
| |
| .. code-block:: sh |
| |
| /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" |
| |
| Terminal restart is recommended after Homebrew installation. |
| |
| Requirements |
| ============ |
| |
| - Xcode and Xcode command line tools |
| - Homebrew packages |
| - meson (1.9.1+, can also be installed as a Python package) |
| - cmake |
| - pkg-config |
| - libclc |
| - llvm (20.1.8+, lower versions may work but have not been tested) |
| - spirv-llvm-translator |
| - spirv-tools (static library preferred which is not included in the package, Vulkan macOS SDK does) |
| |
| Users might already have llvm installed, run ``llvm-config --version`` and |
| check that the command works and prints at least ``20.1.8``. Otherwise install |
| llvm from homebrew and add it to the ``PATH`` (follow homebrew instructions). |
| |
| - Python |
| - Python packages |
| - mako |
| - packaging |
| - pyyaml |
| - meson (1.9.1+, if not installed through Homebrew) |
| |
| Since Homebrew manages the Python environment, it is encouraged to create a |
| Python virtual environment and install all packages in that environment. To |
| create a Python virtual environment (e.g. ``$HOME/venv_mesa``): |
| |
| .. code-block:: sh |
| |
| python3 -m venv $HOME/venv_mesa |
| |
| To enable a Python virtual environment: |
| |
| .. code-block:: sh |
| |
| source $HOME/venv_mesa/bin/activate |
| |
| Build instructions |
| ================== |
| |
| Out of tree build directory is recommended. |
| |
| Once all requirements have been installed, the following command line can be |
| used to create a debug build: |
| |
| .. code-block:: sh |
| |
| meson setup <path/to/mesa> --buildtype=debug -Dplatforms=macos -Dvulkan-drivers=kosmickrisp -Dgallium-drivers= -Dopengl=false -Dzstd=disabled --prefer-static |
| |
| Environment variables |
| ********************* |
| |
| KosmicKrisp specific environment variables: |
| |
| - ``MESA_KK_DEBUG``: ``msl`` to log all generated Metal Shading Language (MSL) shaders. ``force_robustness`` to force robustness on all shaders. |
| - ``MESA_KK_GPU_CAPTURE``: Starts Metal capture at device create and ends it at device destroy. Set to ``1`` to activate. |
| - ``MESA_KK_GPU_CAPTURE_DIRECTORY``: Metal capture will be saved to the specified directory. Defaults to Xcode if no path is provided. |
| - ``MESA_KK_DISABLE_WORKAROUNDS``: Provide ``all`` to disable all workarounds. Otherwise, provide a comma separated list to disable wanted workarounds e.g. ``1,3,4`` to disable workaround 1, 3 and 4. |
| |
| Metal workarounds |
| ***************** |
| |
| Different workarounds are applied throughout the project to avoid issues such |
| as: |
| |
| - Metal API and Vulkan API discrepancies |
| - Metal bugs |
| - MSL compiler bugs |
| - MSL compiler crashes |
| |
| These workarounds can be found in: |
| |
| .. toctree:: |
| :maxdepth: 1 |
| |
| kosmickrisp/workarounds |
