From 7261fb3bc9de2240f7e18590e635b538b7c157ee Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Sat, 5 May 2012 00:41:48 +0200 Subject: [PATCH] Update README to latest build instructions Update README to contain the latest build instructions from wayland-web. --- README | 298 ++++++++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 196 insertions(+), 102 deletions(-) diff --git a/README b/README index b8ad9b4..f254db6 100644 --- a/README +++ b/README @@ -1,130 +1,224 @@ What is Wayland -Wayland is a project to define a protocol for a compositor to talk to -its clients as well as a library implementation of the protocol. The -compositor can be a standalone display server running on Linux kernel -modesetting and evdev input devices, an X applications, or a wayland -client itself. The clients can be traditional applications, X servers -(rootless or fullscreen) or other display servers. - -The wayland protocol is essentially only about input handling and -buffer management. The compositor receives input events and forwards -them to the relevant client. The clients creates buffers and renders -into them and notifies the compositor when it needs to redraw. The -protocol also handles drag and drop, selections, window management and -other interactions that must go throught the compositor. However, the -protocol does not handle rendering, which is one of the features that -makes wayland so simple. All clients are expected to handle rendering -themselves, typically through cairo or OpenGL. - -The wayland repository includes a compositor and a few clients, but -both the compositor and clients are essentially test cases. + Wayland is a project to define a protocol for a compositor to talk to + its clients as well as a library implementation of the protocol. The + compositor can be a standalone display server running on Linux kernel + modesetting and evdev input devices, an X applications, or a wayland + client itself. The clients can be traditional applications, X servers + (rootless or fullscreen) or other display servers. + + The wayland protocol is essentially only about input handling and + buffer management. The compositor receives input events and forwards + them to the relevant client. The clients creates buffers and renders + into them and notifies the compositor when it needs to redraw. The + protocol also handles drag and drop, selections, window management and + other interactions that must go throught the compositor. However, the + protocol does not handle rendering, which is one of the features that + makes wayland so simple. All clients are expected to handle rendering + themselves, typically through cairo or OpenGL. + + The wayland repository includes a compositor and a few clients, but + both the compositor and clients are essentially test cases. Building Instructions -The instructions below assume some familiarity with git and building -and running experimental software. And be prepared that this project -isn't at all useful right now, it's still very much a prototype. When -the instructions suggest to clone a git repo, you can of course just -add a remote and fetch instead, if you have a clone of that repo -around already. I usually install all software I'm working on into -$HOME/install, so that's what I'll use in the instructions below, but -you can use your favorite directory of course or install over your -system copy (pass --prefix=/usr --sysconfdir=/etc, generally). - - -Modesetting - -At this point, kernel modesetting is upstream for Intel, AMD and -nVidia chipsets. Most distributions ship with kernel modesetting -enabled by default and will work with Wayland out of the box. The -modesetting driver must also support the page flip ioctl, which only -the intel driver does at this point. + The instructions below assume some familiarity with git and building + and running experimental software. And be prepared that this project + isn't at all useful right now, it's still very much a prototype. When + the instructions suggest to clone a git repo, you can of course just + add a remote and fetch instead, if you have a clone of that repo around + already. By default the software is installed in $HOME/install but you + can change it by altering $WLD (explained later). You can also install + everything system wide by setting WLD to /usr and passing + --sysconfdir=/etc to autogen.sh. + +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 2.6.37 for nv40 or lower cards, 2.6.38 for nv50 cards. + Some new cards require [2]loading external firmware. + +Setting up the environment + + If you want to install in a custom location (not system wide), you'll + need to set the following environment variables to get various + libraries to link appropriately: +WLD=$HOME/install # change this to another location if you prefer +LD_LIBRARY_PATH=$WLD/lib +PKG_CONFIG_PATH=$WLD/lib/pkgconfig/:$WLD/share/pkgconfig/ +ACLOCAL="aclocal -I $WLD/share/aclocal" + +export WLD 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. + +Wayland libraries + + This is required in order to be able to build Mesa with + --with-egl-platforms=x11,wayland,drm. + $ git clone git://anongit.freedesktop.org/wayland/wayland + $ cd wayland + $ ./autogen.sh --prefix=$WLD + $ make + $ make install + +Mesa + + Wayland uses the mesa EGL stack, and all extensions required to run EGL + on KMS are now upstream on the master branch. Wayland master requires + mesa master. Wayland 0.85 works with mesa branch 8.0 and master. For + this you'll also need a development package for libdrm. Other + dependencies are development packages of xcb-dri2 and xcb-xfixes. + $ git clone git://anongit.freedesktop.org/git/mesa/drm + $ cd drm + $ ./autogen.sh --prefix=$WLD --enable-nouveau-experimental-api + $ make && make install + $ git clone git://anongit.freedesktop.org/git/xorg/util/macros + $ cd macros + $ ./autogen.sh --prefix=$WLD + $ make && make install -Building mesa + $ git clone git://anongit.freedesktop.org/xorg/proto/glproto + $ cd glproto + $ ./autogen.sh --prefix=$WLD + $ make && make install -Wayland uses the mesa EGL stack, and all extensions required to run -EGL on KMS are now upstream on the master branch. The 7.9 release of -mesa will have all these extensions, but for now you'll need to build -mesa master: + $ git clone git://anongit.freedesktop.org/xorg/proto/dri2proto + $ cd dri2proto + $ ./autogen.sh --prefix=$WLD + $ make && make install $ git clone git://anongit.freedesktop.org/mesa/mesa $ cd mesa - $ ./configure --prefix=$HOME/install --enable-egl --enable-gles2 + $ ./autogen.sh --prefix=$WLD --enable-gles2 --disable-gallium-egl \ + --with-egl-platforms=x11,wayland,drm --enable-gbm --enable-shared-glapi \ + --with-gallium-drivers=r300,r600,swrast,nouveau $ make && make install -If you're using an intel chipset, it's best to also pass ---disable-gallium to ./configure, since otherwise libEGL will try to -load the gallium sw rasterizer before loading the Intel DRI driver. - + We disable Gallium for Intel 915 and 965, which just means that libEGL + won't try to load the Gallium drivers directly. The Gallium drivers + will be built as DRI drivers, which the EGL loader will load just fine. libxkbcommon -Wayland needs libxkbcommon for translating evdev keycodes to keysyms. -There's a couple of repos around, and we're trying to consolidate the -development, but for wayland you'll need the repo from my git -repository. For this you'll need development packages for xproto, -kbproto and libX11. + Wayland needs libxkbcommon for translating evdev keycodes to keysyms. + For wayland 0.85 use libxkbcommon branch for-weston-0.85. For this + you'll need development packages for xproto, kbproto, macros and + libX11. + $ git clone git://anongit.freedesktop.org/xorg/proto/xproto + $ cd xproto + $ ./autogen.sh --prefix=$WLD + $ make && make install - $ git clone git://people.freedesktop.org/~krh/libxkbcommon.git - $ cd libxkbcommon/ - $ ./autogen.sh --prefix=$HOME/install + $ git clone git://anongit.freedesktop.org/xorg/proto/kbproto + $ cd kbproto + $ ./autogen.sh --prefix=$WLD $ make && make install + $ git clone git://anongit.freedesktop.org/xorg/lib/libX11 + $ cd libX11 + $ ./autogen.sh --prefix=$WLD + $ make && make install + + $ git clone git://people.freedesktop.org/xorg/lib/libxkbcommon.git + $ cd libxkbcommon/ + $ ./autogen.sh --prefix=$WLD --with-xkb-config-root=/usr/share/X11/xkb + $ make && make install cairo-gl -The Wayland clients render using cairo-gl, which is an experimental -cairo backend. It has been available since cairo 1.10. Unless your -distribution ships cairo with the gl backend enabled, you'll need to -compile your own version of cairo: + The Wayland clients can render using cairo-gl, but fall back to + software when cairo-gl is not available. cairo-gl is an experimental + cairo backend and has been available since cairo 1.10, but recent + bugfixes (available in non-released 1.11.3) are needed. Thus cairo from + git is required. For this you'll need a development package for pixman. + $ git clone git://anongit.freedesktop.org/pixman + $ cd pixman + $ ./autogen.sh --prefix=$WLD + $ make && make install $ git clone git://anongit.freedesktop.org/cairo $ cd cairo - $ ./autogen.sh --prefix=$HOME/install --enable-gl + $ ./autogen.sh --prefix=$WLD --enable-gl --enable-xcb $ make && make install - -Wayland - -With mesa and libxkbcommon in place, we can checkout and build -Wayland. Aside from mesa, Wayland needs development packages for -gdk-pixbuf-2.0, libudev, libdrm, xcb-dri2, xcb-fixes (for X -compositor) cairo-gl, glib-2.0, gdk-2.0 (for poppler) and -poppler-glib: - - $ git clone git://people.freedesktop.org/~krh/wayland - $ ./autogen.sh --prefix=$HOME/install - $ make && make install - -Installing into a non-/usr prefix is fine, but the 70-wayland.rules -udev rule file has to be installed in /etc/udev/rules.d. Once -installed, either reboot or run - - $ sudo udevadm trigger --subsystem-match=drm --subsystem-match=input - -to make udev label the devices wayland will use. - -If DISPLAY is set, the wayland compositor will run under X in a window -and take input from X. Otherwise it will run on the KMS framebuffer -and take input from evdev devices. Pick a background image that you -like and copy it to the Wayland source directory as background.jpg or -use the -b command line option: - - $ ./wayland-system-compositor -b my-image.jpg - -To run clients, switch to a different VT and run the client from -there. Or run it under X and start up the clients from a terminal -window. There are a few demo clients available, but they are all -pretty simple and mostly for testing specific features in the wayland -protocol: 'terminal' is a simple terminal emulator, not very compliant -at all, but works well enough for bash - - 'flower' moves a flower around the screen, testing the frame protocol - 'gears' glxgears, but for wayland, currently broken - 'image' loads the image files passed on the command line and shows them - - 'view' does the same for pdf files, but needs file URIs - (file:///path/to/pdf) +Weston and demo applications + + Weston is the reference implementation of a Wayland compositor. It's + available in the weston repo and comes with a few demo applications. + + Aside from mesa and libxkbcommon, the Weston 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 git://anongit.freedesktop.org/wayland/weston + $ cd weston + $ ./autogen.sh --prefix=$WLD + $ make + $ make install + + If DISPLAY is set, the weston will run under X in a window and take + input from X. Otherwise it will run on the KMS framebuffer and take + input from evdev devices. Copy the weston-deskop-shell.ini config file + to ~/.config and edit it to set a background image that you like. The + run the compositor by typing + $ ./weston + + For KMS/DRM output weston needs root permissions. You can accomplish + this by making weston SUID root (sudo chown root weston; sudo chmod +s + weston) or, with weston master, using weston-launch, which also + requires SUID root. You will also need to grant yourself permissions to + use it, which it will recommend when run. + $ sudo chown root weston-launch + $ sudo chmod +s weston-launch + $ ./weston-launch + + To run clients, switch to a different VT and run the client from there. + Or run it under X and start up the clients from a terminal window. + There are a few demo clients available, but they are all pretty simple + and mostly for testing specific features in the wayland protocol: + * 'terminal' is a simple terminal emulator, not very compliant at + all, but works well enough for bash + * 'flower' draws a flower on the screen, testing the frame protocol + * 'gears' glxgears, but for wayland + * 'smoke' tests SHM buffer sharing + * 'image' loads the image files passed on the command line and shows + them + * 'view' does the same for pdf files + * 'resizor' demonstrates smooth window resizing (use up and down + keys) + * 'eventdemo' reports libtoytoolkit's events to console (see + eventdemo --help) + +XWayland + + [3]Directions for building support for X clients (XWayland). + +Notes + + Environment variables which will get you more debugging output: +MESA_DEBUG=1 +EGL_LOG_LEVEL=debug +LIBGL_DEBUG=verbose +WAYLAND_DEBUG=1 + +References + + 1. http://wayland.freedesktop.org/ + 2. http://nouveau.freedesktop.org/wiki/InstallDRM#Firmware + 3. http://wayland.freedesktop.org/xserver.html -- 1.7.10