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>

    &lfs121_checked;

    <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">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
    <!-- 9 Apr 23.  Change to unversioned patch since it never changes. -->
      <listitem>
        <para>
          Recommended patch:
          <ulink url="&patch-root;/mesa-add_xdemos-2.patch"/>
          (installs 2 demo programs for testing Mesa - not needed if you
          install the <ulink url="https://archive.mesa3d.org/demos/">
          mesa-demos</ulink> package)
        </para>
      </listitem>
    </itemizedlist>

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

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

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

      <xref linkend="glslang"/> (required for Vulkan support),

      <xref linkend="libglvnd"/> (Required for <xref linkend="steam"/>),

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

      <xref linkend="libvdpau"/> (to build VDPAU drivers),

      <xref linkend="llvm"/> (required for the r300, r600, and radeonsi
      drivers, and the LLVMpipe software rasterizer which can make the
      swrast driver much faster),

      <xref linkend="rust"/>, <xref linkend="cbindgen"/>, and
      <xref linkend="rust-bindgen"/> (required for NVK),

      <xref linkend="mesonnative"/> (required for multilib lib32-NVK),

      <xref linkend="wayland-protocols"/> (required for
        KDE Plasma,
        GNOME,
        and recommended for GTK), and

      <xref linkend="libvk"/> (required for Vulkan support)
    </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 extra demos to test
      <application>Mesa</application>; this includes the same programs added by
      the patch above),
      <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>
-->
  </sect2>

  <sect2 role="installation">
    <title>Installation of Mesa</title>
    
    <note>
      <para>
        Don't apply the xdemos patch if you are doing multilib and are going
	to be compiling the 32-bit variant, as the build fails. If you want to
	apply the patch for the 64-bit build, do so then remove the Mesa
	directory and unpack the tarball and create the build directory again.
	Then skip the step where you clean the build directory and follow the
	directions as normal.
      </para>
    </note>

    <para>
      If you have downloaded the xdemos patch (needed if testing the Xorg
      installation per GLFS instructions), apply it by running the following
      command:
    </para>

<!--<screen><userinput>patch -Np1 -i ../mesa-&mesa-version;-add_xdemos-1.patch</userinput></screen>-->
<screen><userinput>patch -Np1 -i ../mesa-add_xdemos-2.patch</userinput></screen>

   <!-- Note that freedreno, vc4, and virgl all need special support from
        libdrm - renodr
        For me, libdrm does not mention virgl, but mesa accepts it. AFAICS
        freedreno is for qualcom hardware, libdrm will build for it on suitable
        systems. VC4 is for the Broadcom VC4 used in the raspberry pi - ken -->
<!--
    <note>
      <para>
        The measurements above, and the Contents below, are for a full build.
        Many people will not wish to install drivers they cannot use, so the
        following paragraphs explain how to limit the drivers, and give an
        example which can be be reduced or amended as necessary.
      </para>
    </note>

-->
<!--
    <para>
      The (non-gallium) DRI drivers available in X86 are auto, <emphasis>or
      alternatively a choice from</emphasis> i915, i965, nouveau, r100, r200,
      and swrast. Use 'auto' to build all available DRI drivers, or use an
      empty string (DRI_DRIVERS="") if you wish to only build gallium drivers.
    </para>

    <para>
      The platforms ("window systems") available for X86 linux are x11, wayland,
     drm, and surfaceless. By not specifying anything, the meson
      build-system will build for all these platforms if you have the
      dependencies, identical to if you had specified '-Dplatforms=auto'.
    </para>

    <para>
      Modify the commands below for your desired drivers.  The drivers listed
      below will cover most modern video cards and virtual machines.  For help in
      selecting drivers see <ulink url="https://docs.mesa3d.org/systems.html"/>.
-->
      <!-- these two don't seem to be mentioned in that mesa link -->
<!--
      For intel drivers, specify crocus for i965 gen 4 through to haswell, iris
      for broadwell and later.
    </para>

    <note>
      <para>
        Although the nouveau drivers can be built for both gallium and dri, the
        i915 driver can only be built for one or the other.
      </para>
    </note>

<screen><userinput>GALLIUM_DRV="crocus,i915,iris,nouveau,r600,radeonsi,svga,swrast,virgl"
DRI_DRIVERS="i965,nouveau"</userinput></screen>
-->

    <!-- https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/22021 -->
<!-- No longer needed
    <para>
      Remove two unneeded references to LLVM headers to avoid a build
      failure with LLVM 17 or later:
    </para>

<screen><userinput>sed '/Scalar.h/d;/Utils.h/d' \
    -i src/gallium/auxiliary/gallivm/lp_bld_init.c</userinput></screen>
-->
    <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     \
      -Dosmesa=true           \
      -Dplatforms=x11,wayland \
      -Dgallium-drivers=auto  \
      -Dvulkan-drivers=auto   \
      -Dvalgrind=disabled     \
      -Dlibunwind=disabled    \
      -Dglvnd=enabled         \
      ..                      &amp;&amp;

ninja</userinput></screen>

    <para>
      To test the results, issue:
      <command>meson configure -Dbuild-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                              \
      -Dosmesa=true                                    \
      -Dplatforms=x11,wayland                          \
      -Dgallium-drivers=auto                           \
      -Dvulkan-drivers=auto                            \
      -Dvalgrind=disabled                              \
      -Dlibunwind=disabled                             \
      -Dglvnd=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
rm -rf DESTDIR
ldconfig</userinput></screen>

  </sect2>

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

    <note>
      <para>
	 NVK does not currently build with current GLFS instructions.
         You can try but odds are the build will fail. The instructions
	 below serve as ground work.
      </para>
    </note>

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

    <para>
      NVK has 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>. If the expanded
      path is <filename>/usr</filename>, skip to the NVK compilation
      instructions. 
    </para>

    <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 by following the commands:
    </para>

<screen><userinput>meson setup                                       \
            --native-file x86                     \
            --prefix=$XORG_PREFIX	          \
            --libdir=$XORG_PREFIX/lib32           \
            --buildtype=release                   \
            -Dplatforms=x11,wayland               \
            -Dgallium-drivers=                    \
            -Dvulkan-drivers=nouveau-experimental \
            -Dglx=disabled                        \
            -Degl=disabled                        \
            -Dopengl=false                        \
            -Dgles1=disabled                      \
            -Dgles2=disabled                      \
            -Dvalgrind=disabled                   \
            -Dlibunwind=disabled                  \
            ..                                    &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
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>
      <anchor id='mesa-gallium-drivers' xreflabel='Mesa Gallium3D Drivers'/>
      <parameter>-Dgallium-drivers=auto</parameter>: This parameter
      controls which Gallium3D drivers should be built.
      
      <literal>auto</literal> selects all Gallium3D drivers available
      for x86: 

      <literal>r300</literal> (for ATI Radeon 9000 or Radeon X
      series), 

      <literal>r600</literal> (for AMD/ATI Radeon HD 2000-6000
      series), 

      <literal>radeonsi</literal> (for AMD Radeon HD 7000 or newer
      AMD GPU models), 

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

      <literal>virgl</literal> (for QEMU virtual GPU
      with <application>virglrender</application> support), 
      
      <literal>svga</literal> (for VMWare virtual GPU),
      
      <literal>swrast</literal> (using CPU for 3D rasterisation; needed for
      OSMesa which provides OpenGL bitmap support),

      <literal>zink</literal> (a driver converting Vulkan calls to OpenGL;
      however, it is unstable and a lot of applications can't use it besides
      demos),

      <literal>iris</literal> (for Intel GPUs shipped with Broadwell or newer
      CPUs),

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

      <literal>i915</literal> (for Intel GMA 900, 950, 3100, or 3150 GPUs
      shipped with chipsets or Atom D/N 4xx/5xx CPUs). 

      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>-Dgallium-drivers=radeonsi,iris,swrast</option>.
    </para>
<!--
    <para>
      <parameter>-Dosmesa=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>-Dplatforms=...</parameter>: This parameter
      controls which windowing systems will be supported. Available
      linux platforms are x11 and wayland.
    </para>

    <para>
      <parameter>-Dvulkan-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 'amd', 'intel', 'intel_hasvk', 'nouveau-experimental'
      and 'swrast'. If you do not want Vulkan support, change 'auto' to "".
    </para>

    <para>
      <parameter>-Dvalgrind=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>-Dlibunwind=disabled</parameter>: This parameter disables
      the usage of libunwind.
    </para>

    <para>
      <parameter>-Dglvnd=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 -Dbuild-tests=true</command>: This command will
      reconfigure the build to set <option>-Dbuild-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>-Degl-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 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>
          glxgears and glxinfo
        </seg>
        <seg>
          libEGL.so,
          libGL.so,
          libGLESv1_CM.so,
          libGLESv2.so,
          libgbm.so,
          libglapi.so, and
          libxatracker.so
        </seg>
        <seg>
          <!-- d3dadapter9.so (optional)
               I guess this is useless today, Wine applications use Vulkan
               through libvkd3d, and new games with native Linux support
               likely uses Vulkan directly.  -->
          <!-- Begin gallium DRI drivers (*_dri.so) and VA-API drivers
               (*_drv_video.so): this is the full set -->
          crocus_dri.so,
          i915_dri.so,
          iris_dri.so,
          kms_swrast_dri.so,
          nouveau_dri.so,
          nouveau_drv_video.so,
          r300_dri.so,
          r600_dri.so,
          r600_drv_video.so,
          radeonsi_dri.so,
          radeonsi_drv_video.so,
          swrast_dri.so,
          virtio_gpu_dri.so,
          virtio_gpu_drv_video.so,
	  vmwgfx_dri.so, and
          zink_dri.so
          <!-- End DRI 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="glxgears">
        <term><command>glxgears</command></term>
        <listitem>
          <para>
            is a GL demo useful for troubleshooting graphics
            problems
          </para>
          <indexterm zone="mesa glxgears">
            <primary sortas="b-glxgears">glxgears</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="glxinfo">
        <term><command>glxinfo</command></term>
        <listitem>
          <para>
            is a diagnostic program that displays information about the
            graphics hardware and installed GL libraries
          </para>
          <indexterm zone="mesa glxinfo">
            <primary sortas="b-glxinfo">glxinfo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

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