| 1 | Rusticl
|
|---|
| 2 | =======
|
|---|
| 3 |
|
|---|
| 4 | Enabling
|
|---|
| 5 | --------
|
|---|
| 6 |
|
|---|
| 7 | In order to use Rusticl on any platform the environment variable
|
|---|
| 8 | :envvar:`RUSTICL_ENABLE` has to be used. Rusticl does not advertise devices
|
|---|
| 9 | for any driver by default yet as doing so can impact system stability until
|
|---|
| 10 | remaining core issues are ironed out.
|
|---|
| 11 |
|
|---|
| 12 | Building
|
|---|
| 13 | --------
|
|---|
| 14 |
|
|---|
| 15 | To 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 |
|
|---|
| 30 | The minimum versions to build Rusticl are:
|
|---|
| 31 |
|
|---|
| 32 | - Rust: 1.66
|
|---|
| 33 | - Meson: 1.3.1
|
|---|
| 34 | - Bindgen: 0.62.0
|
|---|
| 35 | - LLVM: 11.0.0 (recommended: 15.0.0)
|
|---|
| 36 | - Clang: 11.0.0 (recommended: 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 |
|
|---|
| 41 | Afterwards you only need to add ``-Dgallium-rusticl=true -Dllvm=enabled
|
|---|
| 42 | -Drust_std=2021`` to your build options.
|
|---|
| 43 |
|
|---|
| 44 | Most of the code related to Mesa's C code lives inside ``/mesa``, with
|
|---|
| 45 | the occasional use of enums, structs or constants through the code base.
|
|---|
| 46 |
|
|---|
| 47 | If you need help ping ``karolherbst`` either in ``#dri-devel`` or
|
|---|
| 48 | ``#rusticl`` on OFTC.
|
|---|
| 49 |
|
|---|
| 50 | Rust Update Policy
|
|---|
| 51 | ------------------
|
|---|
| 52 |
|
|---|
| 53 | Given that for some distributions it's not feasible to keep up with the
|
|---|
| 54 | pace of Rust, we promise to only bump the minimum required Rust version
|
|---|
| 55 | following 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 |
|
|---|
| 70 | As bug fixes might run into rustc compiler bugs, a rust version bump _can_
|
|---|
| 71 | happen on a stable branch as well.
|
|---|
| 72 |
|
|---|
| 73 | Contributing
|
|---|
| 74 | ------------
|
|---|
| 75 |
|
|---|
| 76 | The minimum configuration you need to start developing with rust
|
|---|
| 77 | is ``RUSTC=clippy-driver meson configure -Dgallium-rusticl=true
|
|---|
| 78 | -Dllvm=enabled -Drust_std=2021``. In addition you probably want to enable
|
|---|
| 79 | any device drivers on your platform. Some device drivers as well as some
|
|---|
| 80 | features are locked behind flags during runtime. See
|
|---|
| 81 | :ref:`Rusticl environment variables <rusticl-env-var>` for
|
|---|
| 82 | more info.
|
|---|
| 83 |
|
|---|
| 84 | All patches that are potentially conformance breaking and also patches
|
|---|
| 85 | that add new features should be ran against the appropriate conformance
|
|---|
| 86 | tests.
|
|---|
| 87 |
|
|---|
| 88 | Also, make sure the formatting is in order before submitting code. That
|
|---|
| 89 | can easily be done via ``git ls-files */{lib,main}.rs | xargs rustfmt``.
|
|---|
| 90 |
|
|---|
| 91 | When submitting Merge Requests or filing bugs related to Rusticl, make
|
|---|
| 92 | sure to add the ``Rusticl`` label so people subscribed to that Label get
|
|---|
| 93 | pinged.
|
|---|
| 94 |
|
|---|
| 95 | Known issues
|
|---|
| 96 | ------------
|
|---|
| 97 |
|
|---|
| 98 | One issue you might come across is, that the Rust edition meson sets is
|
|---|
| 99 | not right. This is a known `meson bug
|
|---|
| 100 | <https://github.com/mesonbuild/meson/issues/10664>`__ and in order to
|
|---|
| 101 | fix it, simply run ``meson configure $your_build_dir -Drust_std=2021``
|
|---|
