glfs/gnome/platform/mutter.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 mutter-download-http "&gnome-download-http;/mutter/&gnome-43;/mutter-&mutter-version;.tar.xz">
  <!ENTITY mutter-download-ftp  "&gnome-download-ftp;/mutter/&gnome-43;/mutter-&mutter-version;.tar.xz">
  <!ENTITY mutter-md5sum        "aba8f5170a27fe7d24f07a3b2fdf2725">
  <!ENTITY mutter-size          "2.7 MB">
  <!ENTITY mutter-buildsize     "151 MB (without tests)">
  <!ENTITY mutter-time          "0.6 SBU (Using parallelism=4)">
  <!ENTITY mutter-time-systemd  "0.6 SBU (Using parallelism=4, add 1.0 SBU for tests)">
]>

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


  <title>Mutter-&mutter-version;</title>

  <indexterm zone="mutter">
    <primary sortas="a-Mutter">Mutter</primary>
  </indexterm>

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

    <para>
      <application>Mutter</application> is the window manager for
      <application>GNOME</application>. It is not invoked directly,
      but from <application>GNOME Session</application> (on a
      machine with a hardware accelerated video driver).
    </para>

    &lfs113_checked;

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

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

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="gnome-settings-daemon"/>,
      <xref linkend="graphene"/>,
      <xref linkend="libxcvt"/>,
      <xref linkend="libxkbcommon"/>, and
      <xref linkend="pipewire"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="desktop-file-utils"/>,
      <xref linkend="gobject-introspection"/>,
      <xref linkend="startup-notification"/>, and
      <xref linkend="sysprof"/>
    </para>

    <bridgehead renderas="sect4">Recommended (Required to
    build the Wayland compositor)</bridgehead>
    <para role="recommended">
      <xref linkend="libinput"/>,
      <xref linkend="wayland"/>,
      <xref linkend="wayland-protocols"/>, and
      <xref linkend="xwayland"/>.
      Additionally, <xref linkend="gtk3"/> needs to be built with
      <application>Wayland</application> support.
    </para>

    <bridgehead renderas="sect4"
                revision="sysv">Recommended (Runtime)</bridgehead>
    <para role="recommended" revision="sysv">
      <xref linkend="blocaled" role="runtime"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="python-dbusmock"/> (required for tests),
      <xref linkend="xorg-server"/> (for X11 sessions)
    </para>

    <!-- NOTE: Mutter compiles git versions of COGL and Clutter for it's own
    internal use. This is because the wayland support upstream isn't advanced
    enough for the graphics stack used in Mutter. -->

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

  </sect2>

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

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

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

meson setup --prefix=/usr              \
            --buildtype=debugoptimized \
            -Dtests=false              \
            ..                         &amp;&amp;
ninja</userinput></screen>

<!--
    <para>
      To test the results, issue:
      <command>dbus-run-session ninja test</command>. The tests
      require an active X session to run correctly. It is not necessary to
      run a  separate D-bus session if not in a GNOME session, but it
      provides a clean environment in any case. One test,
      <filename>native-headless</filename>, is known to fail.
    </para>
    -->
    <!-- there are no added problems in sysv, AFAICT. Running the tests is
    not easy whatever the init system. But using the instructions below in
    a gnome session on sysv works (no test failure)...
    <para revision='sysv'>
       This package does not come with a test suite that runs properly in the
       SystemV environment.
    </para>
    -->

    <para>
      The test suite requires debug functions to be enabled in the build, and an
      external program called <command>xvfb-run</command>.  If you wish to run
      the tests, you should download and install it before running
      <command>meson</command>.

      You can obtain it from <ulink
      url="&sources-anduin-http;/mutter/xvfb-run">xvfb-run</ulink>, and install
      it with executable permissions in <filename
      class="directory">/usr/bin</filename>.  <command>xvfb-run</command> needs
      <command>Xvfb</command> at runtime, and <command>Xvfb</command> can be
      installed from either <xref linkend='xorg-server'/> or <xref
      linkend='xwayland'/>.

      You should also replace <parameter>-Dtests=false</parameter> in the
      <command>meson</command> command, with
      <parameter>-Dtests=true</parameter>.  The test
      suite requires the mutter schema to be installed on the system, so it is
      better to run the tests after installing the package.
    </para>

    <para>
      You can also test basic functions of <application>Mutter</application>
      following <xref linkend='mutter-starting'/>, after installing it.
    </para>

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

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

    <para>
      If you wish to run the tests, remove the reference to
      <application>Zenity</application> which is not a part of BLFS
      from one test:
    </para>

<screen role='test'><userinput>sed 's/zenity --[a-z]*/gtk3-demo/' -i ../src/tests/x11-test.sh</userinput></screen>

    <para>
      Now run the test suite:
    </para>

    <!-- Without "HOME=" one test can fail with certain monitor
         configuration in $HOME/.config/monitors.xml. -->
<screen role='test'><userinput>HOME= ninja test</userinput></screen>

    <para>
      The tests require an active X or wayland session.
      The <filename>native-unit</filename> test is known to fail.
      A lot of tests will fail if the opengl rendering is not done in hardware.
      Don't make any mouse or keyboard input while the test suite is
      running or some tests may fail.
    </para>
  </sect2>

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

    <!-- https://gitlab.gnome.org/GNOME/gnome-shell/-/issues/5512
         If debug is disabled, the "assertion 'CLUTTER_IS_ACTOR (self)'
         failed" message will turn into a crash.  Enabling debug is just a
         work around, it's not a proper fix.  -->
    <para>
      <parameter>--buildtype=debugoptimized</parameter>: Override the
      default buildtype (<quote>debug</quote>), which would produce
      unoptimized binaries.  It's used instead of
      <option>--buildtype=release</option> to work around an issue
      causing gnome-shell to crash.
    </para>
<!--
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/meson-buildtype-release.xml"/>
-->
    <para>
      <parameter>-Dtests=false</parameter>: Prevents building the tests,
      and removes a hard requirement on <command>xvfb-run</command>.
    </para>

    <para>
      <option>-Dprofiler=false</option>: Use this option if
      <application>Sysprof</application> is not installed, and you don't
      want meson to download <application>Sysprof</application> source
      code.
    </para>

  </sect2>

  <sect2 role="starting" id="mutter-starting">
    <title>Starting Mutter</title>

    <!-- Mutter as a Wayland compositor Works with mutter-42.4 and 43.0.
         IIRC mutter can also be used as a X window manager: just replace
         "twm" with "mutter &dash;&dash;x11" in xinitrc. But I've not tested
         such a configuration recently (I don't build Xorg Server or xinit
         these days.  -->

    <para>
      <application>Mutter</application> is normally used as a component of
      <application>gnome-shell</application>, but it can be used as a
      standalone Wayland compositor too.  To run
      <application>Mutter</application> as a Wayland compositor, in a
      virtual console, issue:
    </para>

    <screen role='nodump'><userinput>mutter --wayland -- vte-2.91</userinput></screen>

    <para>
      Replace <command>vte-2.91</command> with the command line for the
      first application you want in the Wayland session. Note that once this
      application exits, the Wayland session will be terminated.
    </para>

    <para>
      <application>Mutter</application> can also function as a nested
      compositor in another Wayland session.  In a terminal emulator, issue:
    </para>

    <screen role='nodump'><userinput>MUTTER_DEBUG_DUMMY_MODE_SPECS=1920x1080 mutter --wayland --nested -- vte-2.91</userinput></screen>

    <para>
      Replace <replaceable>1920x1080</replaceable> with the size you want
      for the nested Wayland session.
    </para>
  </sect2>

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

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

      <seglistitem>
        <seg>
          mutter
        </seg>
        <seg>
          libmutter-11.so
        </seg>
        <seg>
          /usr/{lib,include,libexec/installed-tests,share/{,installed-tests}}/mutter-11
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="mutter-prog">
        <term><command>mutter</command></term>
        <listitem>
          <para>
            is a <application>Clutter</application> based compositing
            <application>GTK+</application> Window Manager
          </para>
          <indexterm zone="mutter mutter-prog">
            <primary sortas="b-mutter">mutter</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libmutter">
        <term><filename class="libraryfile">libmutter-11.so</filename></term>
        <listitem>
          <para>
            contains the <application>Mutter</application> API functions
          </para>
          <indexterm zone="mutter libmutter">
            <primary sortas="c-libmutter">libmutter-11.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>