[PATCH wayland-web] Added depencies and bug fixes to build instructions

Mon May 19 00:39:54 PDT 2014

On Fri, 16 May 2014 13:43:50 -0700
spitzak at gmail.com wrote:

> From: spitzak <spitzak at gmail.com>
> 
> This is based on several experimental runs on two different
> Ubuntu 12.04 machines. Latest version includes instructions for
> a recent update of Mesa (which requires llvm-3.1) and that you
> must compile Cairo to avoid bugs in the system-supplied version.

Hi,

This is v3 of the same patch, right?
Please mention that, so no-one goes reviewing the outdated versions,
especially when it's this long.

General comments:

- Drop all the re-line-wrapping that does not actually change the
  content. It just makes this patch daunting to review.

- I think we should keep the main building page distribution agnostic.
  Otherwise it would be specific to Fedora rawhide or latest release or
  something, since Fedora is what many main developers use, IIRC (not
  me, though). Certainly choosing an ancient distribution like Ubuntu
  12.04 is far too old to be considered in detail on or as the base of
  the main building page. The same goes for the xserver page.

I suppose you could make a sub-page for Ubuntu specifics, but I think
it might be better on some ubuntu-specific wiki where end users can
update it easily. We could still link there.

> ---
>  building.html |  378 ++++++++++++++++++++++++++++++++++++---------------------
>  wayland.css   |    1 +
>  xserver.html  |  173 +++++++++++++++++---------
>  3 files changed, 355 insertions(+), 197 deletions(-)
> 
> diff --git a/building.html b/building.html
> index 04c2c8b..9c42bed 100644
> --- a/building.html
> +++ b/building.html
> @@ -11,34 +11,41 @@
>  <h1><a href="/"><img src="wayland.png" alt="Wayland logo"></a></h1>
>  
>  <p>The instructions below assume some familiarity with git and
> -building and running experimental software.  Also, be prepared for the fact that this
> -project is 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.</p>
> +building and running experimental software.  Also, be prepared for the
> +fact that this project is 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.</p>
> +

> +<p>These instructions have been tested on a stock Ubuntu 12.04 LTS,
> +and should work on Debian and any other apt systems.</p>

I bet the next person fixing these instructions will not be on Ubuntu
12.04, so better drop this, or it gets outdated quick when the person
forgets to remove this.

>  
>  <h2>Hardware / Drivers</h2>
>  
> -<p>X output requires DRI2.  DRM output (without X) requires Kernel Mode
> -Setting (KMS) and the page flip ioctl.  These are supported by:</p>
> +<p>X output requires DRI2 for clients that use EGL for
> +rendering. However most Weston clients use SHM for rendering (or fall
> +back to SHM if EGL is not available) so it is usable on nVidia and
> +other non-DRI2 X servers.</p>
>  
> -<p><b>Intel</b>: i915 (June 2004) or newer cards.  DRM support has been
> +<p>DRM output (without X) requires Kernel Mode
> +Setting (KMS) and the page flip ioctl.  These are supported by:</p>
> +<ul>
> +<li><b>Intel</b>: 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.</p>
>  
> -<p><b>AMD/ATI</b>: Requires open source driver (radeon/ati,
> +<li><b>AMD/ATI</b>: 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).</p>
>  
> -<p><b>nVidia</b>: Requires Nouveau (open source driver).  DRM output
> +<li><b>nVidia</b>: Requires Nouveau (open source driver).  DRM output
>  <a href="https://bugs.freedesktop.org/show_bug.cgi?id=55596">requires
>  kernel version 3.7-rc3</a>.  DRM output previously required kernel
>  version 2.6.37 for nv40 or lower cards, 2.6.38 for nv50 cards. Some new
>  cards require
>  <a href="http://nouveau.freedesktop.org/wiki/InstallDRM#Firmware">loading
>  external firmware</a>.</p>
> +</ul>
>  
>  <p>For building Weston for <a href="http://www.raspberrypi.org/">Raspberry
>  Pi</a>, see <a href="raspberrypi.html">Raspberry Pi build guide</a>.</p>
> @@ -49,37 +56,67 @@ Pi</a>, see <a href="raspberrypi.html">Raspberry Pi build guide</a>.</p>
>  the following environment variables to get various libraries to link
>  appropriately:</p>
>  
> -<pre>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_PATH="$WLD/share/aclocal"
> -ACLOCAL="aclocal -I $ACLOCAL_PATH"
> -
> -export WLD LD_LIBRARY_PATH PKG_CONFIG_PATH ACLOCAL ACLOCAL_PATH
> +<pre>
> +export WLD=$HOME/install   <font color=#800># change this to another location if you prefer</font>
> +export LD_LIBRARY_PATH=$WLD/lib
> +export PKG_CONFIG_PATH=$WLD/lib/pkgconfig/:$WLD/share/pkgconfig/
> +export ACLOCAL_PATH="$WLD/share/aclocal"
> +export ACLOCAL="aclocal -I $ACLOCAL_PATH"
>  </pre>

This is a good hunk IMO, and the boxing is nice, but I'd like to keep
(and add) the $ in front for manually typed commands.

>  
> -<p>Do not set LD_LIBRARY_PATH as your default, it will break things.</p>
> +<p>Do not set <tt>LD_LIBRARY_PATH</tt> as your default, it will break things.</p>
>  <p>You may put the above in a script and source it in the terminal
>  you wish to build the packages.</p>
>  
> -<h3>Installing system wide</h3>
> -<p>To install system wide, you'll need to set this variable, and possibly
> -build with --libdir=/usr/lib64 :</p>
> +<h3>Installing system wide (not tested)</h3>

If you didn't test it, then don't change the instructions. If you are
not changing the instructions, don't add "not tested".

> +
> +<p>To install system wide, you'll need to set WLD differently, and add
> +some switches to the autogen.sh lines, and use sudo to make
> +install:</p>
>  
> -<pre>WLD=/usr
> -export WLD
> +<pre>
> +export WLD=/usr
> +...
> +./autogen.sh --prefix=$WLD --libdir=/usr/lib64 --sysconfdir=/etc
> +make
> +sudo make install
> +...
>  </pre>
>  
> +<h2>Hints for finding missing dependencies</h2>
> +
> +<p>If "foo" is missing, try "<tt>sudo apt-get install libfoo-dev</tt>"</p>
> +
> +<p>If that does not work, "<tt>apt-cache search foo</tt>" may help.</p>
> +
> +<p>Then "<tt>apt-cache show libfoo-dev</tt>" may show the version it will
> +install, if the config indicates what version it wants. Then again
> +maybe it won't.</p>

These are assuming a particular distribution. A person following these
instructions should already know how to use his distribution. There are
a lot more difficult things to deal with like XDG_RUNTIME_DIR.

> +
> +<p>If that does not work, or it complains about the wrong version, you
> +will have to compile from git. It appears all necessary code is in the
> +<a href="http://cgit.freedesktop.org">freedesktop.org git
> +repository</a>. Sometimes you can guess the name, but they are
> +somewhat random as to what subdirectory they are in or whether "lib"
> +is prefixed, so the best method is to go there and search in your
> +browser for "foo". It is best if you use a repository that does not appear
> +to be a user's personal copy.</p>
> +
>  <h2>Wayland libraries</h2>
>  
> -<p>This is required in order to be able to build Mesa with
> ---with-egl-platforms=x11,wayland,drm.</p>
> +<p>This must be built first, so that Mesa can be compiled with the
> +Wayland backend:</p>
> +
> +<pre>
> +sudo apt-get install doxygen <font color=#800># or use --disable-documentation</font>

Distribution specifics.

> +
> +mkdir -p $WLD/share/aclocal <font color=#800># avoid a bug in aclocal</font>

A good addition, though might also use $ACLOCAL_PATH directly.

>  
> -<pre>    $ git clone git://anongit.freedesktop.org/wayland/wayland
> -    $ cd wayland
> -    $ ./autogen.sh --prefix=$WLD
> -    $ make
> -    $ make install
> +git clone git://anongit.freedesktop.org/wayland/wayland
> +cd wayland
> +./autogen.sh --prefix=$WLD
> +make && make install
> +cd ..
>  </pre>
>  
>  <h2>Mesa</h2>
> @@ -89,21 +126,82 @@ EGL on KMS are now upstream.  Wayland should work with any mesa
>  release after 9.0, but in some cases extra functionality or
>  optimization will only be available in more recent releases.</p>
>  
> -<p>To compile mesa you'll need a development package for libdrm.
> -Other dependencies are development packages of xcb-dri2 and
> -xcb-xfixes.</p>
> -
> -<pre>    $ git clone git://anongit.freedesktop.org/git/mesa/drm
> -    $ cd drm
> -    $ ./autogen.sh --prefix=$WLD
> -    $ make && make install
> -
> -    $ git clone git://anongit.freedesktop.org/mesa/mesa
> -    $ cd mesa
> -    $ ./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
> +<p>Most of the dependencies can be installed with these commands:</p>
> +
> +<pre>
> +sudo apt-get install autoconf automake bison debhelper dpkg-dev flex \
> +  libdrm-dev libexpat1-dev libudev-dev libx11-dev libx11-xcb-dev \
> +  libxdamage-dev libxext-dev libxfixes-dev libxxf86vm-dev \
> +  linux-libc-dev pkg-config python-libxml2 quilt x11proto-dri2-dev \
> +  x11proto-gl-dev xutils-dev
> +
> +sudo apt-get install llvm-3.1-dev <font color=#800># may want to use newest version available</font>
> +sudo ln -sf llvm-config-3.1 /usr/bin/llvm-config
> +
> +sudo apt-get install libpciaccess-dev <font color=#800># needed by drm</font>

Distribution specifics.

> +</pre>
> +
> +<p>You will also have to compile several packages from git:</p>
> +
> +<pre>
> +git clone git://anongit.freedesktop.org/git/mesa/drm
> +cd drm
> +./autogen.sh --prefix=$WLD
> +make && make install
> +cd ..
> +
> +git clone git://anongit.freedesktop.org/xcb/proto
> +cd proto
> +./autogen.sh --prefix=$WLD
> +make && make install
> +cd ..
> +
> +git clone git://anongit.freedesktop.org/xorg/util/macros
> +cd macros
> +./autogen.sh --prefix=$WLD
> +make && make install
> +cd ..
> +
> +git clone git://anongit.freedesktop.org/xcb/libxcb
> +cd libxcb
> +./autogen.sh --prefix=$WLD
> +make && make install
> +cd ..
> +
> +git clone git://anongit.freedesktop.org/xorg/proto/presentproto
> +cd presentproto
> +./autogen.sh --prefix=$WLD
> +make && make install
> +cd ..
> +
> +git clone git://anongit.freedesktop.org/xorg/proto/dri3proto
> +cd dri3proto
> +./autogen.sh --prefix=$WLD
> +make && make install
> +cd ..
> +
> +git clone git://anongit.freedesktop.org/xorg/lib/libxshmfence
> +cd libxshmfence
> +./autogen.sh --prefix=$WLD
> +make && make install
> +cd ..
> +</pre>

These should not usually be needed. I think it would be enough to
just mention --disable-dri3 in case someone has a problem with these
dependencies. The rest are only because you used such an old
distribution as a base. I don't think we should go that far in the
generic guide.

> +
> +<p>If you want to compile the XServer, it may be a good idea to
> +compile all it's <a href="xserver.html">prerequisites</a> now, so
> +that Mesa is using the same version as xserver.</p>

Not sure that really matters.

> +
> +<p>And finally you can compile Mesa:</p>
> +
> +<pre>
> +git clone git://anongit.freedesktop.org/mesa/mesa
> +cd mesa
> +./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 \
> + --disable-llvm-shared-libs <font color=#800># this may be a bug in the llvm package</font>
> +make && make install
> +cd ..

I'm not sure should tell people to use --disable-llvm-shared-libs, the
Mesa default must be good enough, or it is a distribution problem with
the dependencies. Anyway, this is not really a Mesa build guide but
just enough details to configure Mesa properly for Wayland needs in
general.

>  </pre>
>  
>  <p>We disable Gallium for Intel 915 and 965, which just means that libEGL
> @@ -113,52 +211,69 @@ be built as DRI drivers, which the EGL loader will load just fine.</p>
>  <p><a href="mesa-configure.html">Example mesa configure output.</a></p>
>  
>  <p>Note on Mesa build failures:  If you're not building in your Mesa git
> -repo for the first time, the first thing to try is always "git clean
> --xfd", and possibly deleting your $WLD directory, as Mesa requires
> +repo for the first time, the first thing to try is always "<tt>git clean
> +-xfd</tt>", and possibly deleting your $WLD directory, as Mesa requires
>  this often.</p>
>  
> -<h2>libxkbcommon</h2>
> +<h2>Cairo</h2>
>  
> -<p>Wayland needs libxkbcommon >= 0.3.0 for translating evdev keycodes to keysyms.</p>
> +The version of Cairo included with Ubuntu 12.04 has bugs that cause
> +rendering errors in some Wayland clients (in particular the
> +Xserver). Though not required, it may be a good idea to compile the
> +newest version from source:

Distribution specifics. Just drop the Cairo and Pixman parts.

>  
> -<pre>    $ git clone git://github.com/xkbcommon/libxkbcommon
> -    $ cd libxkbcommon/
> -    $ ./autogen.sh --prefix=$WLD --with-xkb-config-root=/usr/share/X11/xkb
> -    $ make && make install
> +<pre>
> +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=$WLD --enable-xcb
> +make && make install
>  </pre>
>  
> -<h2>cairo-gl</h2>
> -
> -<p>The Wayland clients can render using cairo-gl, but fall back to
> -software when cairo-gl is not available.  For cairo-gl, cairo 1.11.3
> -or newer is needed.  For this you'll need a development package for
> -pixman.</p>
> +<h2>Weston and demo applications</h2>
>  
> -<pre>    $ git clone git://anongit.freedesktop.org/pixman
> -    $ cd pixman
> -    $ ./autogen.sh --prefix=$WLD
> -    $ make && make install
> +<p>Weston is the reference implementation of a Wayland compositor.
> +It's available in the weston repo and comes with a few demo
> +applications.
>  
> -    $ git clone git://anongit.freedesktop.org/cairo
> -    $ cd cairo
> -    $ ./autogen.sh --prefix=$WLD --enable-gl --enable-xcb
> -    $ make && make install
> +<pre>
> +sudo apt-get install libmtdev-dev libpam0g-dev

Distribution specifics.

> +
> +git clone git://github.com/xkbcommon/libxkbcommon
> +cd libxkbcommon
> +./autogen.sh --prefix=$WLD --with-xkb-config-root=/usr/share/X11/xkb
> +make && make install
> +cd ..

Not only Weston needs libxkbcommon, but all other Wayland compositors
and clients need it too. Why squash this into the Weston section?

> +
> +<font color=#800># You can skip this if you provide --disable-libunwind to weston autogen</font>
> +git clone git://git.sv.gnu.org/libunwind
> +cd libunwind
> +autoreconf -i
> +./configure --prefix=$WLD
> +make && make install
> +cd ..
>  </pre>
>  
> -<h2>libunwind</h2>
> +<p>For pdf viewer you need poppler-glib and gio-2.0, I did not test this.</p>

The pdf viewer does not exist anymore.

>  
> -<p>Weston requires libunwind v1.1 if you don't configure with
> ---disable-libunwind .</p>
> +<p>Now we can build Weston and the demo programs. Make sure you set
> +the PATH for autogen, if this does not work compilation will fail in
> +wayland-scanner and you must do make clean before trying again as it
> +leaves bad output files:</p>

>  
> -<pre>    $ git clone git://git.sv.gnu.org/libunwind
> -    $ cd libunwind
> -    $ autoreconf -i
> -    $ ./configure --prefix=$WLD
> -    $ make && make install
> +<pre>
> +git clone git://anongit.freedesktop.org/wayland/weston
> +cd weston
> +PATH=$WLD/bin:$PATH ./autogen.sh --prefix=$WLD --disable-setuid-install

No need for PATH, we have a proper fix coming.

> +<font color=#800># remove --disable-setuid-install if installing system-wide</font>

No, system-wide has nothing to do with needing or not needing
setuid-install. weston-launch needs to be setuid if it used, at least
without proper systemd I believe.

> +make && make install
>  </pre>
>  
> -
> -<h2><code>$XDG_RUNTIME_DIR</code></h2>
> +<h2><tt>$XDG_RUNTIME_DIR</tt></h2>

Why tt instead of code?

>  
>  <p>Weston creates its unix socket file (for example, wayland-0)
>  in the directory specified by the required environment variable

The rest I didn't have time to check.

Would be nice to separate the changes to build.html and xserver.html to
different patches. They are not essentially part of the same change,
right?

Thanks,
pq