OpenSWR

Latest Linux Build Instructions

These instructions describe how to build OpenSWR within Mesa for Linux OS. The build uses the Meson build system with Ninja, as described in Mesa's Meson installation page. OpenSWR is built in Mesa with the addition of swr to the list of gallium drivers.

1. Introduction
2. Setup
   1. Building and Installing LLVM
3. Building Mesa with OpenSWR
4. Using Mesa with OpenSWR

As of March 2022, OpenSWR has been moved to the Amber branch of Mesa. This walkthrough uses the Amber branch (21.3.x), as committed to Mesa 21.3.7. OpenSWR has been removed from the primary Mesa branch. Thus, the Mesa 22.x branch and higher has OpenSWR removed. Review the latest Mesa branches for more information.

The instructions below describe how to compile Mesa using the Mesa released source tarballs. Compiling directly from the git repository is more complex and is beyond the scope of these instructions. If you want to compile from the git repository and you run into issues, please contact us directly.

Mesa requires dependencies to build:

• libtool-bin
• meson
• ninja
• python-pip
• g++
• git
• cmake
• xz-utils
• libx11-dev
• libxext-dev
• x11proto-core-dev
• x11proto-gl-dev
• libglew-dev
• freeglut3-dev
• bison
• flex
• libx11-xcb-dev
• pkg-config
• libxcb-randr0-dev

as well as the following two Python modules installed via pip:

• mako
• lxml

for testing:

• mesa-utils

Please make sure you install them prior to building. Refer to Mesa's installation page for more information on its requirements.

One of the major Mesa requirements is LLVM, but with some additional flags required at compile time. If you do not already have LLVM, you will need to build and install it first. Precompiled releases of LLVM were not compatable on the walkthrough system. LLVM source is available as a tarball on the LLVM release download page. Currently, LLVM version 12.0.1 is recommended. 13.x or 14.x are not recommended and have sighted portability limitations on the Mesa discussion board. Once downloaded, use the following steps to build and install LLVM. In this example we are installing them locally.

$ pwd
/home/openswr/llvm
$ ls
llvm-x.y.z.src.tar.xz
$ tar xJf llvm-x.y.z.src.tar.xz
$ mkdir build
$ cd build
$ cmake -G "Unix Makefiles" \
        -D CMAKE_BUILD_TYPE=Release \
        -D LLVM_TARGETS_TO_BUILD=X86 \
        -D BUILD_SHARED_LIBS=1 \
        -D LLVM_ENABLE_RTTI=1 \
        -D CMAKE_INSTALL_PREFIX=/home/openswr/.local/ \
        ../llvm-x.y.z.src
$ make -j `nproc`
$ make install
                

            export PATH=/home/openswr/.local/bin:${PATH}
                export LD_LIBRARY_PATH=/home/openswr/.local/lib:${LD_LIBRARY_PATH}
                

Download a Mesa source distribution from Mesa's download page. We recommend the latest non-release-candidate version for the best compatibility.

Once downloaded, use the following steps to build Mesa with OpenSWR.

$ pwd
/home/openswr/mesa
$ ls
mesa-x.y.z.tar.gz
$ tar xf mesa-x.y.z.tar.gz
$ cd mesa-x.y.z
$ mkdir build
                

Now we can configure Mesa with OpenSWR. In this example, we are installing Mesa locally.

$ meson --buildtype=release \
        -Dglx=gallium-xlib \
        -Dvulkan-drivers= \
        -Ddri-drivers= \
        -Dgallium-drivers=swrast,swr \
        -Dplatforms=x11 \
        -Dgallium-omx=disabled \
        -Dprefix=/home/openswr/.local \
        build
                

If you also want to compile OSMesa (off-screen rendering support), please add the following flag:

-Dosmesa=gallium
                

By default, the build will compile with support for AVX and AVX2 targets. If you want to also compile for Skylake and/or Knight's Landing architectures (AVX512), please add the following flag. Make sure your compiler supports the necessary compiler flags to compile for the specified architectures.

-Dswr-arches=avx,avx2,skx,knl
                

Check the ark processor database for architecture information for your target CPU SKUs

Once configured, you can use ninja to build Mesa.

$ ninja -C build
                

And you can use meson to install.

$ meson install -C build
                

Once installed, you will see libGL.so, libOSMesa.so (if it was enabled), and libSWR<arch>.so for each architecture selected.

If you installed Mesa with OpenSWR to a local directory as in the examples above, it should already be usable by applications. If you installed elsewhere, you will need to include the path in your LD_LIBRARY_PATH environment variable. Make sure you specifically add the lib or lib/gallium directory to LD_LIBRARY_PATH. You will also need the LLVM lib directory appended to your LD_LIBRARY_PATH if it is not present already.

$ export LD_LIBRARY_PATH=/your/path/to/mesa/lib:/your/path/to/llvm/lib:${LD_LIBRARY_PATH}
                

Now any application seeking GL will use the Mesa installation. To enable the OpenSWR driver, you need to specify it with the GALLIUM_DRIVER environment variable:

$ export GALLIUM_DRIVER=swr
                

You can verify that OpenSWR is used for rendering using the following command:

$ glxinfo | grep "OpenGL\ renderer\ string"
OpenGL renderer string: SWR (LLVM 12.0.1, 256 bits)
                

Instrument OpenSWR-based applications with useful environment variables. In particular, review the GALLIUM_ prefixed variables. Refer to the enviornment variable document on mesa3d.org for details on variables like:

GALLIUM_HUD
GALLIUM_LOG_FILE
GALLIUM_PRINT_OPTIONS
GALLIUM_DUMP_CPU
LIBGL_ALWAYS_SOFTWARE

To send any runtime information to stderr, ensure GALLIUM_PRINT_OPTIONS is set!:

export GALLIUM_PRINT_OPTIONS=1

SWR_PRINT_INFO can cause the runtime to emit SWR status. Documentation is limited since OpenSWR has moved to the Amber Branch. You may set it before running a program:

export SWR_PRINT_INFO=1

Look for a message like:

            SWR detected AVX2 instruction support (using: libswrAVX2.so).

Hello GL Quickstart

Many users employ glxgears and glxinfo from the Mesa demos repository to check that their distribution of Mesa is running. glxinfo and glxgears are found in the mesa-utils package. View the Mesa demos for more information.

Note: The performance advantages of OpenSWR tend to be realized in scenes with much more geometry than glxgears.