1Rusticl 2======= 3 4Rusticl is an OpenCL implementation on top of Gallium drivers. 5 6Enabling 7-------- 8 9In order to use Rusticl on any platform the environment variable 10:envvar:`RUSTICL_ENABLE` has to be used. Rusticl does not advertise devices 11for any driver by default yet as doing so can impact system stability until 12remaining core issues are ironed out. 13 14Enabling drivers by default 15--------------------------- 16 17Distributions and everybody building rusticl themselves can opt-in or opt-out 18certain drivers from being enabled by default. The 19``gallium-rusticl-enable-drivers`` takes a list of drivers to enable by 20default. The environment variable :envvar:`RUSTICL_ENABLE` will overwrite this 21list at runtime. 22 23Not all drivers are supported to be enabled by default, because that should 24require opt-in by the driver maintainers. Check out the meson option 25documentation to see for which drivers this option is supported. 26 27The ``auto`` option might not enable all drivers supported by this flag, but 28for distribution it's recommended to use that one unless they get an ack from 29driver maintainers to expand the list. 30 31Building 32-------- 33 34To build Rusticl you need to satisfy the following build dependencies: 35 36- ``rustc`` 37- ``rustfmt`` (highly recommended, but only *required* for CI builds 38 or when authoring patches) 39- ``bindgen`` 40- `LLVM <https://github.com/llvm/llvm-project/>`__ built with 41 ``libclc`` and ``-DLLVM_ENABLE_DUMP=ON``. 42- `SPIRV-Tools <https://github.com/KhronosGroup/SPIRV-Tools>`__ 43- `SPIRV-LLVM-Translator 44 <https://github.com/KhronosGroup/SPIRV-LLVM-Translator>`__ for a 45 ``libLLVMSPIRVLib.so`` matching your version of LLVM, i.e. if you're 46 using LLVM 15 (``libLLVM.so.15``), then you need a 47 ``libLLVMSPIRVLib.so.15``. 48 49The minimum versions to build Rusticl are: 50 51- Rust: 1.78 52- Meson: 1.4.0 53- Bindgen: 0.65.0 54- LLVM: 15.0.0 55- Clang: 15.0.0 56 Updating clang requires a rebuilt of mesa and rusticl if and only if the value of 57 ``CLANG_RESOURCE_DIR`` changes. It is defined through ``clang/Config/config.h``. 58- SPIRV-Tools: any version (recommended: v2022.3) 59 60Afterwards you only need to add ``-Dgallium-rusticl=true -Dllvm=enabled 61-Drust_std=2021`` to your build options. 62 63Most of the code related to Mesa's C code lives inside ``/mesa``, with 64the occasional use of enums, structs or constants through the code base. 65 66If you need help ping ``karolherbst`` either in ``#dri-devel`` or 67``#rusticl`` on OFTC. 68 69Contributing 70------------ 71 72The minimum configuration you need to start developing with rust 73is ``RUSTC=clippy-driver meson configure -Dgallium-rusticl=true 74-Dllvm=enabled -Drust_std=2021``. In addition you probably want to enable 75any device drivers on your platform. Some device drivers as well as some 76features are locked behind flags during runtime. See 77:ref:`Rusticl environment variables <rusticl-env-var>` for 78more info. 79 80All patches that are potentially conformance breaking and also patches 81that add new features should be ran against the appropriate conformance 82tests. 83 84Also, make sure the formatting is in order before submitting code. That 85can easily be done via ``git ls-files */{lib,main}.rs | xargs rustfmt``. 86 87When submitting Merge Requests or filing bugs related to Rusticl, make 88sure to add the ``Rusticl`` label so people subscribed to that Label get 89pinged. 90 91Known issues 92------------ 93 94One issue you might come across is, that the Rust edition meson sets is 95not right. This is a known `meson bug 96<https://github.com/mesonbuild/meson/issues/10664>`__ and in order to 97fix it, simply run ``meson configure $your_build_dir -Drust_std=2021`` 98