derek.holloway
7502bf64a4
CodeQL / Analyze (actions) (push) Canceled after 0s
CodeQL / Analyze (python) (push) Canceled after 0s
pre-commit / pre-commit (push) Canceled after 0s
Multi-Arch CI / setup (push) Canceled after 0s
Publish build_manylinux_x86_64 images / publish_build_manylinux_x86_64 (push) Canceled after 0s
Setup (Multi-Arch) / setup (push) Canceled after 0s
Multi-Arch CI / Linux::${{ fromJSON(needs.setup.outputs.linux_build_config || '{}').build_variant_label || 'skip' }} (push) Canceled after 0s
Publish TheRock Docker image / build-and-push-image (push) Canceled after 0s
Publish no_rocm_image_ubi10 image / publish_no_rocm_image_ubi10 (push) Canceled after 0s
Multi-Arch CI / Windows::${{ fromJSON(needs.setup.outputs.windows_build_config || '{}').build_variant_label || 'skip' }} (push) Canceled after 0s
Publish TheRock Docker image / build-and-push-image (push) Canceled after 0s
Multi-Arch CI / Manifest Diff (push) Canceled after 0s
TheRock Manifest Diff Report / Generate Manifest Diff Report (push) Canceled after 0s
Multi-Arch CI / CI Summary (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04 images / publish_no_rocm_image_ubuntu24_04 (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04_ocl_rt images / publish_no_rocm_image_ubuntu24_04_ocl_rt (push) Canceled after 0s
Publish TheRock Docker image / build-and-push-image (push) Canceled after 0s
Publish TheRock Docker image / build-and-push-image (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04 images / publish_no_rocm_image_ubuntu24_04_rocgdb (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04_rocgdb images / publish_no_rocm_image_ubuntu24_04_rocgdb (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04 images / publish_no_rocm_image_ubuntu24_04_ocl_rt (push) Canceled after 0s
Publish TheRock Docker image / build-and-push-image (push) Canceled after 0s
Unit Tests / Unit Tests :: ubuntu-24.04 (push) Canceled after 0s
Unit Tests / Unit Tests :: windows-2022 (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04 images / publish_no_rocm_image_ubuntu24_04_media (push) Canceled after 0s
Unit Tests / Unit Tests Summary (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04 images / publish_no_rocm_image_ubuntu24_04_openmpi (push) Canceled after 0s
100 lines
3.1 KiB
ReStructuredText
100 lines
3.1 KiB
ReStructuredText
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
|