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