1Rusticl 2======= 3 4Enabling 5-------- 6 7In order to use Rusticl on any platform the environment variable 8:envvar:`RUSTICL_ENABLE` has to be used. Rusticl does not advertise devices 9for any driver by default yet as doing so can impact system stability until 10remaining core issues are ironed out. 11 12Building 13-------- 14 15To build Rusticl you need to satisfy the following build dependencies: 16 17- ``rustc`` 18- ``rustfmt`` (highly recommended, but only *required* for CI builds 19 or when authoring patches) 20- ``bindgen`` 21- `LLVM <https://github.com/llvm/llvm-project/>`__ built with 22 ``libclc`` and ``-DLLVM_ENABLE_DUMP=ON``. 23- `SPIRV-Tools <https://github.com/KhronosGroup/SPIRV-Tools>`__ 24- `SPIRV-LLVM-Translator 25 <https://github.com/KhronosGroup/SPIRV-LLVM-Translator>`__ for a 26 ``libLLVMSPIRVLib.so`` matching your version of LLVM, i.e. if you're 27 using LLVM 15 (``libLLVM.so.15``), then you need a 28 ``libLLVMSPIRVLib.so.15``. 29 30The minimum versions to build Rusticl are: 31 32- Rust: 1.66 33- Meson: 1.3.1 34- Bindgen: 0.62.0 35- LLVM: 15.0.0 36- Clang: 15.0.0 37 Updating clang requires a rebuilt of mesa and rusticl if and only if the value of 38 ``CLANG_RESOURCE_DIR`` changes. It is defined through ``clang/Config/config.h``. 39- SPIRV-Tools: any version (recommended: v2022.3) 40 41Afterwards you only need to add ``-Dgallium-rusticl=true -Dllvm=enabled 42-Drust_std=2021`` to your build options. 43 44Most of the code related to Mesa's C code lives inside ``/mesa``, with 45the occasional use of enums, structs or constants through the code base. 46 47If you need help ping ``karolherbst`` either in ``#dri-devel`` or 48``#rusticl`` on OFTC. 49 50Rust Update Policy 51------------------ 52 53Given that for some distributions it's not feasible to keep up with the 54pace of Rust, we promise to only bump the minimum required Rust version 55following those rules: 56 57- Only up to the Rust requirement of other major Linux desktop 58 components, e.g.: 59 60 - `Firefox ESR <https://whattrainisitnow.com/release/?version=esr>`__: 61 `Minimum Supported Rust Version: 62 <https://firefox-source-docs.mozilla.org/writing-rust-code/update-policy.html#schedule>`__ 63 64 - latest `Linux Kernel Rust requirement 65 <https://docs.kernel.org/process/changes.html#current-minimal-requirements>`__ 66 67- Only require a newer Rust version than stated by other rules if and only 68 if it's required to get around a bug inside rustc. 69 70As bug fixes might run into rustc compiler bugs, a rust version bump _can_ 71happen on a stable branch as well. 72 73Contributing 74------------ 75 76The minimum configuration you need to start developing with rust 77is ``RUSTC=clippy-driver meson configure -Dgallium-rusticl=true 78-Dllvm=enabled -Drust_std=2021``. In addition you probably want to enable 79any device drivers on your platform. Some device drivers as well as some 80features are locked behind flags during runtime. See 81:ref:`Rusticl environment variables <rusticl-env-var>` for 82more info. 83 84All patches that are potentially conformance breaking and also patches 85that add new features should be ran against the appropriate conformance 86tests. 87 88Also, make sure the formatting is in order before submitting code. That 89can easily be done via ``git ls-files */{lib,main}.rs | xargs rustfmt``. 90 91When submitting Merge Requests or filing bugs related to Rusticl, make 92sure to add the ``Rusticl`` label so people subscribed to that Label get 93pinged. 94 95Known issues 96------------ 97 98One issue you might come across is, that the Rust edition meson sets is 99not right. This is a known `meson bug 100<https://github.com/mesonbuild/meson/issues/10664>`__ and in order to 101fix it, simply run ``meson configure $your_build_dir -Drust_std=2021`` 102