source: archive/weston.xml@ c339779

<?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 weston-download-http "http://wayland.freedesktop.org/releases/weston-&weston-version;.tar.xz">
  <!ENTITY weston-download-ftp  " ">
  <!ENTITY weston-md5sum        "310af6d7f8ba03c3418cec8ad72ea748">
  <!ENTITY weston-size          "1.2 MB">
  <!ENTITY weston-buildsize     "57 MB (with tests)">
  <!ENTITY weston-time          "0.5 SBU (with tests)">
]>

<sect1 id="weston" xreflabel="Weston-&weston-version;" revision="systemd">
  <?dbhtml filename="weston.html"?>

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

  <title>Weston-&weston-version;</title>

  <indexterm zone="weston">
    <primary sortas="a-Weston">Weston</primary>
  </indexterm>

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

    <para>
      <application>Weston</application> is the reference implementation of
      a <application>Wayland</application> compositor, and a useful
      compositor in its own right. It has various backends that lets it
      run on Linux kernel modesetting and evdev input as well as under X11.
      <application>Weston</application> also ships with a few example clients,
      from simple clients that demonstrate certain aspects of the protocol
      to more complete clients and a simplistic toolkit.
    </para>

    &lfs80_checked;

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

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

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="cairo"/>,
      <xref linkend="libinput"/>,
      <xref linkend="libjpeg"/>,
      <xref linkend="libxkbcommon"/>,
      <xref linkend="mesa"/> (built with
      <application>Wayland</application> support),
      <xref linkend="mtdev"/>,
      <xref linkend="wayland"/>, and
      <xref linkend="wayland-protocols"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="glu"/> (to build the screensaver client),
      <xref linkend="linux-pam"/> (to build the
      <command>weston-launch</command> utility),
      <xref linkend="pango"/> (to build some demo clients),
      <xref linkend="systemd"/>,
      <xref linkend="xorg7-lib"/> (to build the X11
      backend and X11 compatibility layer) and
      <xref linkend="xorg-server"/> (with Xwayland, runtime
      - for X11 backwards compatibility)
    </para>

    <note> 
      <para>
        The <command>weston-launch</command> utility is required if
        you want to run <application>Weston</application> as a
        non privileged user.
      </para>
    </note>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="colord"/>,
      <xref linkend="doxygen"/>,
      <xref linkend="lcms2"/>,
      <xref linkend="libpng"/>,
      <xref linkend="libva"/> (for H.264 VAAPI video encoding),
      <xref linkend="libwebp"/>,
      <ulink url="http://www.freerdp.com/">FreeRDP</ulink> and
      <ulink url="http://www.nongnu.org/libunwind/">libunwind</ulink>
    </para>

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

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

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

<screen><userinput>./configure --prefix=/usr --enable-demo-clients-install &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>make check</command>. The tests need
      to be run from an X Terminal or equivalent.
    </para>

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

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

  </sect2>

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

    <para>
      <parameter>--enable-demo-clients-install</parameter>: This switch
      enables the installation of the demo clients shipped with
      <application>Weston</application>.
    </para>

    <note>
      <para>
        Consult <command>./configure --help</command> output for switches needed
        to prevent <command>configure</command> from looking for some of the
        recommended dependencies.
      </para>
    </note>

  </sect2>

  <sect2 role="using">
    <title>Using Weston</title>

    <para>
      To start <application>Weston</application> as a X11 client,
      from an X terminal, run the following command:
    </para>

<screen><userinput>weston</userinput></screen>

    <para>
      To run it as a DRM compositor, from a TTY, while logged
      in as a normal user, run the following command:
    </para>

<screen><userinput>weston-launch</userinput></screen>

    <para>
      Note that <command>weston-launch</command> is a wrapper for
      <command>weston</command>. If you need to pass a parameter
      to <command>weston</command> while using
      <command>weston-launch</command>, use the following syntax:
    </para>

<screen><userinput>weston-launch -- --backend=fbdev-backend.so</userinput></screen>

    <para>
      Note the -- between the <command>weston-launch</command> and
      the <command>weston</command> parameter
      <parameter>--backend=fbdev-backend.so</parameter>. For list
      of parameters that you can pass to <command>weston</command>,
      consult the <command>weston(1)</command> manual page.
    </para>

    <para>
      To terminate <application>Weston</application> when running
      as a DRM compositor, use the CTRL+ALT+Backspace
      combination on your keyboard.
    </para>

    <para>
      Note that the default backend, DRM, will only run if a
      KMS driver is present on the system. It will not run in
      a virtual machine such as VBox or Qemu and on NVidia or
      AMD hardware with proprietary drivers. On these setups
      it would be possible to use the FBDEV backend by running
      the command described above.
    </para>

    <para>
      Also note that the X11 backend requires a working EGL stack.
      If you are running hardware that has no 3D support or
      no EGL stack, you can't run accelerated applications
      inside <application>Weston</application>. The latest
      proprietary NVidia driver has the necessary EGL
      stack needed to run <application>Weston</application>
      as an X11 client, but it is not officially supported.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Weston</title>

    <sect3 id="weston-config">
      <title>Config Files</title>
      <para>
        <filename>~/.config/weston.ini</filename>
      </para>

      <indexterm zone="weston weston-config">
        <primary sortas="e-AA.config-weston.ini">~/.config/weston.ini</primary>
      </indexterm>
    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>
        The <application>Weston</application> configuration file can be
        used to configure which modules will be loaded, keyboard
        layout, display resolution, touchpad behaviour, desktop shell
        appearance, etc.
      </para>

      <para>
        To change the keyboard layout inside <application>Weston</application>,
        add the following to your config file:
      </para>

<screen><literal>[keyboard]
keymap_model=pc105
keymap_layout=de
keymap_variant=euro
keymap_options=grp:alt_shift_toggle</literal></screen>

      <para>
        For an explanation of each of the mentioned options,
        consult the <command>xkeyboard-config(7)</command>
        manual page.
      </para>

      <para>
        To change the resolution of the compositor,
        add the following to your config file:
      </para>

<screen><literal>[output]
name=LVDS1
mode=1366x768</literal></screen>

      <para>
        The name can be one of the following:
      </para>

      <itemizedlist spacing="compact">
        <listitem>
          <para>
            DRM backend: LVDS1 (Laptop internal panel no.1)
          </para>
        </listitem>
        <listitem>
          <para>
            DRM backend: VGA1 (VGA connector no.1)
          </para>
        </listitem>
        <listitem>
          <para>
            X11 backend: X1 (X window no.1)
          </para>
        </listitem>
        <listitem>
          <para>
            Wayland backend: WL1 (Wayland window no.1)
          </para>
        </listitem>
      </itemizedlist>

      <para>
        For more information consult the
        <command>weston-drm(7)</command> manual page.
      </para>

      <para>
        To load a <application>Weston</application> module or a shell
        backend, add the following to your config file:
      </para>

<screen><literal>[core]
modules=xwayland.so
shell=desktop-shell.so</literal></screen>

      <para>
        Note that you need to load the <filename>xwayland.so</filename>
        module if you want to use X11 clients inside
        <application>Weston</application>.
      </para>

      <para>
        For a detailed list of configuration directives, consult the
        <command>weston.ini(5)</command> manual page or examine the
        <filename>weston.ini</filename> file inside the
        <application>Weston</application> source directory.
      </para>

    </sect3>

  </sect2>

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

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

      <seglistitem>
        <seg>
          wcap-decode, weston, weston-calibrator, weston-clickdot,
          weston-cliptest, weston-dnd, weston-editor, weston-eventdemo,
          weston-flower, weston-fullscreen, weston-image,
          weston-info, weston-launch, weston-multi-resource,
          weston-presentation-shm, weston-resizor, weston-scaler,
          weston-simple-damage, weston-simple-dmabuf-intel,
          weston-simple-dmabuf-v4l, weston-simple-egl, weston-simple-shm,
          weston-simple-touch, weston-smoke, weston-stacking,
          weston-subsurfaces, weston-terminal and weston-transformed
        </seg>
        <seg>
          libweston-1.so and libweston-desktop-1.so
        </seg>
        <seg>
          /usr/include/{libweston-1,weston}
          /usr/lib/{libweston-1,weston},
          /usr/share/wayland-sessions and
          /usr/share/weston
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="weston-prog">
        <term><command>weston</command></term>
        <listitem>
          <para>
            is the reference implementation of a Wayland server.
          </para>
          <indexterm zone="weston weston-prog">
            <primary sortas="b-weston">weston</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>