And one spelling correction. links -dump -width 75 ../wayland-web/building.html Thanks to evil_core for pointing out the need. --- README | 304 +++++++++++++++++++++++++++++++++++++++++++--------------------- 1 files changed, 206 insertions(+), 98 deletions(-)
diff --git a/README b/README index b8ad9b4..bec3b92 100644 --- a/README +++ b/README @@ -1,130 +1,238 @@ 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 through 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). - + (Copied from http://wayland.freedesktop.org/building.html which may + be more up to date.) -Modesetting + 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). -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. +Hardware / Drivers + X output requires DRI2. DRM output (without X) requires Kernel Mode + Setting (KMS) and the page flip ioctl. These are supported by: -Building mesa + 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. -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: + 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). - $ git clone git://anongit.freedesktop.org/mesa/mesa - $ cd mesa - $ ./configure --prefix=$HOME/install --enable-egl --enable-gles2 - $ make && make install + nVidia: Requires Nouveau (open source driver). DRM output requires a + kernel built from the Nouveau git repository, details below. Cards + probably work back to Riva TNT (1998). The latest series of chips, + NVC0 / Fermi, released March 2010, requires loading external firmware + for Nouveau, which is not documented. -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. +Setting up the environment + If you want to install in $HOME/install (or another location that + won't interfere with the rest of your system) you'll need to set the + following environment variables to get various libraries to link + appropriately: -libxkbcommon + LD_LIBRARY_PATH=$HOME/install/lib + PKG_CONFIG_PATH=$HOME/install/lib/pkgconfig/:$HOME/install/share/pkgconfig/ + ACLOCAL="aclocal -I $HOME/install/share/aclocal" + C_INCLUDE_PATH=$HOME/install/include + LIBRARY_PATH=$HOME/install/lib -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. + Do not set LD_LIBRARY_PATH as your default, it will break things. - $ git clone git://people.freedesktop.org/~krh/libxkbcommon.git - $ cd libxkbcommon/ - $ ./autogen.sh --prefix=$HOME/install - $ make && make install +Wayland libraries + Required to build Mesa with --with-egl-platforms=wayland,drm. -cairo-gl + $ git clone git://anongit.freedesktop.org/wayland/wayland + $ cd wayland + $ ./autogen.sh --prefix=$HOME/install + $ make + $ make install -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: +Mesa - $ git clone git://anongit.freedesktop.org/cairo - $ cd cairo - $ ./autogen.sh --prefix=$HOME/install --enable-gl - $ 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. You'll need to pull + it from git, because 7.10 does not include required commits related + to BGRA8888 and wayland-egl. For this you'll also need a development + package for libdrm. + $ git clone git://anongit.freedesktop.org/git/mesa/drm + $ cd drm + $ ./autogen.sh --prefix=$HOME/install --enable-nouveau-experimental-api + $ make && make install -Wayland + $ git clone git://anongit.freedesktop.org/mesa/mesa + $ cd mesa + $ ./autogen.sh --prefix=$HOME/install --enable-gles2 \ + --disable-gallium-egl --enable-gallium-nouveau --enable-gallium-r600 \ + --with-egl-platforms=wayland,drm + $ make && make install -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: + 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. - $ git clone git://people.freedesktop.org/~krh/wayland - $ ./autogen.sh --prefix=$HOME/install - $ make && make install +libxkbcommon -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 + Wayland needs libxkbcommon for translating evdev keycodes to keysyms. + For this you'll need development packages for xproto, kbproto, macros + and libX11. - $ sudo udevadm trigger --subsystem-match=drm --subsystem-match=input + $ git clone git://anongit.freedesktop.org/xorg/proto/xproto + $ cd xproto + $ ./autogen.sh --prefix=$HOME/install + $ make && make install -to make udev label the devices wayland will use. + $ git clone git://anongit.freedesktop.org/xorg/proto/kbproto + $ cd kbproto + $ ./autogen.sh --prefix=$HOME/install + $ make && make install -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: + $ git clone git://anongit.freedesktop.org/xorg/util/macros + $ cd macros + $ ./autogen.sh --prefix=$HOME/install + $ make && make install - $ ./wayland-system-compositor -b my-image.jpg + $ git clone git://anongit.freedesktop.org/xorg/lib/libX11 + $ cd libX11 + $ ./autogen.sh --prefix=$HOME/install + $ make && make install -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 + $ git clone git://people.freedesktop.org/xorg/lib/libxkbcommon.git + $ cd libxkbcommon/ + $ ./autogen.sh --prefix=$HOME/install --with-xkb-config-root=/usr/share/X11/xkb + $ make && make install - '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 +cairo-gl - 'view' does the same for pdf files, but needs file URIs - (file:///path/to/pdf) + 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. Unless your + distribution ships cairo with the gl backend enabled, you'll need to + compile your own version of cairo. For this you'll need a development + package for pixman. + + $ git clone git://anongit.freedesktop.org/pixman + $ cd pixman + $ ./autogen.sh --prefix=$HOME/install + $ make && make install + + $ git clone git://anongit.freedesktop.org/cairo + $ cd cairo + $ ./autogen.sh --prefix=$HOME/install --enable-gl --enable-xcb + $ make && make install + +Wayland applications + + Aside from mesa and libxkbcommon, the Wayland demos' dependencies can + be satisfied with released versions of: gdk-pixbuf-2.0, libudev 136, + libdrm 2.4.23, pixman-1, xcb-dri2, xcb-xfixes (for X compositor), + cairo-gl 1.10.0, glib-2.0, and gobject-2.0. And optionally, for the + pdf viewer: poppler-glib, gdk-2.0, and gio-2.0. + + $ git clone git://anongit.freedesktop.org/wayland/wayland-demos + $ cd wayland-demos + $ ./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 copied to /etc/udev/rules.d. + + $ sudo cp compositor/70-wayland.rules /etc/udev/rules.d/ + + Once installed, either reboot or run the following to make udev label + the devices wayland will use. + + $ sudo udevadm trigger --subsystem-match=drm --subsystem-match=input + + 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: + + $ ./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' 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) + +Notes + + Environment variables which will get you more debugging output: + + MESA_DEBUG=1 + EGL_LOG_LEVEL=debug + LIBGL_DEBUG=verbose + WAYLAND_DEBUG=1 + +Nouveau Kernel + + To use DRM output with nVidia, you need to build a kernel from the + Nouveau kernel git repository: + (required commit) + + $ git clone --depth 1 git://anongit.freedesktop.org/nouveau/linux-2.6 + $ cd linux-2.6 + $ cp /boot/config-`uname -r` .config # use .config of currently running kernel + $ yes "" | make oldconfig # use defaults for new options + $ make clean && make && make modules && sudo make modules_install && sudo make install + + Ubuntu Maverick's /sbin/installkernel is broken, requring these + additional commands: + + $ mkinitramfs -o initrd.img `make kernelversion`+ + $ sudo mv initrd.img /boot/initrd.img-`make kernelversion`+ + $ sudo update-grub + + To uninstall a kernel installed this way: + + $ sudo rm /boot/initrd.img-`make kernelversion`+ /lib/modules/`make kernelversion`+ + $ sudo update-grub -- 1.7.1 _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
