source: gnome/platform/mutter.xml@ 920e139

<?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-44;/mutter-&mutter-version;.tar.xz">
  <!ENTITY mutter-download-ftp  "&gnome-download-ftp;/mutter/&gnome-44;/mutter-&mutter-version;.tar.xz">
  <!ENTITY mutter-md5sum        "985f14046cbff834f5f7ba4e1bce4bad">
  <!ENTITY mutter-size          "2.7 MB">
  <!ENTITY mutter-buildsize     "99 MB (with tests)">
  <!ENTITY mutter-time          "0.6 SBU (Using parallelism=4; add 1.4 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>

    &lfs120_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>
        <para>
          Estimated build time: &mutter-time;
        </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"/>, and
      <xref linkend="startup-notification"/>
    </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"/>
    </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="sysprof"/>,-->
      <xref linkend="xorg-server"/> (for X11 sessions), and
      <ulink url="&sysprof-url;">sysprof</ulink>
    </para>

    <!-- NOTE: Mutter compiles shipped Cogl and Clutter for it's own
    internal use. This is because upstream have decided that Cogl and
    Clutter should be only used by Mutter in the future, so the development
    of Cogl and Clutter is now performed in the Mutter repository.  The
    "standalone" Cogl and Clutter are considered obsolete now and we have
    archived them.  -->

  </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=release        \
            -Dtests=false              \
            -Dprofiler=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 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 -Dclutter_tests=false</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]*/gtk4-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.
      Two tests named
      <!-- https://gitlab.gnome.org/GNOME/mutter/-/issues/2848 -->
      <filename>cogl-test-framebuffer-get-bits-gl3</filename> and
      <!-- This needs a pipewire daemon running.  As at Aug 2023
           the method to run a pipewire daemon is not in BLFS
           (but in editor notes), so claim this a known failure.  -->
      <filename>native-unit</filename> are known to fail.
      A few other tests may fail depending on the configuration.
      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>

    <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>
      <parameter>-Dprofiler=false</parameter>: Allow building this package
      without <application>Sysprof</application>.  Remove this option if
      you've installed <application>Sysprof</application> and want to
      analysis the rendering performance of
      <application>Mutter</application>.
    </para>

    <para>
      <option>-Dtests=true -Dclutter_tests=false</option>: Building all the
      tests but the tests for the shipped <application>Clutter</application>
      library.  The <application>Clutter</application> tests are known to
      fail with <option>--buildtype=release</option>.
    </para>

  </sect2>

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

    <!-- Mutter as a Wayland compositor works with recent mutter releases.
         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-12.so and libmutter-test-12.so (optional)
        </seg>
        <seg>
          /usr/{lib,include,libexec/installed-tests,share/{,installed-tests}}/mutter-12
        </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-12.so</filename></term>
        <listitem>
          <para>
            contains the <application>Mutter</application> API functions
          </para>
          <indexterm zone="mutter libmutter">
            <primary sortas="c-libmutter">libmutter-12.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libmutter-test">
        <term><filename class="libraryfile">libmutter-test-12.so</filename></term>
        <listitem>
          <para>
            contains the <application>Mutter</application> test suite API
            functions; this library is only installed if the test suite of
            this package is enabled and it is needed by
            <application>gnome-shell</application> test suite
          </para>
          <indexterm zone="mutter libmutter-test">
            <primary sortas="c-libmutter-test">libmutter-test-12.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>