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 14Building 15-------- 16 17To build Rusticl you need to satisfy the following build dependencies: 18 19- ``rustc`` 20- ``rustfmt`` (highly recommended, but only *required* for CI builds 21 or when authoring patches) 22- ``bindgen`` 23- `LLVM <https://github.com/llvm/llvm-project/>`__ built with 24 ``libclc`` and ``-DLLVM_ENABLE_DUMP=ON``. 25- `SPIRV-Tools <https://github.com/KhronosGroup/SPIRV-Tools>`__ 26- `SPIRV-LLVM-Translator 27 <https://github.com/KhronosGroup/SPIRV-LLVM-Translator>`__ for a 28 ``libLLVMSPIRVLib.so`` matching your version of LLVM, i.e. if you're 29 using LLVM 15 (``libLLVM.so.15``), then you need a 30 ``libLLVMSPIRVLib.so.15``. 31 32The minimum versions to build Rusticl are: 33 34- Rust: 1.76 35- Meson: 1.4.0 36- Bindgen: 0.65.0 37- LLVM: 15.0.0 38- Clang: 15.0.0 39 Updating clang requires a rebuilt of mesa and rusticl if and only if the value of 40 ``CLANG_RESOURCE_DIR`` changes. It is defined through ``clang/Config/config.h``. 41- SPIRV-Tools: any version (recommended: v2022.3) 42 43Afterwards you only need to add ``-Dgallium-rusticl=true -Dllvm=enabled 44-Drust_std=2021`` to your build options. 45 46Most of the code related to Mesa's C code lives inside ``/mesa``, with 47the occasional use of enums, structs or constants through the code base. 48 49If you need help ping ``karolherbst`` either in ``#dri-devel`` or 50``#rusticl`` on OFTC. 51 52Contributing 53------------ 54 55The minimum configuration you need to start developing with rust 56is ``RUSTC=clippy-driver meson configure -Dgallium-rusticl=true 57-Dllvm=enabled -Drust_std=2021``. In addition you probably want to enable 58any device drivers on your platform. Some device drivers as well as some 59features are locked behind flags during runtime. See 60:ref:`Rusticl environment variables <rusticl-env-var>` for 61more info. 62 63All patches that are potentially conformance breaking and also patches 64that add new features should be ran against the appropriate conformance 65tests. 66 67Also, make sure the formatting is in order before submitting code. That 68can easily be done via ``git ls-files */{lib,main}.rs | xargs rustfmt``. 69 70When submitting Merge Requests or filing bugs related to Rusticl, make 71sure to add the ``Rusticl`` label so people subscribed to that Label get 72pinged. 73 74Known issues 75------------ 76 77One issue you might come across is, that the Rust edition meson sets is 78not right. This is a known `meson bug 79<https://github.com/mesonbuild/meson/issues/10664>`__ and in order to 80fix it, simply run ``meson configure $your_build_dir -Drust_std=2021`` 81