This guide explains how to build and run the norwood wayland compositor. The latest code is housed in git. For testing purposes, it is recommended to use a nonstandard prefix for installation of all components. The instructions assume some familiarity with git and using experimental software. If you need git help, see the Tips section. You can optionally install everything system-wide by setting the prefix to /usr and passing –sysconfdir=/etc to autogen.sh though this is not recommended for testing purposes.
Backends
There are several backends for weston. The backend that is possibly most useful for development is the x11 backend. This allows you to run weston as an X11 window inside of your current X session. The ultimate desired backend for weston on the desktop is the drm backend. This allows us to use the graphics drivers in a way that will not allow tearing if used correctly. Other backends include rpi for raspberry pi, an fbdev backend for framebuffer, a wayland backend for running nested compositor instances and a headless backend for certain tests. There is also a new rdp backend included in norwood now ready for testing. For building Weston for Raspberry Pi, see Raspberry Pi build guide.
Hardware / Drivers
X output requires DRI2. DRM output (without X) requires Kernel Mode Setting (KMS) and the page flip ioctl. These are supported by:
Intel: i915 (June 2004) or newer cards. DRM support has been in the kernel since around 2.6.29. Sandy Bridge chips require kernel 2.6.37.
AMD/ATI: Requires open source driver (radeon/ati, not fglrx/catalyst). DRM output requires kernel version 2.6.38. Cards probably work back to Radeon 7200 (2000).
nVidia: Requires Nouveau (open source driver). DRM output requires kernel version 3.7-rc3. DRM output previously required kernel version 2.6.37 for nv40 or lower cards, 2.6.38 for nv50 cards. Some new cards require loading external firmware.
Setting up the environment
Installing to a custom location
If you do not want to install system wide, you’ll need to set the following environment variables to get various libraries to link appropriately:
prefix=$HOME/install # change this to another location if you prefer LD_LIBRARY_PATH=$prefix/lib PKG_CONFIG_PATH=$prefix/lib/pkgconfig/:$prefix/share/pkgconfig/ ACLOCAL="aclocal -I $prefix/share/aclocal" export prefix LD_LIBRARY_PATH PKG_CONFIG_PATH ACLOCAL
Do not set LD_LIBRARY_PATH as your default, it will break things.
You may put the above in a script and source it in the terminal you wish to build the packages.
Installing system wide
Installing to a global prefix used by the system (i.e. /usr) is not recommended as this is experimental software and may potentially break any number of system components. This guide provides everything you need to create a disposable installation that will not affect your operating system installation.
Northfield
$ git clone https://github.com/soreau/northfield.git
$ cd northfield
$ ./autogen.sh --prefix=$prefix
$ make
$ make install
Mesa
Norwood uses the mesa EGL stack, and all extensions required to run EGL on KMS are now upstream in the official master branch. Northfield does not require mesa master, but it is recommended to test it regularly as it changes daily. In the case that mesa is broken, try the next branch of the github repository. Efforts will be made to keep a last-known-working snapshot here https://github.com/soreau/mesa By default, please use mesa master.
$ git clone git://anongit.freedesktop.org/git/mesa/drm
$ cd drm
$ ./autogen.sh --prefix=$prefix
$ make && make install
$ git clone git://anongit.freedesktop.org/mesa/mesa
$ cd mesa
$ ./autogen.sh --prefix=$prefix --enable-gles2 --disable-gallium-egl
--with-egl-platforms=x11,wayland,drm --enable-gbm --enable-shared-glapi
--with-gallium-drivers=r300,r600,nouveau,swrast
$ make && make install
Libxkbcommon
Northfield requires libxkbcommon for keyboard input.
$ git clone git://people.freedesktop.org/xorg/lib/libxkbcommon.git
$ cd libxkbcommon/
$ ./autogen.sh --prefix=$prefix --with-xkb-config-root=/usr/share/X11/xkb
$ make && make install
Cairo
Northfield clients can using any method they choose to paint their surfaces. One popular option is to use cairo. This is what the Norwood demo clients use and thus is a dependency.
$ git clone git://anongit.freedesktop.org/pixman
$ cd pixman
$ ./autogen.sh --prefix=$prefix
$ make && make install
$ git clone git://anongit.freedesktop.org/cairo
$ cd cairo
$ ./autogen.sh --prefix=$prefix --enable-gl --enable-xcb
$ make && make install
Norwood
Norwood is the reference implementation of a Northfield compositor. It is available in the Norwood repository with a few demo applications. Norwood is was forked from weston and the binary name will remain the same.
Aside from mesa and libxkbcommon, Norwood dependencies can be satisfied with released versions of: gdk-pixbuf-2.0, libudev 136, libdrm 2.4.23, pixman-1, cairo-gl 1.11.3, glib-2.0, and gobject-2.0. And optionally, for the pdf viewer: poppler-glib and gio-2.0.
$ git clone https://github.com/soreau/norwood.git
$ cd norwood
$ ./autogen.sh --prefix=$prefix
$ make
$ make install
If DISPLAY is set, the weston will run under X in a window and take input from X. Otherwise, a different backend must be used for output such as drm for example. Copy the weston.ini config file to ~/.config and edit it to set a png image that you like. Then run the compositor by typing:
$ ./weston
KMS/DRM output should be handled with weston-launch. This requires elivated privileges which are set if “make install” is run as root. It also requires that you enable systemd session support for weston-launch (by using systemd and having the systemd-login devel headers at configure time) or add yourself to the “weston-launch” group:
$ sudo groupadd weston-launch
$ sudo usermod -a -G weston-launch $USER
$ # Log all the way out (of X, etc.)
$ sudo chown root weston-launch
$ sudo chmod +s weston-launch
$ weston-launch
XWayland
Directions for building support for X clients (XWayland)
Environment Variables
Debug:
MESA_DEBUG=1 EGL_LOG_LEVEL=debug LIBGL_DEBUG=verbose WAYLAND_DEBUG=1
XDG_RUNTIME_DIR
Weston creates its unix socket file (for example, wayland-0) in the directory specified by the required environment variable XDG_RUNTIME_DIR . Clients use the same variable to find that socket. If you are using a distro that does not set XDG_RUNTIME_DIR for you, do:
$ mkdir /tmp/xdg_runtime_dir
$ chmod 0700 /tmp/xdg_runtime_dir
$ su -c 'echo XDG_RUNTIME_DIR=/tmp/xdg_runtime_dir >> /etc/environment'
Coding style
Git tips
Patch creation/submission