Files
glfs/shareddeps/drivers/mesa.xml
2025-06-09 15:34:38 -06:00

700 lines
23 KiB
XML

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % general-entities SYSTEM "../../general.ent">
%general-entities;
<!ENTITY mesa-download-http "https://mesa.freedesktop.org/archive/mesa-&mesa-version;.tar.xz">
]>
<sect1 id="mesa" xreflabel="Mesa-&mesa-version;">
<?dbhtml filename="mesa.html"?>
<title>Mesa-&mesa-version;</title>
<indexterm zone="mesa">
<primary sortas="a-Mesa">Mesa</primary>
</indexterm>
<sect2 role="package">
<title>Introduction to Mesa</title>
<para>
<application>Mesa</application> offers a wide variety of graphic
software, like the OpenGL libraries and drivers, Vulkan drivers,
and other drivers.
</para>
<para>
Every driver from this package works with <xref linkend="libglvnd"/>. The
package will auto-detect a <application>libglvnd</application>
installation if present and will link against the libraries provided by
that package. Thus, the OpenGL libraries provided by this package will
not be built, only the drivers for OpenGL.
</para>
<important><para>
Read <xref linkend="aboutgl"/> to decide if you want to install OpenGL
implementations from this provider.
If you want to install <xref linkend="libglvnd"/>, install that
<emphasis>FIRST</emphasis> before installing this package so that this
package's OpenGL implementations do not get built.
</para></important>
<note>
<para>
<application>Mesa</application> is updated relatively often. You may
want to use the latest available &mesa-major-minor;.x mesa version.
</para>
</note>
<note>
<para>
An Internet connection is needed for building the Nouveau Vulkan
driver. The system certificate store may need to be set up with
<xref role='recommended' linkend='make-ca'/> before building this
package.
</para>
</note>
&long-build-time;
<itemizedlist spacing="compact">
<listitem>
<para>
Download (HTTP): <ulink url="&mesa-download-http;"/>
</para>
</listitem>
</itemizedlist>
<!--
<para>
<emphasis role="strong">Patch for Seizure Prevention (Recommended)</emphasis>
</para>
<itemizedlist spacing="compact">
<listitem>
<para>
Recommended patch:
<ulink url="&patch-root;/mesa/mesa-seizure_prevention-2.patch"/>
</para>
</listitem>
</itemizedlist>
-->
<bridgehead renderas="sect3">Mesa Dependencies</bridgehead>
<bridgehead renderas="sect4">Required</bridgehead>
<para role="required">
<xref linkend="libdrm"/>,
<xref linkend="mako"/>,
<xref linkend="pyyaml"/>, and
<xref linkend="xorg7-lib"/>
</para>
<bridgehead renderas="sect4">Recommended</bridgehead>
<para role="recommended">
<itemizedlist spacing="compact">
<listitem>
<para>
<xref linkend="cbindgen"/>, <xref linkend="make-ca"/>,
<xref linkend="mesonfiles"/>, <xref linkend="rust-bindgen"/>, and
<xref linkend="rustc"/> (required for Nouveau Vulkan)
</para>
</listitem>
<listitem>
<para>
<xref linkend="glslang"/> (required for Vulkan support)
</para>
</listitem>
<listitem>
<para>
<xref linkend="libclc"/> (required for the Intel Iris Gallium3D)
</para>
</listitem>
<listitem>
<para>
<xref role="first" linkend="libva"/> (to provide VA-API support for some
Gallium3D drivers, note that there is a circular dependency. You must
build <application>libva</application> first without EGL and GLX support,
install this package, and rebuild <application>libva</application>)
</para>
</listitem>
<listitem>
<para>
<xref linkend="libvdpau"/> (to build VDPAU drivers)
</para>
</listitem>
<listitem>
<para>
<xref linkend="llvm"/> (required for the r300, r600, and radeonsi
drivers, and the LLVMpipe software rasterizer; Clang in LLVM is
required for Swrast Vulkan)
</para>
</listitem>
<listitem>
<para>
<xref linkend="ply"/> (required for Intel Vulkan)
</para>
</listitem>
<listitem>
<para>
<xref linkend="libvk"/> (required for the Zink Gallium3D driver)
</para>
</listitem>
<listitem>
<para>
<xref linkend="wayland-protocols"/> (required for many desktop
environments and recommended for GTK)
</para>
</listitem>
</itemizedlist>
</para>
<bridgehead renderas="sect4">Optional</bridgehead>
<para role="optional">
&gbm;,
<ulink url="&blfs-svn;/general/libgcrypt.html">libgcrypt</ulink>,
<xref linkend="libglvnd"/>,
<xref linkend="libunwind"/>,
<ulink url="&blfs-svn;/general/lm-sensors.html">lm-sensors</ulink>,
<!-- for libsensors according to Meson -->
<xref linkend="nettle"/>,
<ulink url="&blfs-svn;/general/valgrind.html">valgrind</ulink>,
<ulink url="&slfs-website;/general/mesa-demos.html">Mesa-Demos</ulink>
(provides more than 300 demos to test <application>Mesa</application>),
<ulink url="https://omxilurceforge.net/">Bellagio OpenMAX Integration
Layer</ulink> (for mobile platforms), and
<ulink url="https://github.com/tizonia/tizonia-openmax-il/wiki/Tizonia-OpenMAX-IL/">
libtizonia</ulink>
</para>
</sect2>
<sect2 role="installation">
<title>Installation of Mesa</title>
<para>
Install <application>Mesa</application> by running the following
commands:
</para>
<screen><userinput>mkdir build &amp;&amp;
cd build &amp;&amp;
meson setup \
--prefix=/usr \
--buildtype=release \
-D platforms=x11,wayland \
-D gallium-drivers=auto \
-D vulkan-drivers=auto \
-D gles1=disabled \
-D video-codecs=all \
-D valgrind=disabled \
-D libunwind=disabled \
.. &amp;&amp;
ninja</userinput></screen>
<para>
To test the results, issue:
<command>meson configure -D build-tests=true &amp;&amp; ninja test</command>.
</para>
<para>
Now, as the <systemitem class="username">root</systemitem> user:
</para>
<screen role="root"><userinput>ninja install</userinput></screen>
<para>
If desired, install the optional documentation by running
the following commands as the
<systemitem class="username">root</systemitem> user:
</para>
<screen role="root"
remap="doc"><userinput>cp -rv ../docs -T /usr/share/doc/mesa-&mesa-version;</userinput></screen>
</sect2>
<sect2 role="installation">
<title>lib32 Installation of Mesa</title>
<para>
Install lib32-<application>Mesa</application> by running the following
commands:
</para>
<screen><userinput>rm -rf * &amp;&amp;
meson setup \
--cross-file=lib32 \
--prefix=/usr \
--libdir=/usr/lib32 \
--buildtype=release \
-D platforms=x11,wayland \
-D gallium-drivers=auto \
-D vulkan-drivers=auto \
-D gles1=disabled \
-D video-codecs=all \
-D valgrind=disabled \
-D libunwind=disabled \
.. &amp;&amp;
sed -i 's/\/usr\/lib\//\/usr\/lib32\//g' ./build.ninja &amp;&amp;
BINDGEN_EXTRA_CLANG_ARGS="-m32" ninja</userinput></screen>
<para>
Now, as the <systemitem class="username">root</systemitem> user:
</para>
<screen role="root"><userinput>DESTDIR=$PWD/DESTDIR ninja install &amp;&amp;
cp -vr DESTDIR/usr/lib32/* /usr/lib32 &amp;&amp;
if [ -d DESTDIR/usr/share/vulkan ]; then
cp -vR DESTDIR/usr/share/vulkan /usr/share
fi &amp;&amp;
rm -rf DESTDIR &amp;&amp;
ldconfig</userinput></screen>
</sect2>
<sect2 role="commands">
<title>Command Explanations</title>
&options-meson;
<para>
<parameter>--buildtype=release</parameter>: This switch ensures a
fully-optimized build, and disables debug assertions which will
severely slow down the libraries in certain use-cases. Without this
switch, build sizes can span into the 2GB range.
</para>
<para>
<parameter>-D platforms=...</parameter>: This parameter
controls which windowing systems will be supported. Available
linux platforms are x11 and wayland.
</para>
<para>
<parameter>-D gallium-drivers=auto</parameter>: This parameter
controls which Gallium3D drivers should be built. Gallium drivers
are essentially OpenGL drivers. If you wish to build
specific drivers, valid options include:
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>auto</literal> selects all Gallium3D drivers available
for x86
</para>
</listitem>
<listitem>
<para>
<literal>r300</literal> (for ATI Radeon 9000 or Radeon X
series)
</para>
</listitem>
<listitem>
<para>
<literal>r600</literal> (for AMD/ATI Radeon HD 2000-6000
series)
</para>
</listitem>
<listitem>
<para>
<literal>radeonsi</literal> (for AMD Radeon HD 7000 or newer
AMD GPU models)
</para>
</listitem>
<listitem>
<para>
<literal>nouveau</literal>
(for Supported NVIDIA GPUs, they are listed as all
<quote>3D features</quote> either <quote>DONE</quote> or
<quote>N/A</quote> in <ulink
url='https://nouveau.freedesktop.org/FeatureMatrix.html'>the Nouveau
status page</ulink>)
</para>
</listitem>
<listitem>
<para>
<literal>virgl</literal> (for QEMU virtual GPU
with <application>virglrender</application> support)
</para>
</listitem>
<listitem>
<para>
<literal>svga</literal> (for VMWare virtual GPU)
</para>
</listitem>
<listitem>
<para>
<literal>softpipe</literal> (using CPU for 3D rasterization)
</para>
</listitem>
<listitem>
<para>
<literal>llvmpipe</literal> (<literal>softpipe</literal> but uses
<application>LLVM</application> to increase performance)
</para>
</listitem>
<listitem>
<para>
<literal>zink</literal> (a driver converting OpenGL calls to Vulkan;
if the Vulkan driver is performant, this driver can also be
performant; can be used as a replacement for Gallium3D drivers like
<literal>nouveau</literal> as detailed in
<xref linkend="whatnow"/>)
</para>
</listitem>
<listitem>
<para>
<literal>iris</literal> (for Intel GPUs shipped with Broadwell or newer
CPUs)
</para>
</listitem>
<listitem>
<para>
<literal>crocus</literal> (for Intel GMA 3000, X3000 series, 4000 series,
or X4000 series GPUs shipped with chipsets, or Intel HD GPUs shipped with
pre-Broadwell CPUs)
</para>
</listitem>
<listitem>
<para>
<literal>i915</literal> (for Intel GMA 900, 950, 3100, or 3150 GPUs
shipped with chipsets or Atom D/N 4xx/5xx CPUs)
</para>
</listitem>
</itemizedlist>
You may replace <literal>auto</literal> with a comma-separated list to
build only a subset of these drivers if you precisely know which drivers
you need, for example:
<option>-D gallium-drivers=radeonsi,iris,swrast</option>.
</para>
<para>
<parameter>-D vulkan-drivers=auto</parameter>: This switch enables support
for the Vulkan graphics API. It automatically builds all graphics drivers
that are available for Vulkan. If you wish to build specific drivers,
valid options include:
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>amd</literal> (for AMD Radeon HD 7730 or newer AMD GPUs)
</para>
</listitem>
<listitem>
<para>
<literal>intel</literal> (for Intel GPUs shipped with Skylake or newer
CPUs, or as a dedicated PCIe card)
</para>
</listitem>
<listitem>
<para>
<literal>intel_hasvk</literal> (for Intel GPUs shipped with Ivy Bridge,
Haswell, or Broadwell CPUs)
</para>
</listitem>
<listitem>
<para>
<literal>nouveau</literal> (for GTX 16XX, RTX 20XX, or newer NVIDIA GPUs;
this driver is maturing and is already quite performant, although less so
than the <application>NVIDIA</application> driver; however, it is a good
replacement, especially when used with <literal>zink</literal>)
</para>
</listitem>
<listitem>
<para>
<literal>swrast</literal> (using CPU for 3D rasterization. Note that it's
much slower than using a modern 3D-capable GPU)
</para>
</listitem>
</itemizedlist>
You may replace <literal>auto</literal> with a comma-separated list to
build only a subset of these drivers if you precisely know which drivers
you need, for example:
<option>-D vulkan-drivers=amd,nouveau,swrast</option>.
</para>
<para>
<parameter>-D gles1=disabled</parameter>: This flag disables building a
deprecated spec of OpenGL ES.
</para>
<para>
<parameter>-D video-codecs=all</parameter>: This parameter enables
building all the video codecs as they are disabled by default to avoid
legal issues. It would be prudent to not distribute your build if you
set this option. The matter is still unclear, however. See this
<ulink url="https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1016687">
Debian bug report</ulink> for more info.
</para>
<para>
<parameter>-D valgrind=disabled</parameter>: This parameter disables
the usage of Valgrind during the build process. Remove this parameter
if you have Valgrind installed, and wish to check for memory leaks.
</para>
<para>
<parameter>-D libunwind=disabled</parameter>: This parameter disables
the usage of libunwind.
</para>
<para>
<option>-D egl-native-platform="..."</option>: This parameter
controls which Embedded Graphics Library support will be built. Available
linux options are auto (default), x11, wayland, surfaceless, and drm.
</para>
<para>
<option>-D gles2=disabled</option>: If you don't need OpenGL ES, use
this option. Be sure to read <xref linkend="aboutgles"/>.
</para>
<para>
<option>-D legacy-x11="..."</option> This parameter controls which legacy
X11 features get built-in support. Available linux options are none
(default) and dri2. These features are rarely needed anymore.
</para>
<para>
<option>-D libgbm-external=true</option>: This links against the
system-installed <filename class="libraryfile">libgbm</filename> and
disables building the GBM if it's installed. Whenever updating this
package, it is recommended to also update the GBM so this option is not
used.
</para>
<para>
<computeroutput>BINDGEN_EXTRA_CLANG_ARGS="-m32"</computeroutput>: This
variable ensures that <xref linkend="rust-bindgen"/> generates bindings
that don't go out of bounds when compiling lib32 Nouveau Vulkan.
</para>
<para>
<command>sed -i 's/\/usr\/lib\//\/usr\/lib32\//g' ./build.ninja</command>:
This package can be stubborn and likes to link against LLVM libraries in
<filename>/lib</filename>, even on a multilib installation, so this command
tells this package to link against libraries in the proper directory.
</para>
<para>
<command>meson configure -D build-tests=true</command>: This command will
reconfigure the build to set <option>-D build-tests=true</option>, but
keep the other options specified in the <command>meson setup</command>
command unchanged. It allows <command>ninja test</command> to build and
run unit tests.
</para>
</sect2>
<sect2 role="content">
<title>Contents</title>
<segmentedlist>
<segtitle>Installed Programs</segtitle>
<segtitle>Installed Libraries</segtitle><!-- in /usr/lib -->
<segtitle>Installed DRI Driver Stubs</segtitle><!-- in /usr/lib/dri -->
<segtitle>Installed VA-API Drivers</segtitle><!-- in /usr/lib/dri -->
<segtitle>Installed GBM Drivers</segtitle><!-- in /usr/lib/gbm -->
<segtitle>Installed VDPAU Drivers</segtitle><!-- in /usr/lib/vdpau -->
<segtitle>Installed Vulkan Drivers</segtitle><!-- in /usr/lib -->
<segtitle>Installed Directories</segtitle>
<seglistitem>
<seg>
None
</seg>
<seg>
libEGL (or libEGL_mesa if <xref linkend="libglvnd"/> is installed),
libGL (if <xref linkend="libglvnd"/> is not installed),
libGLESv2 (if <xref linkend="libglvnd"/> is not installed),
libgallium-&mesa-version;,
libgbm,
libglapi (if <xref linkend="libglvnd"/> is not installed),
libGLX_mesa (if <xref linkend="libglvnd"/> is installed), and
libxatracker
</seg>
<seg>
<!-- Begin DRI Driver Stubs -->
libdril_dri and symlinks to it:
crocus_dri,
i915_dri,
iris_dri,
kms_swrast_dri,
nouveau_dri,
r300_dri,
r600_dri,
r600_drv_video,
radeonsi_dri,
swrast_dri,
virtio_gpu_dri,
vmwgfx_dri, and
zink_dri
<!-- End DRI Driver Stubs -->
</seg>
<seg>
<!-- Begin VA-API Drivers -->
nouveau_drv_video,
radeonsi_drv_video, and
virtio_gpu_drv_video
<!-- End VA-API Drivers -->
</seg>
<seg>
<!-- Begin GBM drivers -->
dri_gbm
<!-- End GBM drivers -->
</seg>
<seg>
<!-- Begin VDPAU Drivers -->
libvdpau_nouveau,
libvdpau_r300,
libvdpau_r600,
libvdpau_radeonsi, and
libvdpau_virtio_gpu
(many of these drivers are hard-linked)
<!-- End VDPAU Drivers -->
</seg>
<seg>
libvulkan_intel_hasvk,
libvulkan_intel,
libvulkan_lvp,
libvulkan_nouveau, and
libvulkan_radeon
</seg>
<seg>
<!-- /usr/include/GL is installed by xorg-protos -->
/usr/{include/{EGL,GLES2,GLES3,KHR},
/usr/lib/{dri,gbm,vdpau}},
/usr/share/drirc.d (contains workarounds for various applications,
particularly browsers and games),
/usr/share/vulkan,
and /usr/share/doc/mesa-&mesa-version;
</seg>
</seglistitem>
</segmentedlist>
<variablelist>
<bridgehead renderas="sect3">Short Descriptions</bridgehead>
<?dbfo list-presentation="list"?>
<?dbhtml list-presentation="table"?>
<varlistentry id="dri_gbm">
<term><filename class='libraryfile'>dri_gbm</filename></term>
<listitem>
<para>
implements Graphics Buffer Management functions needed by
<systemitem class='library'>libgbm</systemitem> on top of
<systemitem class='library'>libdrm</systemitem>
</para>
</listitem>
</varlistentry>
<varlistentry id="libdril_dri">
<term><filename class='libraryfile'>libdril_dri</filename></term>
<listitem>
<para>
is a stub allowing Xorg server to co-operate with the Gallium3D
drivers
</para>
</listitem>
</varlistentry>
<varlistentry id="libEGL">
<term><filename class="libraryfile">libEGL</filename></term>
<listitem>
<para>
provides an interface between graphics APIs and the window system;
provided if <xref linkend="libglvnd"/> is not installed
</para>
<indexterm zone="mesa libEGL">
<primary sortas="c-libGL">libEGL</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="libgallium">
<term><filename class='libraryfile'>libgallium-&mesa-version;</filename></term>
<listitem>
<para>
contains all the Gallium3D drivers
</para>
</listitem>
</varlistentry>
<varlistentry id="libgbm">
<term><filename class="libraryfile">libgbm</filename></term>
<listitem>
<para>
is the <application>Mesa</application> Graphics Buffer
Manager library
</para>
<indexterm zone="mesa libgbm">
<primary sortas="c-libgbm">libgbm</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="libglapi">
<term><filename class="libraryfile">libglapi</filename></term>
<listitem>
<para>
is <application>Mesa's</application> implementation of the OpenGL
API; provided if <xref linkend="libglvnd"/> is not installed
</para>
<indexterm zone="mesa libglapi">
<primary sortas="c-libglapi">libglapi</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="libGLES2">
<term><filename class="libraryfile">libGLES2</filename></term>
<listitem>
<para>
contains OpenGL ES 2.x and 3.x calls; provided if <xref
linkend="libglvnd"/> is not installed
</para>
<indexterm zone="mesa libGLES2">
<primary sortas="c-libGLES2">libGLES2</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="libGL">
<term><filename class="libraryfile">libGL</filename></term>
<listitem>
<para>
is the main OpenGL library; provided if <xref linkend="libglvnd"/>
is not installed; <filename
class="libraryfile">libOpenGL</filename> is not provided by this
package
</para>
<indexterm zone="mesa libGL">
<primary sortas="c-libGL">libGL</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="libxatracker">
<term><filename class="libraryfile">libxatracker</filename></term>
<listitem>
<para>
is the XA state tracker for the VMWare vmwgfx driver
</para>
<indexterm zone="mesa libxatracker">
<primary sortas="c-libxatracker">libxatracker</primary>
</indexterm>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>