README

   1 What is Wayland
   2
   3 Wayland is a project to define a protocol for a compositor to talk to
   4 its clients as well as a library implementation of the protocol.  The
   5 compositor can be a standalone display server running on Linux kernel
   6 modesetting and evdev input devices, an X applications, or a wayland
   7 client itself.  The clients can be traditional appliactions, X servers
   8 (rootless or fullscreen) or other display servers.
   9
  10 The wayland protocol is essentially only about input handling and
  11 buffer management.  The compositor receives input events and forwards
  12 them to the relevant client.  The clients creates buffers and renders
  13 into them and notifies the compositor when it needs to redraw.  The
  14 protocol also handles drag and drop, selections, window management and
  15 other interactions that must go throught the compositor.  However, the
  16 protocol does not handle rendering, which is one of the features that
  17 makes wayland so simple.  All clients are expected to handle rendering
  18 themselves, typically through cairo or OpenGL.
  19
  20 The wayland repository includes a compositor and a few clients, but
  21 both the compositor and clients are essentially test cases.
  22
  23
  24 Building Instructions
  25
  26 The instructions below assume some familiarity with git and building
  27 and running experimental software.  And be prepared that this project
  28 isn't at all useful right now, it's still very much a prototype.  When
  29 the instructions suggest to clone a git repo, you can of course just
  30 add a remote and fetch instead, if you have a clone of that repo
  31 around already.  I usually install all software I'm working on into
  32 $HOME/install, so that's what I'll use in the instructions below, but
  33 you can use your favorite directory of course or install over your
  34 system copy (pass --prefix=/usr --sysconfdir=/etc, generally).
  35
  36
  37 Modesetting
  38
  39 At this point, kernel modesetting is upstream for Intel, AMD and
  40 nVidia chipsets.  Most distributions ship with kernel modesetting
  41 enabled by default and will work with Wayland out of the box.  The
  42 modesetting driver must also support the page flip ioctl, which only
  43 the intel driver does at this point.
  44
  45
  46 Building mesa
  47
  48 Wayland uses the mesa EGL stack, and all extensions required to run
  49 EGL on KMS are now upstream on the master branch.  The 7.9 release of
  50 mesa will have all these extensions, but for now you'll need to build
  51 mesa master:
  52
  53     $ git clone git://anongit.freedesktop.org/mesa/mesa
  54     $ cd mesa
  55     $ ./configure --prefix=$HOME/install  --enable-egl --enable-gles2
  56     $ make && make install
  57
  58 If you're using an intel chipset, it's best to also pass
  59 --disable-gallium to ./configure, since otherwise libEGL will try to
  60 load the gallium sw rasterizer before loading the Intel DRI driver.
  61
  62
  63 libxkbcommon
  64
  65 Wayland needs libxkbcommon for translating evdev keycodes to keysyms.
  66 There's a couple of repos around, and we're trying to consolidate the
  67 development, but for wayland you'll need the repo from my get
  68 repository.  For this you'll need development packages for xproto,
  69 kbproto and libX11.
  70
  71     $ git clone git://people.freedesktop.org/~krh/libxkbcommon.git
  72     $ cd libxkbcommon/
  73     $ ./autogen.sh --prefix=$HOME/install
  74     $ make && make install
  75
  76
  77 cairo-gl
  78
  79 The Waland clients render using cairo-gl, which is an experimental
  80 cairo backend.  It has been available since cairo 1.10.  Unless your
  81 distribution ships cairo with the gl backend enabled, you'll need to
  82 compile your own version of cairo:
  83
  84     $ git clone git://anongit.freedesktop.org/cairo
  85     $ cd cairo
  86     $ ./autogen.sh --prefix=$HOME/install --enable-gl
  87     $ make && make install
  88
  89
  90 Wayland
  91
  92 With mesa and libxkbcommon in place, we can checkout and build
  93 Wayland.  Aside from mesa, Wayland needs development packages for
  94 gdk-pixbuf-2.0, libudev, libdrm, xcb-dri2, xcb-fixes (for X
  95 compositor) cairo-gl, glib-2.0, gdk-2.0 (for poppler) and
  96 poppler-glib:
  97
  98     $ git clone git://people.freedesktop.org/~krh/wayland
  99     $ aclocal; autoconf; ./configure --prefix=$HOME/install
 100     $ make && make install
 101
 102 Installing into a non-/usr prefix is fine, but the 70-wayland.rules
 103 udev rule file has to be installed in /etc/udev/rules.d.  Once
 104 installed, either reboot or run
 105
 106     $ sudo udevadm trigger --subsystem-match=drm --subsystem-match=input
 107
 108 to make udev label the devices wayland will use.
 109
 110 If DISPLAY is set, the wayland compositor will run under X in a window
 111 and take input from X.  Otherwise it will run on the KMS framebuffer
 112 and take input from evdev devices.  Pick a background image that you
 113 like and copy it to the Wayland source directory as background.jpg or
 114 use the -b command line option:
 115
 116     $ ./wayland-system-compositor -b my-image.jpg
 117
 118 To run clients, switch to a different VT and run the client from
 119 there.  Or run it under X and start up the clients from a terminal
 120 window.  There are a few demo clients available, but they are all
 121 pretty simple and mostly for testing specific features in the wayland
 122 protocol: 'terminal' is a simple terminal emulator, not very compliant
 123 at all, but works well enough for bash
 124
 125     'flower' moves a flower around the screen, testing the frame protocol
 126     'gears' glxgears, but for wayland, currently broken
 127     'image' loads the image files passed on the command line and shows them
 128
 129     'view' does the same for pdf files, but needs file URIs
 130     (file:///path/to/pdf)