glfs/shareddeps/drivers/mesa.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">
  <!ENTITY mesa-download-ftp  " ">
]>

<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, offering the OpenGL library, OpenGL drivers, Vulkan drivers,
      and so forth.
    </para>

    <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>

    

    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&mesa-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&mesa-download-ftp;"/>
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Mesa Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="xorg7-lib"/>,
      <xref linkend="libdrm"/>,
      <xref linkend="mako"/>, and
      <xref linkend="pyyaml"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">

      <itemizedlist spacing="compact">
        <listitem>
          <para>
            <xref linkend="cbindgen"/>, <xref linkend="rust-bindgen"/>,
	    and <xref linkend="rust"/> (required for NVK and Vulkan swrast)
          </para>
        </listitem>
        <listitem>
          <para>
	    <xref linkend="glslang"/> (required for Vulkan support)
	  </para>
        </listitem>
        <listitem>
          <para>
            <xref linkend="libclc"/> (required for Intel Iris Gallium)
	  </para>
	</listitem>
        <listitem>
          <para>
            <xref linkend="libglvnd"/> (required for <xref linkend="steam"/>)
          </para>
        </listitem>
        <listitem>
	  <para>
            <xref role="first" linkend="libva"/> (to provide VA-API support for some
            gallium 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 Vulkan Swrast)
          </para>
        </listitem>
        <listitem>
          <para>
            <xref linkend="mesonfiles"/> (required for multilib 32-bit Nouveau and
            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">
      <ulink url="&blfs-svn;/general/libgcrypt.html">libgcrypt</ulink>,
      <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="https://archive.mesa3d.org/demos/">mesa-demos</ulink>
      (provides more than 300 demos to test <application>Mesa</application>),
      <ulink url="https://omxil.sourceforge.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>
<!--
    <note>
      <para>
        The instructions below assume that
        <application>LLVM</application> with the r600/amdgpu and host backends
        and run-time type information (RTTI - needed for nouveau) are installed.
        You will need to modify the instructions if you
        choose not to install all of these. For an explanation of Gallium3D see
        <ulink url="https://en.wikipedia.org/wiki/Gallium3D"/>.
      </para>
    </note>
-->

    <note>
      <para>
        An Internet connection is needed for building the Nouveau Vulkan driver.
      </para>
    </note>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Mesa</title>
    
    <note>
      <para>
        If you are using <xref linkend="nvidia"/> and wish to use
	<xref linkend="steam"/>, this package is still a requirement
	as <application>Steam</application> depends on Mesa's GBM,
	or else the webhelper will repeatedly launch and crash before
	showing an error screen. You will need to have at least one
	gallium driver for this package to compile. Set the option
	<parameter>-D gallium-drivers=nouveau</parameter> to get this
	package over and done with as then you can move on. The
	32-bit version of this package is not necessary if you are doing
	this.
      </para>
    </note>

    <para>
      Install <application>Mesa</application> by running the following
      commands:
    </para>

<screen><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup                    \
      --prefix=$XORG_PREFIX    \
      --buildtype=release      \
      -D osmesa=true           \
      -D platforms=x11,wayland \
      -D gallium-drivers=auto  \
      -D vulkan-drivers=auto   \
      -D valgrind=disabled     \
      -D video-codecs=all      \
      -D libunwind=disabled    \
      -D glvnd=enabled         \
      ..    &amp;&amp;

ninja</userinput></screen>

    <para>
      To test the results, issue:
      <command>meson configure -D build-tests=true &amp;&amp; ninja test</command>.
    </para>
<!-- All 88 tests passed for me for 22.3.3 [pierre]
     All 90 tests passed for me for 23.1.0 [bdubbs]
     89 Tests passed for me, 1 timeout on 23.1.8 [rahul]
     All 98 tests passed for me for 23.3.1 [bdubbs]
-->

    <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>32-bit Installation of Mesa</title>

    <para>
      First clean the build directory:
    </para>

    <screen><userinput>rm -rf *</userinput></screen>

    <para>
      Install lib32-<application>Mesa</application> by running the following
      commands:
    </para>

<screen><userinput>CC="gcc -m32" CXX="g++ -m32"                 \
PKG_CONFIG_PATH=$XORG_PREFIX/lib32/pkgconfig \
meson setup                                  \
      --prefix=$XORG_PREFIX                  \
      --libdir=$XORG_PREFIX/lib32            \
      --buildtype=release                    \
      -D osmesa=true                         \
      -D platforms=x11,wayland               \
      -D gallium-drivers=auto                \
      -D vulkan-drivers=auto                 \
      -D valgrind=disabled                   \
      -D video-codecs=all                    \
      -D libunwind=disabled                  \
      -D glvnd=enabled                       \
      .. &amp;&amp;
      sed -i 's/\/usr\/lib\//\/usr\/lib32\//g' ./build.ninja &amp;&amp;

ninja</userinput></screen>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>DESTDIR=$PWD/DESTDIR ninja install
cp -vr DESTDIR/$XORG_PREFIX/lib32/* $XORG_PREFIX/lib32
if [ -d DESTDIR/$XORG_PREFIX/share/vulkan ]; then
     cp -vR DESTDIR/$XORG_PREFIX/share/vulkan $XORG_PREFIX/share
fi
rm -rf DESTDIR
ldconfig</userinput></screen>

  </sect2>

  <sect2 role="installation">
    <title>32-bit Installation of NVK and Vulkan Swrast</title>

    <note>
      <para>
        Feel free to skip this section if you don't want to install the
	Nouveau Vulkan driver (NVK) or Vulkan swrast.
      </para>
    </note>

    <para>
      NVK and Vulkan swrast have special requirements to be configured and
      compiled, requiring extra steps. You are going to need to modify a
      few paths in a personality
      file used by <application>Pkgconf</application>, as it searches in
      <filename>/usr</filename> rather than 
      <envar>$XORG_PREFIX</envar>.
    </para>

    <note>
      <para>If the expanded path is <filename>/usr</filename>, skip to cleaning
      the build directory.</para>
    </note>

    <para>
      Change the paths in the <application>Pkgconf</application> personality
      file as the <systemitem class="username">root</systemitem> user:
    </para>

<screen><userinput>sed -i 's/\/usr/\$XORG_PREFIX/g' \
    /usr/share/pkgconfig/personality.d/i686-pc-linux-gnu.personality</userinput></screen>

    <para>
      Now clean the build directory:
    </para>

    <screen><userinput>rm -rf *</userinput></screen>

    <para>
      Install lib32-NVK and/or Vulkan swrast by following the commands:
    </para>

<screen><userinput>meson setup                                      \
            --cross-file lib32                   \
            --prefix=$XORG_PREFIX	         \
            --libdir=$XORG_PREFIX/lib32          \
            --buildtype=release                  \
            -D platforms=x11,wayland             \
            -D gallium-drivers=softpipe,llvmpipe \
            -D vulkan-drivers=nouveau,swrast     \
            -D glx=disabled                      \
            -D egl=disabled                      \
            -D opengl=false                      \
            -D gles1=disabled                    \
            -D gles2=disabled                    \
            -D valgrind=disabled                 \
            -D libunwind=disabled                \
            .. &amp;&amp;
            sed -i 's/\/usr\/lib\//\/usr\/lib32\//g' ./build.ninja &amp;&amp;

ninja</userinput></screen>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen><userinput>DESTDIR=$PWD/DESTDIR ninja install
cp -vR DESTDIR/$XORG_PREFIX/lib32/* $XORG_PREFIX/lib32
cp -vR DESTDIR/$XORG_PREFIX/share/vulkan $XORG_PREFIX/share
rm -rf DESTDIR
ldconfig</userinput></screen>

    <para>
      If you modified the <application>Pkgconf</application> personality,
      you can change it back by doing the following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen><userinput>sed -i 's/\$XORG_PREFIX/\/usr/g' \
    /usr/share/pkgconfig/personality.d/i686-pc-linux-gnu.personality</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <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 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; needed for
            OSMesa which provides OpenGL bitmap support)
          </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 Vulkan calls to OpenGL;
            it is maturing and becoming more useful and performant and can be used
	    as a replacement for dri drivers like <literal>nouveau</literal>)
          </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 osmesa=true</parameter>: This switch enables building
      the <filename class="libraryfile">libOSMesa</filename> library and
      provides Gallium3D support in it. It requires the swrast gallium driver.
    </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 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 so performance isn't the best but is fairly
	    usable)
          </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 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 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 libunwind=disabled</parameter>: This parameter disables
      the usage of libunwind.
    </para>

    <para>
      <parameter>-D glvnd=enabled</parameter>: This parameter disables this
      package from building its own OpenGL library and uses the libraries
      provided by <xref linkend="libglvnd"/>. Omit parameter if you do not
      want to use <xref linkend="steam"/>. Otherwise, keep the parameter and
      install <xref linkend="libglvnd"/> before compiling this package.
    </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>

    <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>
      <command>sed -i 's/\/usr\/lib\//\/usr\/lib32\//g' ./build.ninja</command>:
      This package is 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>

  </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 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.so,
          libGL.so,
          libGLESv1_CM.so,
          libGLESv2.so,
          libgallium-&mesa-version;.so,		
          libgbm.so,
          libglapi.so,
          libOSMesa.so, and
          libxatracker.so
        </seg>
	<seg>
          <!-- Begin DRI Driver Stubs -->
          libdril_dri.so and symlinks to it:	
          crocus_dri.so,
          i915_dri.so,
          iris_dri.so,
          kms_swrast_dri.so,
          nouveau_dri.so,
          r300_dri.so,
          r600_dri.so,
          r600_drv_video.so,
          radeonsi_dri.so,
          swrast_dri.so,
          virtio_gpu_dri.so,
	  vmwgfx_dri.so, and
          zink_dri.so
          <!-- End DRI Driver Stubs -->
	</seg>
        <seg>
          <!-- Begin VA-API Drivers -->
          nouveau_drv_video.so,
          radeonsi_drv_video.so,
          virtio_gpu_drv_video.so,
          <!-- End VA-API Drivers -->
        </seg>
        <seg>
          <!-- Begin VDPAU Drivers -->
          libvdpau_nouveau.so,
          libvdpau_r300.so
          libvdpau_r600.so, and
          libvdpau_radeonsi.so
          libvdpau_virtio_gpu.so
          <!-- End VDPAU Drivers -->
          (Many of these drivers are hard-linked).
        </seg>
        <seg>
          libvulkan_intel_hasvk.so,
          libvulkan_intel.so,
          libvulkan_lvp.so, and
          libvulkan_nouveau.so, and
          libvulkan_radeon.so
        </seg>
        <seg>
          <!-- $XORG_PREFIX/include/GL is installed by xorg-protos -->
          $XORG_PREFIX/{include/{EGL,GLES,GLES2,GLES3,KHR},
          $XORG_PREFIX/lib/{dri,vdpau}},
          $XORG_PREFIX/share/drirc.d (contains workarounds for various applications,
          particularly browsers and games),
          $XORG_PREFIX/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="libEGL">
        <term><filename class="libraryfile">libEGL.so</filename></term>
        <listitem>
          <para>
            provides a native platform graphics interface as
            defined by the EGL-1.4 specification
          </para>
          <indexterm zone="mesa libEGL">
            <primary sortas="c-libGL">libEGL.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libgbm">
        <term><filename class="libraryfile">libgbm.so</filename></term>
        <listitem>
          <para>
            is the <application>Mesa</application> Graphics Buffer
            Manager library
          </para>
          <indexterm zone="mesa libgbm">
            <primary sortas="c-libgbm">libgbm.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libGLESv1_CM">
        <term><filename class="libraryfile">libGLESv1_CM.so</filename></term>
        <listitem>
          <para>
            is the <application>Mesa</application> OpenGL ES 1.1 library
          </para>
          <indexterm zone="mesa libGLESv1_CM">
            <primary sortas="c-libGLESv1_CM">libGLESv1_CM.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libGLES2">
        <term><filename class="libraryfile">libGLES2.so</filename></term>
        <listitem>
          <para>
            is the <application>Mesa</application> OpenGL ES 2.0 library
          </para>
          <indexterm zone="mesa libGLES2">
            <primary sortas="c-libGLES2">libGLES2.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libGL">
        <term><filename class="libraryfile">libGL.so</filename></term>
        <listitem>
          <para>
            is the main <application>Mesa</application> OpenGL library
          </para>
          <indexterm zone="mesa libGL">
            <primary sortas="c-libGL">libGL.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>