glfs/x/installing/mesa.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!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  "ftp://ftp.freedesktop.org/pub/mesa/mesa-&mesa-version;.tar.xz">
  <!ENTITY mesa-md5sum        "d0d76cd8b00bc1308e37985d4a45d3c5">
  <!ENTITY mesa-size          "11 MB">
  <!ENTITY mesa-buildsize     "1.6 GB (with demos and docs)">
  <!ENTITY mesa-time          "2.3 SBU (with parallelism=4, demos, and docs)">
]>

<sect1 id="mesa" xreflabel="Mesa-&mesa-version;">
  <?dbhtml filename="mesa.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <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> is an OpenGL compatible 3D graphics
      library.
    </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>

    &lfs84_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <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>
      <listitem>
        <para>
          Download MD5 sum: &mesa-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &mesa-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &mesa-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &mesa-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Recommended patch:
          <ulink
            url="&patch-root;/mesa-&mesa-version;-add_xdemos-2.patch"/>
          (installs 2 demo programs for testing Mesa - not needed if you
          install the <ulink url="ftp://ftp.freedesktop.org/pub/mesa/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">
      
      <phrase revision="systemd"><xref linkend="libva"/> (to build drivers for 
      supported hardware, 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>.),</phrase>
      
      <xref linkend="libvdpau"/> (to build VDPAU drivers),
      
      <xref linkend="llvm"/> (required for Gallium3D, r300, and radeonsi
      drivers and for the llvmpipe software rasterizer. See <ulink role="nodep"
      url="http://www.mesa3d.org/systems.html"/> for more information), and
      <xref linkend="wayland-protocols"/> (required for 
        <xref role="nodep" linkend='plasma5-build'/>,
        <!-- <xref role="nodep" linkend='lxqt'/>, -->
        GNOME, and 
        recommended for  <xref role="nodep" linkend='gtk3'/>)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="libgcrypt"/>,
      <xref linkend="lm_sensors"/> <!-- for libsensors according to Meson -->,
      <xref linkend="nettle"/>,
      <xref linkend="valgrind"/>,
      <ulink url="ftp://ftp.freedesktop.org/pub/mesa/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="http://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 are installed. You will need to modify the instructions if you
        choose not to install it.  For an explanation of Gallium3D see
        <ulink url="https://en.wikipedia.org/wiki/Gallium3D"/>.
      </para>
    </note>

    <para condition="html" role="usernotes">User Notes:
      <ulink url="&blfs-wiki;/mesa"/>
    </para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of Mesa</title>

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

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

   <!-- Note that freedreno, vc4, and virgl all need special support from
        libdrm - renodr -->

   <para>Now, select the drivers you wish to install.  
   The gallium available drivers are 
     kmsro, radeonsi, r300, r600, nouveau, freedreno,
     swrast, v3d, vc4, etnaviv, tegra, i915, svga, virgl, and
     swr.

   The DRI drivers available are 
     i915, i965, r100, r200, nouveau, and swrast.  
   The platforms available are 
     x11, wayland, drm, surfaceless, haiku, and android.
   
   Modify the commands
   below for any desired drivers.  The listed drivers below will cover most
   modern video cards.  For help in selecting drivers see <ulink
   url='http://www.mesa3d.org/systems.html'/>.</para>

<screen><userinput>GALLIUM_DRV="nouveau,radeonsi,svga,swrast"
DRI_DRIVERS="i915,i965,nouveau"
PLATFORMS="x11,wayland,drm"</userinput></screen>

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

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

meson --prefix=$XORG_PREFIX          \
      --sysconfdir=/etc              \
      -Dvalgrind=false               \
      -Dglx=dri                      \
      -Dosmesa=gallium               \
      -Dgallium-nine=true            \
      -Ddri-drivers=$DRI_DRIVERS     \
      -Dgallium-drivers=$GALLIUM_DRV \
      -Dplatforms=$PLATFORMS         \
      ..                             &amp;&amp;

unset GALLIUM_DRV DRI_DRIVERS PLATFORMS &amp;&amp;

ninja</userinput></screen>

    <para>
      If you have applied the xdemos patch, build the demo programs by
      running the following command:
    </para>

<screen><userinput>make -C ../xdemos DEMOS_PREFIX=$XORG_PREFIX LIBRARY_PATH=$PWD/src/glx</userinput></screen>
<!--
    <para>
      To test the results, issue: <command>make -k check</command>. 
    </para>
-->
    <para>
      This package does not come with a test suite.
    </para>

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

<screen role="root"><userinput>ninja install</userinput></screen>

    <para>
      If you have built the demo programs, install them by running the
      following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make -C ../xdemos DEMOS_PREFIX=$XORG_PREFIX 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"><userinput>install -v -dm755 /usr/share/doc/mesa-&mesa-version; &amp;&amp;
cp -rfv ../docs/* /usr/share/doc/mesa-&mesa-version;</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>
<!--
    <para>
      <parameter>CFLAGS="-O2" CXXFLAGS="-O2"</parameter>: By default,
      <application>Autoconf</application> sets CFLAGS and CXXFLAGS to
      "-g -O2". That results in binaries and libraries being built with
      debugging symbols which make them bigger. Override the default
      flags to omit the -g compiler flag so the final libraries are smaller.
    </para>

    <para>
      <parameter>LDFLAGS=-lLLVM</parameter>: This environment variable
      specifies the LLVM libraries that are not automatically included
      for some of the package components.
    </para>
-->
<!--
    <para>
      <parameter>- -enable-texture-float</parameter>: This switch enables
      floating-point textures and render buffers. Please consult
      <filename>docs/patents.txt</filename> to see if there are
      any legal issues if you use this feature.
    </para>
    Removed in 18.2.0
-->
<!--
    <para>
      <parameter>-Dosmesa=gallium</parameter>: This switch enables building
      the <filename class="libraryfile">libOSMesa</filename> library.
    </para>

    <para>
      <parameter>- -enable-xa</parameter>: This switch enables building the
      XA X Acceleration API (Required for VMware 3D Driver).
    </para>

    <para>
      <parameter>- -enable-gbm</parameter>: This switch enables building the
      <application>Mesa</application> Graphics Buffer Manager library.
    </para>

    <para>
      <parameter>- -enable-glx-tls</parameter>: This switch enables TLS (Thread Local
      Storage) support in GLX.
    </para>
-->
    <para>
      <parameter>-Dplatforms="..."</parameter>: This parameter
      controls which platforms EGL will be built for. Available
      platforms are drm, x11, surfaceless, haiku, android,  and wayland.
    </para>

    <para>
      <parameter>-Dgallium-drivers="..."</parameter>: This parameter
      controls which Gallium3D drivers should be built. Available drivers 
      are pl111, radeonsi, r300, r600, nouveau, and freedreno.
    </para>

    <para>
      <parameter>-Ddri-drivers="..."</parameter>: This parameter
      controls which platforms should be supported. Available platforms
      are i915, i965, r100, r200, nouveau, and swrast.
    </para>

    <para>
      <parameter>-Dvalgrind=false</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>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          glxgears and glxinfo
        </seg>
        <seg>
          <!-- Begin DRI drivers -->
          d3dadapter9.so, <!-- For Windows? This is DirectX's Direct3D -->
          i915_dri.so,
          i965_dri.so,
          kms_swrast_dri.so,
          nouveau_dri.so,
          nouveau_vieux_dri.so,
          radeonsi_dri.so,
          radeonsi_drv_video.so,
          swrast_dri.so,
          vmwgfx_dri.so
          <!-- End DRI Drivers -->
          libEGL.so,
          libGL.so,
          libGLESv1_CM.so,
          libGLESv2.so,
          libOSMesa.so,
          libXvMCnouveau.so,
          libgbm.so,
          libglapi.so,
          <!-- Begin Vulkan drivers -->
          libvulkan_intel.so,
          libvulkan_radeon.so,
          <!-- End Vulkan drivers -->
          libxatracker.so,
          <!-- Begin VDPAU drivers -->
          libvdpau_nouveau.so, and
          libvdpau_radeonsi.so
          <!-- End VDPAU drivers -->
        </seg>
        <seg>
          $XORG_PREFIX/{include/{EGL,GL,GLES,GLES2,GLES3,KHR,vulkan},lib/{d3d,dri,vdpau}}
          and
          /usr/share/doc/mesa-&mesa-version; (optional)
        </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>

      <varlistentry id="libOSMesa">
        <term><filename class="libraryfile">libOSMesa.so</filename></term>
        <listitem>
          <para>
            is the <application>Mesa</application> Off-screen Rendering library.
          </para>
          <indexterm zone="mesa libOSMesa">
            <primary sortas="c-libOSMesa">libOSMesa.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>