Venemo/mesa-howto.md

## mesa-howto.md

      
    Raw
  

              mesa-howto.md
            
          
    Building and using mesa for development and testing

This explains how to build mesa from source, and how to use the custom built mesa to run some apps and games, without needing to replace the mesa libraries that your operating system runs on.
Let's assume that you are using an x86_64 system.
Building mesa

Overview

Here is what we are going to do:

Install all build dependencies for mesa
Clone the mesa repo to ~/Projects/mesa
Build mesa
Install the mesa version you just built into ~/mesa (not the same as the above directory)
Create a script which can tell games / apps to use the libraries from ~/mesa instead of what is on your system out of the box.

Step 1. Install dependencies

Use your distro package manager to install mesa dependencies. If you're on a different distro, you will need to substitute with the correct commands for your package manager. The packages are usually named similarly but maybe have a different naming convention (eg. -dev vs. -devel, etc.).
This works on Fedora 41:
dnf builddep mesa

Step 2. Clone the mesa repo

I usually put every git repo I work with into a directory such as ~/Projects - I recommend the same to you.
mkdir -p ~/Projects
cd ~/Projects
git clone https://gitlab.freedesktop.org/mesa/mesa.git

Step 3. 64-bit build

We're assuming that your distro uses lib64 for the 64-bit libraries like Fedora. If not, adjust the meson commands below according to your distro.
The compiled libraries will go into ~/mesa for the sake of simplicity.
There are various ways to compile Mesa, based on what parts you want to include. This depends on your HW. Compilation is faster when you include fewer components.
To build Mesa, you need to:
# Enter the mesa root directory.
cd mesa

# Setup the build with meson to select which parts you need.
# Several potential setup commands are listed below.
meson setup <directory> --libdir lib64 --prefix $HOME/mesa <other options>

# Compile with ninja
ninja -C build64 install

Setup with both Intel and AMD drivers in release mode, including Zink and codecs:

meson setup build64 --libdir lib64 --prefix $HOME/mesa -Dgallium-drivers=radeonsi,swrast,iris,zink -Dvulkan-drivers=intel,amd -Dvideo-codecs=h264dec,h264enc,h265dec,h265enc,vc1dec -Dbuildtype=release

Alternate setup with AMD drivers only in release mode (recommended for AMD performance testing):

meson setup build64 --libdir lib64 --prefix $HOME/mesa -Dgallium-drivers=radeonsi,swrast,zink -Dvulkan-drivers=amd -Dbuildtype=release

Alternate setup with RADV only in debug mode (recommended for bisecting RADV crashes, etc.)

meson setup build64radvdebug --libdir lib64 --prefix $HOME/mesa -Dgallium-drivers= -Dvulkan-drivers=amd -Dbuildtype=debug

Alternate setup with RADV only in debug mode without LLVM (recommended when bisecting old versions with incompatible LLVM versions)

meson setup build64radvdebug --libdir lib64 --prefix $HOME/mesa -Dllvm=disabled -Dgallium-drivers= -Dvulkan-drivers=amd -Dbuildtype=debug

You can compile one with ninja -C build64radvdebug and the other with ninja -C build64 - they don't interfere with each other. Of course if you use the same install prefix they will overwrite each other when you install them.
Note about upgrading to a different version of mesa

You can use the usual git commands for updating, for example git pull etc. You don't need to re-run meson but you do need to re-run ninja (eg. ninja -C build64 install) to compile and install the changes in the new version.
Step 4. 32-bit build on an x86_64 system (skip when only testing a 64-bit game)

For the 32-bit build, you will need to install the 32-bit variant of the development packages for all dependencies. Note that some distributions do not allow installing both the 32-bit and 64-bit version of some or all development packages, especially LLVM. (For example Ubuntu notoriously disallows both 32-bit and 64-bit LLVM development packages, and sometimes it gets buggy on other distros as well.)
As annoying as that sounds, this means that on some (buggy) distros you may have to uninstall some 64-bit development packages before the distro allows you to install the 32-bit ones.
Specifically for Fedora:
# 32-bit version of pkg-config, see notes below
dnf install pkgconf-pkg-config.i686

# Various 32-bit development packages of libraries
dnf install glibc-devel.i686 libdrm-devel.i686 elfutils-libelf-devel.i686 wayland-devel.i686 libffi-devel.i686 libxcb-devel.i686 libXau-devel.i686 libX11-devel.i686 libXext-devel.i686 libXfixes-devel.i686 libxshmfence-devel.i686 libXxf86vm-devel.i686 libXrandr-devel.i686 libXrender-devel.i686 libclc-devel.i686

# 32-bit development package of LLVM, this may not work when the 64-bit version is also installed
dnf install llvm-devel.i686

Make sure the meson cross directory exists:
mkdir -p ~/.local/share/meson/cross

Create a meson cross file here: ~/.local/share/meson/cross/gcc-i686 with the following content.
If you don't use Fedora (or another Red Hat family distro), replace i686-redhat-linux-gnu-pkg-config with the correct 32-bit pkg-config executable for your distro. Also verify the location of llvm-config-32 which might be different on another distro.
[binaries]
c='gcc'
cpp='g++'
ar='ar'
strip='strip'
pkg-config='i686-redhat-linux-gnu-pkg-config'
llvm-config='/usr/bin/llvm-config-32'

[built-in options]
c_args=['-m32', '-march=native']
c_link_args=['-m32']
cpp_args=['-m32', '-march=native']
cpp_link_args=['-m32']

[host_machine]
system='linux'
cpu_family='x86'
cpu='x86'
endian='little'

Now you can use it to build 32-bit mesa libs.
32-bit setup with Intel and AMD drivers only in release mode, including codecs:

cd ~/Projects/mesa
meson setup build32 --cross-file gcc-i686 --libdir lib --prefix $HOME/mesa -Dgallium-drivers=radeonsi,swrast,iris,zink -Dvulkan-drivers=intel,amd -Dvideo-codecs=h264dec,h264enc,h265dec,h265enc,vc1dec -Dbuildtype=release
ninja -C build32 install

Note that you can build both the x86_64 and the i686 libraries together and they can still all go to ~/mesa, meaning there is no need to configure anything else when you need both 32 and 64-bit. You can build both 64 and 32 bit Mesa in the same prefix and use all of that with either 32-bit or 64-bit games.
Using the compiled mesa binaries

Running through a script (recommended for testing a single game or app)

Create a script file like this, eg. nano ~/mesa-run.sh

If you used a different install prefix or a different lib dir above, you will need to adjust this script accordingly.
#!/bin/sh

MESA=$HOME/mesa \
LD_LIBRARY_PATH=$MESA/lib64:$MESA/lib:$LD_LIBRARY_PATH \
LIBGL_DRIVERS_PATH=$MESA/lib64/dri:$MESA/lib/dri \
VK_ICD_FILENAMES=$MESA/share/vulkan/icd.d/radeon_icd.x86_64.json:$MESA/share/vulkan/icd.d/radeon_icd.x86.json \
LIBVA_DRIVERS_PATH=$MESA/lib64/dri:$MESA/lib/dri \
VDPAU_DRIVER_PATH=$MESA/lib64/vdpau \
OCL_ICD_VENDORS=$MESA/etc/OpenCL/vendors/rusticl.icd \
    exec "$@"

Don't forget to add executable permissions to the script:
chmod +x ~/mesa-run.sh

Now you can run your games like:
~/mesa-run.sh vkcube

Note about games with a 32-bit launcher

Some games have a launcher which is a small app that doesn't do anything useful other than launching the game. These are ofen 32-bit apps, so if you want to run a game that has such a launcher and it doesn't work, you may need to do the 32-bit build to make it work.
Testing a Steam game with your custom built mesa:


Compile mesa as written above
Create the ~/mesa-run.sh script as above
First make sure it works correctly with vkcube or another simple sample app from the terminal
Open Steam, go to your Library
Right-click the game, click "Properties"
In the "Launch options" type:

~/mesa-run.sh %command%

Alternative: sourcing a script method

Use this when you want all apps you launch from a terminal to use your custom built mesa.
Create a script at ~/mesa.sh with the following content.

If you used a different install prefix or a different lib dir above, you will need to adjust this script accordingly.
#!/bin/sh

MESA=$HOME/mesa

export LD_LIBRARY_PATH=$MESA/lib64:$MESA/lib:$LD_LIBRARY_PATH
export LIBGL_DRIVERS_PATH=$MESA/lib64/dri:$MESA/lib/dri
export VK_ICD_FILENAMES=$MESA/share/vulkan/icd.d/radeon_icd.x86_64.json:$MESA/share/vulkan/icd.d/radeon_icd.i686.json
export LIBVA_DRIVERS_PATH=$MESA/lib64/dri:$MESA/lib/dri
export VDPAU_DRIVER_PATH=$MESA/lib64/vdpau
export OCL_ICD_VENDORS=$MESA/etc/OpenCL/vendors/rusticl.icd

Now you can just source mesa.sh and then anything launched from that terminal will use the mesa libs you just built.
For example:
source ~/mesa.sh
vkcube

To verify that it uses the version of mesa you want:
source ~/mesa.sh
vulkaninfo

Using RADV with RGP

# Run RADV with pipeline tracing enabled, and specify a trigger file
RADV_THREAD_TRACE_PIPELINE=1 RADV_THREAD_TRACE_TRIGGER=/tmp/trigger ~/mesa-run.sh ./bin/triangle

# From a different terminal, touch the trigger file. This will make RADV create an RGP capture in /tmp
touch /tmp/trigger

Building LLVM and using it with mesa (skip this unless you know you specifically need it)

Only build a custom LLVM if you are really sure you need it. Most of the time you don't.
Sometimes you need to test the very latest LLVM and use it without messing up your system packages.
Here are some useful cmake options:

CMAKE_INSTALL_PREFIX - for simplicity, let's just use the same prefix as used by your mesa build
LLVM_LIBDIR_SUFFIX - for distros that use /usr/lib64 or a similar convention, eg. set this to 64 on Fedora

Example:
cd llvm-project/llvm
mkdir build
cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$HOME/mesa -DLLVM_LIBDIR_SUFFIX=64 -DLLVM_TARGETS_TO_BUILD="AMDGPU" -DLLVM_OPTIMIZED_TABLEGEN=ON -DLLVM_BUILD_LLVM_DYLIB=ON -DLLVM_LINK_LLVM_DYLIB=ON -DLLVM_INCLUDE_EXAMPLES=OFF
ninja
ninja install

After this, you need to rebuild mesa. First, tell mesa's meson to use the LLVM that you just built.
Create a meson native file at $HOME/.local/share/meson/native/my-llvm-x64 with the following content. Substitute Timur with your own username.
[binaries]
llvm-config = "/home/Timur/mesa/bin/llvm-config"

Finally, specify this to meson using the --native-file=my-llvm-x64 argument, for example:
meson build64 --libdir <your libdir> --prefix <your prefix> <other options> --native-file=my-llvm-x64
ninja -C build64 install