source: x/lib/libdrm.xml@ e917814

<?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 libdrm-download-http "https://dri.freedesktop.org/libdrm/libdrm-&libdrm-version;.tar.xz">
  <!ENTITY libdrm-download-ftp  " ">
  <!ENTITY libdrm-md5sum        "5403981a20c964f4c893ff91393652bd">
  <!ENTITY libdrm-size          "459 KB">
  <!ENTITY libdrm-buildsize     "8.6 MB (with tests)">
  <!ENTITY libdrm-time          "less than 0.1 SBU (with tests) with parallelism=4">
  <!-- With version 2.4.102, the tests add 1 second to my build. -->
  <!-- The 'threaded' test adds about 15 seconds if you're on an NVIDIA system
       due to it directly interacting with the GPU. -->
]>

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


  <title>Libdrm-&libdrm-version;</title>

  <indexterm zone="libdrm">
    <primary sortas="a-libdrm">libdrm</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Libdrm</title>

    <para>
      <application>Libdrm</application> provides a userspace library for
      accessing the direct rendering manager (DRM) on operating systems that
      support the ioctl interface. Libdrm is a low-level library, typically used
      by graphics drivers such as the Mesa DRI drivers, the X drivers, libva and
      similar projects.
    </para>

    &lfs113_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&libdrm-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&libdrm-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &libdrm-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &libdrm-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &libdrm-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &libdrm-time;
        </para>
      </listitem>
    </itemizedlist>

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

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="xorg7-lib"/> (for Intel KMS API support required by Mesa)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="cairo"/> (for tests),
      <xref linkend="cmake"/> (could be used to find dependencies without pkgconfig files),
      <xref linkend="DocBook"/>,
      <xref linkend="docbook-xsl"/>,
      <xref linkend="docutils"/>, and
      <xref linkend="libxslt"/> (to build manual pages),
      <xref linkend="libatomic_ops"/> (required by architectures without native atomic operations),
      <xref linkend="valgrind"/>, and
      <ulink url="https://cunit.sourceforge.net/">CUnit</ulink> (for AMDGPU tests)
    </para>

  </sect2>

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

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

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

meson setup --prefix=$XORG_PREFIX \
            --buildtype=release   \
            -Dudev=true           \
            -Dvalgrind=disabled   \
            ..                    &amp;&amp;
ninja</userinput></screen>

    <para>
      To check the results, issue <command>ninja test</command>. <!--One test,
      'threaded' in the nouveau subdirectory, is known to fail with a
      30 second timeout.-->
      <!-- Regarding the 'threaded' test, it's now skipped by default (2.4.102)
           -renodr -->

      <!-- Tests may hang
      for unknown reasons. --><!-- If nouveau threaded test hangs, you can disable it
      with
      <command>sed -i 's/^TESTS/#&amp;/' tests/nouveau/Makefile.in</command>.

      Now that tests are run with ninja, the test merely times out after 30 seconds.
      -->
    </para>

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

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

  </sect2>

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

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/meson-buildtype-release.xml"/>

    <para>
      <parameter>-Dudev=true</parameter>: This parameter enables support for using
      <application>Udev</application> instead of <command>mknod</command>.
    </para>

    <para>
      <parameter>-Dvalgrind=disabled</parameter>: This parameter disables
      building libdrm with valgrind support. This fixes building sysprof and
      other packages that use libdrm. Change this parameter to "enabled"
      (or remove it) if you need support for valgrind.
    </para>

  </sect2>

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

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

      <seglistitem>
        <seg>
          None
        </seg>
        <seg>
          libdrm_amdgpu.so, libdrm_intel.so, libdrm_nouveau.so,
          libdrm_radeon.so, and libdrm.so<!--, and libkms.so-->
        </seg>
        <seg>
           /usr/include/libdrm <!--,/usr/include/libkms,-->
           and /usr/share/libdrm
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="libdrm_amdgpu">
        <term><filename class="libraryfile">libdrm_amdgpu.so</filename></term>
        <listitem>
          <para>
            contains the AMDGPU specific Direct Rendering Manager functions
          </para>
          <indexterm zone="libdrm libdrm_amdgpu">
            <primary sortas="c-libdrm_amdgpu">libdrm_amdgpu.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libdrm_intel">
        <term><filename class="libraryfile">libdrm_intel.so</filename></term>
        <listitem>
          <para>
            contains the Intel specific Direct Rendering Manager
            functions
          </para>
          <indexterm zone="libdrm libdrm_intel">
            <primary sortas="c-libdrm_intel">libdrm_intel.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libdrm_nouveau">
        <term><filename class="libraryfile">libdrm_nouveau.so</filename></term>
        <listitem>
          <para>
            contains the open source nVidia (Nouveau) specific Direct
            Rendering Manager functions
          </para>
          <indexterm zone="libdrm libdrm_nouveau">
            <primary sortas="c-libdrm_nouveau">libdrm_nouveau.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libdrm_radeon">
        <term><filename class="libraryfile">libdrm_radeon.so</filename></term>
        <listitem>
          <para>
            contains the AMD Radeon specific Direct Rendering Manager
            functions
          </para>
          <indexterm zone="libdrm libdrm_radeon">
            <primary sortas="c-libdrm_radeon">libdrm_radeon.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libdrm-lib">
        <term><filename class="libraryfile">libdrm.so</filename></term>
        <listitem>
          <para>
            contains the Direct Rendering Manager API functions
          </para>
          <indexterm zone="libdrm libdrm-lib">
            <primary sortas="c-libdrm">libdrm.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <!-- Removed in 2.4.111
      <varlistentry id="libkms">
        <term><filename class="libraryfile">libkms.so</filename></term>
        <listitem>
          <para>
            contains API functions for kernel mode setting abstraction
          </para>
          <indexterm zone="libdrm libkms">
            <primary sortas="c-libkms">libkms.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>
      -->

    </variablelist>

  </sect2>

</sect1>