xorg: Changes to 'debian-unstable'
debian/changelog | 13 +
xsf-docs/faq/general.mdwn | 58 ++++++++
xsf-docs/howto/build-mesa.mdwn | 201 ++++++++++++++++++++++++++++++
xsf-docs/howto/configure-input.mdwn | 176 ++++++++++++++++++++++++++
xsf-docs/howto/report-bugs.mdwn | 38 +++++
xsf-docs/howto/triage-bugs.mdwn | 95 ++++++++++++++
xsf-docs/howto/use-gdb.mdwn | 141 +++++++++++++++++++++
xsf-docs/howto/use-xrandr.mdwn | 173 +++++++++++++++++++++++++
xsf-docs/howtos | 1
xsf-docs/howtos/build-mesa.mdwn | 201 ------------------------------
xsf-docs/howtos/configure-input.mdwn | 167 ------------------------
xsf-docs/howtos/report-bugs.mdwn | 35 -----
xsf-docs/howtos/triage-bugs.mdwn | 93 -------------
xsf-docs/howtos/use-gdb.mdwn | 102 ---------------
xsf-docs/howtos/use-xrandr.mdwn | 173 -------------------------
xsf-docs/index.mdwn | 19 +-
xsf-docs/reference/squeeze-backports.mdwn | 65 +++++++++
17 files changed, 971 insertions(+), 780 deletions(-)
New commits:
commit f299727f49b84f6e52a8d09f05753331e5c4940e
Author: Cyril Brulebois <kibi@debian.org>
Date: Fri Feb 25 21:05:47 2011 +0100
Upload to unstable.
diff --git a/debian/changelog b/debian/changelog
index 7ac8f70..f9e7ac2 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,4 +1,4 @@
-xorg (1:7.6+4) UNRELEASED; urgency=low
+xorg (1:7.6+4) unstable; urgency=low
[ Steve Langasek ]
* Mark x11-common as Multi-Arch: foreign, so foreign-architecture libs
@@ -12,7 +12,7 @@ xorg (1:7.6+4) UNRELEASED; urgency=low
- Update: howto/triage-bugs
- Update: howto/use-gdb (mention getting/using a core file)
- -- Steve Langasek <vorlon@debian.org> Mon, 21 Feb 2011 19:28:58 -0800
+ -- Cyril Brulebois <kibi@debian.org> Fri, 25 Feb 2011 21:05:36 +0100
xorg (1:7.6+3) unstable; urgency=low
commit 73984c6b0576f15d8848cdf0cb36765f01914222
Author: Cyril Brulebois <kibi@debian.org>
Date: Fri Feb 25 21:03:41 2011 +0100
Document the merge.
diff --git a/debian/changelog b/debian/changelog
index f2c1433..7ac8f70 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,8 +1,17 @@
xorg (1:7.6+4) UNRELEASED; urgency=low
+ [ Steve Langasek ]
* Mark x11-common as Multi-Arch: foreign, so foreign-architecture libs
have their dependency satisfied by it.
+ [ Cyril Brulebois ]
+ * Merge xsf-docs up to the 4d4bfa3eaf commit:
+ - Add: faq/general
+ - Add: reference/squeeze-backports
+ - Update: howto/configure-input
+ - Update: howto/triage-bugs
+ - Update: howto/use-gdb (mention getting/using a core file)
+
-- Steve Langasek <vorlon@debian.org> Mon, 21 Feb 2011 19:28:58 -0800
xorg (1:7.6+3) unstable; urgency=low
commit 4d4bfa3eaff329d4fb51d970aa2f048ee0ae815d
Author: Cyril Brulebois <kibi@debian.org>
Date: Fri Feb 25 00:48:50 2011 +0100
use-gdb: Mention getting a core with kdm.
diff --git a/xsf-docs/howto/use-gdb.mdwn b/xsf-docs/howto/use-gdb.mdwn
index d90591c..f60eab0 100644
--- a/xsf-docs/howto/use-gdb.mdwn
+++ b/xsf-docs/howto/use-gdb.mdwn
@@ -56,6 +56,11 @@ that.**
[daemon]
LocalXserverCommand=/usr/bin/Xorg -br -verbose -audit 0 -novtswitch -core
+ * Using `kdm`: One should look for the `ServerArgsLocal` variable in
+ the `/etc/kde4/kdm/kdmrc` file, and add `-core` there. Example:
+
+ ServerArgsLocal=-br -nolisten tcp -core
+
* Using `xdm`: It’s sufficient to add `-core` to the command
configured through `/etc/X11/xdm/Xservers`, for example:
commit 8a3e38ac6853fc35327363e26aad55f2f4b9651f
Author: Cyril Brulebois <kibi@debian.org>
Date: Fri Feb 25 00:44:07 2011 +0100
use-gdb: Need to specify the binary when loading a core.
diff --git a/xsf-docs/howto/use-gdb.mdwn b/xsf-docs/howto/use-gdb.mdwn
index 8e1b097..d90591c 100644
--- a/xsf-docs/howto/use-gdb.mdwn
+++ b/xsf-docs/howto/use-gdb.mdwn
@@ -63,9 +63,10 @@ that.**
### Loading a core file
-That’s trivial:
+That’s trivial, one just needs to pass both the core file and the path
+to the binary:
- # gdb -c /etc/X11/core
+ # gdb -c /etc/X11/core /usr/bin/Xorg
Now `gdb` is ready to display backtraces.
commit 8802b8730bac49ebeb9e48772a5e1ba65920d56c
Author: Cyril Brulebois <kibi@debian.org>
Date: Fri Feb 25 00:25:14 2011 +0100
use-gdb: Mention getting a core with xdm.
diff --git a/xsf-docs/howto/use-gdb.mdwn b/xsf-docs/howto/use-gdb.mdwn
index daa7cc9..8e1b097 100644
--- a/xsf-docs/howto/use-gdb.mdwn
+++ b/xsf-docs/howto/use-gdb.mdwn
@@ -56,6 +56,11 @@ that.**
[daemon]
LocalXserverCommand=/usr/bin/Xorg -br -verbose -audit 0 -novtswitch -core
+ * Using `xdm`: It’s sufficient to add `-core` to the command
+ configured through `/etc/X11/xdm/Xservers`, for example:
+
+ :0 local /usr/bin/X :0 vt7 -nolisten tcp -core
+
### Loading a core file
That’s trivial:
commit a0dbd236a467fcd688e85d33a5409eadc6c75e38
Author: Cyril Brulebois <kibi@debian.org>
Date: Thu Feb 24 19:17:47 2011 +0100
use-gdb: Mention getting a core with gdm3.
diff --git a/xsf-docs/howto/use-gdb.mdwn b/xsf-docs/howto/use-gdb.mdwn
index 89de47e..daa7cc9 100644
--- a/xsf-docs/howto/use-gdb.mdwn
+++ b/xsf-docs/howto/use-gdb.mdwn
@@ -45,6 +45,17 @@ that.**
## Actual gdb work
+### Getting a core file
+
+ * Using `gdm3`: The idea is to tweak the daemon’s
+ `LocalXserverCommand` setting, adding the `-core` option. As of
+ `gdm3 2.30`, the defaults can be found in
+ `/usr/share/gdm/gdm.schemas`. Sample `/etc/gdm3/daemon.conf`
+ excerpt:
+
+ [daemon]
+ LocalXserverCommand=/usr/bin/Xorg -br -verbose -audit 0 -novtswitch -core
+
### Loading a core file
That’s trivial:
commit 69be710b26fb230628f64da67d0018d579ed868f
Author: Cyril Brulebois <kibi@debian.org>
Date: Thu Feb 24 19:00:13 2011 +0100
use-gdb: Mention the needed steps for each approach.
diff --git a/xsf-docs/howto/use-gdb.mdwn b/xsf-docs/howto/use-gdb.mdwn
index 4ae55ba..89de47e 100644
--- a/xsf-docs/howto/use-gdb.mdwn
+++ b/xsf-docs/howto/use-gdb.mdwn
@@ -19,12 +19,23 @@ This is a *post-mortem* approach. The idea is to run X with the
`-core` option. Once it dies, a core file (`/etc/X11/core`) is
generated, and can be loaded from `gdb`.
+Follow these steps:
+
+ 1. Getting a core file.
+ 2. Loading a core file.
+ 3. Displaying/saving a backtrace.
+
### Two-machine approach
You pay the “need a second machine” price, but that buys you
interactivity. Just log into the first machine from the second one,
using `ssh`.
+Follow these steps:
+
+ 1. Attaching/Starting X from gdb.
+ 2. Displaying/saving a backtrace.
+
### Needed packages
Obviously, `gdb` is needed; `xserver-xorg-core-dbg` contains the
commit 9de1c5e28da7ecba417876671cdfef1ea9bd335f
Author: Cyril Brulebois <kibi@debian.org>
Date: Thu Feb 24 18:52:57 2011 +0100
use-gdb: Mention loading a core dump.
diff --git a/xsf-docs/howto/use-gdb.mdwn b/xsf-docs/howto/use-gdb.mdwn
index a3be461..4ae55ba 100644
--- a/xsf-docs/howto/use-gdb.mdwn
+++ b/xsf-docs/howto/use-gdb.mdwn
@@ -34,6 +34,14 @@ that.**
## Actual gdb work
+### Loading a core file
+
+That’s trivial:
+
+ # gdb -c /etc/X11/core
+
+Now `gdb` is ready to display backtraces.
+
### Attaching X from gdb
The way of starting X doesn’t really matter, as `gdb` makes it
commit 2951c0265f337b17d95e2f16f149e1e11f504e52
Author: Cyril Brulebois <kibi@debian.org>
Date: Thu Feb 24 18:50:20 2011 +0100
use-gdb: Mention the core file for the single machine approach.
diff --git a/xsf-docs/howto/use-gdb.mdwn b/xsf-docs/howto/use-gdb.mdwn
index df7152d..a3be461 100644
--- a/xsf-docs/howto/use-gdb.mdwn
+++ b/xsf-docs/howto/use-gdb.mdwn
@@ -15,17 +15,15 @@ with a single machine.
### One-machine approach
-From a console (let’s assume it’s `vt1`), open a `root`
-terminal. Then, start a loop which will bring you back to this console
-after a given delay (in the following example, every 60 seconds), just
-in case. The ampersand (`&`) at the end makes it a background job.
-
- while :; do sleep 60; chvt 1; done &
+This is a *post-mortem* approach. The idea is to run X with the
+`-core` option. Once it dies, a core file (`/etc/X11/core`) is
+generated, and can be loaded from `gdb`.
### Two-machine approach
-That’s simpler, but then you need a second machine. Just log into the
-first machine from the second one, using `ssh`.
+You pay the “need a second machine” price, but that buys you
+interactivity. Just log into the first machine from the second one,
+using `ssh`.
### Needed packages
commit 25fbfe0adec72cd09ceee2f8055f583602e6eb75
Author: Cyril Brulebois <kibi@debian.org>
Date: Thu Feb 24 18:39:55 2011 +0100
faq/general: Mention configure-input, and terminate:ctrl_alt_bksp.
diff --git a/xsf-docs/faq/general.mdwn b/xsf-docs/faq/general.mdwn
index 80c23f3..515bc78 100644
--- a/xsf-docs/faq/general.mdwn
+++ b/xsf-docs/faq/general.mdwn
@@ -3,6 +3,14 @@
Cyril Brulebois <kibi@debian.org>
+## Input drivers
+
+ * *How do I configure input for X?*
+ Look at the [how to configure input](../howto/configure-input.html) documentation.
+
+ * *Why can’t I kill X through `Ctrl+Alt+Backspace`?*
+ That’s explained in the above-mentioned documentation.
+
## Video drivers
### Intel driver
commit c9df1b6b4b232d43f35f0456dd731428f9a982ef
Author: Cyril Brulebois <kibi@debian.org>
Date: Mon Feb 21 16:56:06 2011 +0100
faq/general: Mention how to start a bare X session.
diff --git a/xsf-docs/faq/general.mdwn b/xsf-docs/faq/general.mdwn
index 8e86196..80c23f3 100644
--- a/xsf-docs/faq/general.mdwn
+++ b/xsf-docs/faq/general.mdwn
@@ -37,3 +37,14 @@ Cyril Brulebois <kibi@debian.org>
(view it online:
[for squeeze](http://git.debian.org/?p=pkg-xorg/driver/xserver-xorg-video-nouveau.git;a=blob;f=debian/README.Debian;h=27ced6b1bf5102a5b72525318439efdfb330745d;hb=6c2f12ca18f55b55d49e083d86d87d970ce53a07),
[for sid](http://git.debian.org/?p=pkg-xorg/driver/xserver-xorg-video-nouveau.git;a=blob;f=debian/README.Debian)).
+
+
+## Others
+
+### Session management
+
+ * *How to start a bare X session (without Gnome, KDE, etc.)?*
+ Assuming there’s no X running on the `:1` display, run this from a
+ VT:
+
+ startx /usr/bin/xterm -- :1
commit 9833fa5dffd02cb908309a83a44a200dcd3dd9d7
Author: Cyril Brulebois <kibi@debian.org>
Date: Mon Feb 21 04:04:06 2011 +0100
index: Link to squeeze-backports.
diff --git a/xsf-docs/index.mdwn b/xsf-docs/index.mdwn
index 3a516bd..0e30322 100644
--- a/xsf-docs/index.mdwn
+++ b/xsf-docs/index.mdwn
@@ -22,6 +22,7 @@ metapackage (under `/usr/share/doc/xorg`), starting with `wheezy`.
## Reference documentation
* [Dependencies between server and drivers](reference/dependencies.html)
+ * [Backports policy for squeeze](reference/squeeze-backports.html)
* [Upstream contacts](reference/upstream-contacts.html)
## Other documentation
commit 902ebb749f699e5bb444fe5e861335c9bcf0586d
Author: Cyril Brulebois <kibi@debian.org>
Date: Mon Feb 21 04:03:16 2011 +0100
reference/squeeze-backports: New document.
diff --git a/xsf-docs/reference/squeeze-backports.mdwn b/xsf-docs/reference/squeeze-backports.mdwn
new file mode 100644
index 0000000..89b923f
--- /dev/null
+++ b/xsf-docs/reference/squeeze-backports.mdwn
@@ -0,0 +1,65 @@
+# Backports policy for squeeze
+
+Cyril Brulebois <kibi@debian.org>
+
+
+## Proposed plans
+
+If one forgets about libraries and clients, a whole X stack boils down
+to: the server itself, input and video drivers, libdrm, and mesa.
+
+Since upgrading the server means upgrading all input and video drivers
+(more than 50 source packages), that’s certainly too much to backport,
+since we’re already trying to support `stable` (through stable
+updates), `testing`/`unstable`, and `experimental`. For example, in
+February 2011, that means `xorg-server` 1.7 in `stable`, 1.9 in
+`unstable` (and “soon” in `testing`), and 1.10 in `experimental`.
+
+So the plan is to keep `xorg-server` as it is in `squeeze` (possibly
+preparing/testing targeted fix if appropriate), and backporting
+drivers when possible. With API/ABI updates, the minimal server
+version required tend to get raised from time to time, but usually
+drivers can be built against a rather large range of server
+versions. In case a driver stop building against the server available
+in `stable`, we’ll likely stick to the highest version still building
+against it, and then tell people to upgrade the whole stack if they
+need something more recent (unless some trivial cherry-picking is
+possible, of course).
+
+The plan is to backport a few drivers on a possibly regular fashion,
+and other drivers upon request.
+
+
+### Input drivers
+
+ * `evdev`: Linux-only keyboard & mouse/pointer driver.
+ * `keyboard` and `mouse`: Needed for non-Linux ports.
+ * `synaptics`: Better touchpad support than `evdev`.
+
+
+### Video drivers
+
+ * `ati`, `mach64`, `r128`: Drivers for ATI cards.
+ * `intel`: Driver for Intel cards.
+ * `nouveau`: Driver for NVidia cards.
+ * `fbdev` and `vesa`: Generic drivers.
+ * `dummy`: Dummy driver, suitable when there’s no monitor connected.
+
+
+### Libraries
+
+The important libraries are `libdrm` and `mesa`. The former will
+likely get pulled at some point by a driver, so a backport will be
+needed for this library. The latter is under very heavy development,
+so one may want to try a new release or a snapshot without having to
+upgrade everything to `unstable`. It’s a huge package to build, so we
+[documented how to build it](../howto/build-mesa.html) locally. But
+there’s some hope to make some weekly or daily builds available at
+some point.
+
+
+### Kernel
+
+Some of those drivers might need a more recent kernel version than
+the one in `squeeze`, but hopefully it’ll be available through
+`squeeze-backports` as well.
commit a46a56813275a2c336bede0dbbd63ab54c37e6c6
Author: Cyril Brulebois <kibi@debian.org>
Date: Mon Feb 21 03:31:22 2011 +0100
report-bugs: Link to use-gdb.
diff --git a/xsf-docs/howto/report-bugs.mdwn b/xsf-docs/howto/report-bugs.mdwn
index 6fc7140..15b36df 100644
--- a/xsf-docs/howto/report-bugs.mdwn
+++ b/xsf-docs/howto/report-bugs.mdwn
@@ -21,6 +21,9 @@ Note: In case this metapackage wasn’t used to install your X stack,
report a bug against `xserver-xorg` instead. And if that one isn’t
installed either, go for `xserver-xorg-core`.
+If a backtrace shows up in the X log, it’s much appreciated to try and
+get a [full backtrace using gdb](use-gdb.html).
+
### Follow-up with more info
commit e28961893d9b141475e72d50a9dc3a4ff6eba761
Author: Cyril Brulebois <kibi@debian.org>
Date: Fri Feb 18 23:53:24 2011 +0100
triage-bugs: Mention “exclude=tag:squeeze-accepted”.
diff --git a/xsf-docs/howto/triage-bugs.mdwn b/xsf-docs/howto/triage-bugs.mdwn
index e523584..8ee3f94 100644
--- a/xsf-docs/howto/triage-bugs.mdwn
+++ b/xsf-docs/howto/triage-bugs.mdwn
@@ -49,9 +49,11 @@ Here’s an example of URL, for the last tags:
By the way one should keep an eye on the list of found/fixed
versions since those bugs are likely marked as resolved (in `unstable`
-or `experimental`), but might still affect a stable release. Maybe we
-just need to have both `squeeze-candidate` and `squeeze-accepted`, and
-swap usertags when the stable upload happens.
+or `experimental`), but might still affect a stable release.
+
+To list the bugs marked `squeeze-candidate` but not
+`squeeze-accepted`:
+→ <http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=debian-x@lists.debian.org&tag=squeeze-candidate&exclude=tag:squeeze-accepted>
## Categories
commit a6a400729c813eb8c2ce4b62b5bd022d889fd984
Author: Cyril Brulebois <kibi@debian.org>
Date: Tue Feb 15 22:09:35 2011 +0100
howtos: Rename to howto for consistency.
We have faq/ and reference/ as singular. Keep a symlink for now since
some mails to the BTS reference howtos/*.
diff --git a/xsf-docs/howto/build-mesa.mdwn b/xsf-docs/howto/build-mesa.mdwn
new file mode 100644
index 0000000..dc49cd9
--- /dev/null
+++ b/xsf-docs/howto/build-mesa.mdwn
@@ -0,0 +1,201 @@
+# How to build mesa
+
+Cyril Brulebois <kibi@debian.org>
+
+
+## Foreword
+
+Mesa is a special package since many flavours are built, which means
+it takes quite some time to get all packages ready, as well as some
+disc space (over 2GB for the `build/` directory alone).
+
+Also, trying to figure out whether latest `master` is also affected,
+or backporting some bug fixes might lead to some painful I/O while
+generating the `.deb` files, and then installing/unpacking them. This
+is why this document was written: Helping users test other mesa
+releases, branches, bug fixes without having to build full packages,
+and without having to mess with their systems (*i.e.* no root access
+is needed once the build dependencies are installed).
+
+We’ll focus on the DRI (Direct Rendering Infrastructure) flavour
+(`libgl1-mesa-dri`), which is the most common.
+
+It might be possible to adapt the following steps to another flavour,
+in which case the appropriate options to be passed to `./configure`
+should be looked up in the `debian/rules` file of the Debian source
+package.
+
+*Note:* Before reading further, be aware that `nouveau` is a bit
+ special.
+
+ * It’s considered experimental, and shipped in the
+ `libgl1-mesa-dri-experimental` package accordingly.
+ * It may fail to build (both API and ABI are still changing).
+ * We’re not shipping `nouveau_vieux_dri.so` yet (for cards from NV04
+ to NV2X; `nouveau_dri.so` is for NV30 and later). See the upstream
+ [FeatureMatrix](http://nouveau.freedesktop.org/wiki/FeatureMatrix)
+ page to determine a card’s series.
+
+
+## Gathering information
+
+Get started by installing `mesa-utils`, which contains `glxinfo`.
+
+ * *Is direct rendering enabled?*
+
+ $ glxinfo | grep ^direct
+ direct rendering: Yes
+
+ ↪ Yes.
+
+ * *Is this the classic or
+ [Gallium](http://en.wikipedia.org/wiki/Gallium3D) driver?*
+
+ $ glxinfo | grep 'renderer string'
+ OpenGL renderer string: Mesa DRI Intel(R) 945GM GEM 20100330 DEVELOPMENT
+
+ ↪ No “Gallium” here, therefore: “classic”.
+
+ * *Which driver is this, and where is it located?*
+
+ $ LIBGL_DEBUG=verbose glxinfo 2>&1 >/dev/null | grep so$
+ libGL: OpenDriver: trying /usr/lib/dri/tls/i915_dri.so
+ libGL: OpenDriver: trying /usr/lib/dri/i915_dri.so
+
+ ↪ `i915`, from the system directory: `/usr/lib/dri` (likely
+ installed through a Debian package).
+
+ * *How can I get more debugging information?*
+
+ export LIBGL_DEBUG=verbose
+ export MESA_DEBUG=1
+ export EGL_LOG_LEVEL=debug
+
+
+## Preparing mesa sources
+
+To get started, installing all build dependencies of the `mesa` source
+package should be sufficient, along with the essential build tools,
+and `git`:
+
+ $ sudo apt-get install build-essential git
+ $ sudo apt-get build-dep mesa
+
+If you’re on `squeeze` you may need to install a few more packages:
+newer `libdrm-dev` (**FIXME:** talk about picking it from `wheezy`? or
+about a local installation?), as well as `libxmu-dev`, `libxi-dev`.
+
+Make sure you have some disc space available, since the git repository
+is over 120MB, and since the mesa directory is over 500MB after a
+build. Once you’re ready, grab the upstream mesa sources:
+
+ $ git clone git://anongit.freedesktop.org/mesa/mesa mesa.git
+ $ cd mesa.git
+ $ autoreconf -vfi
+
+Here’s what the `./configure` call will look like:
+
+ $ ./configure --enable-driglx-direct \
+ --enable-gallium \
+ --enable-gles-overlay \
+ --enable-gles1 \
+ --enable-gles2 \
+ --enable-glx-tls \
+ --with-driver=dri \
+ --with-dri-driverdir=/usr/lib/dri \
+ --with-egl-platforms='drm x11' \
+ --with-state-trackers=egl,glx,dri,vega \
+ …
+
+Now, what are the parameters to replace “`…`” with? Basically, if
+you determined an Intel driver (`i915` or `i965`), you want to use the
+classic drivers and to disable the Gallium drivers. If you saw a
+Radeon driver (`r300` or `r600`), you should prefer the Gallium
+drivers. If you’re using `nouveau`, make sure you read the note in the
+**Foreword**. The following assumes you’re using `nouveau_dri.so`.
+
+
+Examples for common drivers:
+
+ * For `i915`, you need:
+
+ --with-dri-drivers=i915
+
+ * For `i965`, you need:
+
+ --with-dri-drivers=i965
+
+ * For `nouveau`, you may want to try:
+
+ --with-dri-drivers=nouveau --enable-gallium-nouveau
+
+ * For `r300` (the options are named `radeon`), you need:
+
+ --with-dri-drivers=radeon --enable-gallium-radeon
+
+ * For `r600`, you need:
+
+ --with-dri-drivers=r600 --enable-gallium-r600
+
+Now, once you’ve run `./configure`, time for your favorite beverage:
+
+ $ make
+
+
+## Running the newly-built mesa libraries
+
+Shared libraries end up in the `lib/` directory. It contains the
+classic drivers, while Gallium drivers end up under `lib/gallium`. If
+you’re not an Intel user, overwrite the classic drivers with the
+Gallium ones:
+
+ $ mv lib/gallium/* lib/
+
+Now, 3 variables need to be set, so that the locally-built libraries
+are used.
+
+ * To begin with, libGL itself and its drivers:
+
+ $ export LIBGL_DRIVERS_PATH=lib
+
+ *Did this work?*
+
+ $ LIBGL_DEBUG=verbose glxinfo 2>&1 >/dev/null | grep so$
+ libGL: OpenDriver: trying lib/tls/i915_dri.so
+ libGL: OpenDriver: trying lib/i915_dri.so
+
+ ↪ Yes: No system directory, paths are relative to `lib/`.
+
+ * Set `LD_LIBRARY_PATH` to make sure the locally-built libraries
+ (including those pulled through library dependencies) are used,
+ instead of system ones:
+
+ $ export LD_LIBRARY_PATH=lib
+
+ *Did this work?*
+
+ $ ldd lib/libGLESv2.so | grep glapi
+ libglapi.so.0 => lib/libglapi.so.0 (0x00007fee3192e000)
+
+ ↪ Yes: Path is relative to `lib`.
+
+ * Set the EGL search path:
+
+ $ export EGL_DRIVERS_PATH=lib/egl
+
+ *Did this work?*
+
+ **FIXME: We should be shipping EGL-aware applications through
+ `mesa-utils`.**
+
+ $ EGL_LOG_LEVEL=debug test_application 2>&1 >/dev/null | grep '\.so'
+ libEGL debug: added lib/egl/egl_gallium.so to module array
+ libEGL debug: dlopen(lib/egl/egl_gallium.so)
+ libEGL debug: DRI2: dlopen(lib/i915_dri.so)
+
+ ↪ Yes: No system directory, paths are relative to `lib/`.
+
+
+### The end.
+
+Now you should be ready to test upstream’s suggestions!
diff --git a/xsf-docs/howto/configure-input.mdwn b/xsf-docs/howto/configure-input.mdwn
new file mode 100644
index 0000000..75ea3c3
--- /dev/null
+++ b/xsf-docs/howto/configure-input.mdwn
@@ -0,0 +1,176 @@
+# How to configure input
+
+Cyril Brulebois <kibi@debian.org>
+
+
+## General considerations
+
+### Foreword
+
+The Debian wiki also contains an
+[inupt hotplug guide](http://wiki.debian.org/XStrikeForce/InputHotplugGuide)
+which contains some context around X’s input subsystem. The present
+document is meant to be an executive summary, and might miss some
+bits. (**FIXME:** Merge those bits.)
+
+
+### Rules of thumb
+
+In this documentation, only the last part of the driver’s name will be
+mentioned, all of them are under the `xserver-xorg-input-*` namespace.
+
+ * On Linux, `evdev` is used for both keyboard and mouse
+ input.
+ * On Linux as well, `synaptics` can be used to benefit from extra
+ features; it takes precedence over `evdev` automatically if both
+ are installed.
+ * On GNU/kFreeBSD and GNU/Hurd, `kbd` handles the keyboard and
+ `mouse` handles mice, unsurprisingly.
+
+
+### Configuration snippets
+
+X can now be run without `xorg.conf`, but sometimes one has to
+configure a few settings for this or that driver. Starting with
+`squeeze`, that can be done by adding a file under
+`/etc/X11/xorg.conf.d`, with a `.conf` suffix, as documented in the
+`xorg.conf` manpage.
+
+Some packages ship a default configuration file under
+`/usr/share/X11/xorg.conf.d` with general rules to match appropriate
+hardware. The files under `/etc/X11/xorg.conf.d` take precedence, as
+documented in the `xorg.conf` manpage.
+
+It’s probably mostly useful in the `synaptics` case, in case one wants
+to change default settings on a system-wide fashion. See the **Pointer
+configuration** section below for an example.
+
+
+## Basic keyboard configuration
+
+The `keyboard-configuration` package ships `/etc/default/keyboard`
+which can be used to set the following `xkb` items: model, layout,
+variant, and options. Here’s an example:
+
+ XKBMODEL="pc105"
+ XKBLAYOUT="fr"
+ XKBVARIANT="oss"
+ XKBOPTIONS="compose:menu,terminate:ctrl_alt_bksp"
+
+Quick words about the options:
+
+ * They are comma-separated.
+ * The list of options and a short description for each can be found
+ in the `/usr/share/X11/xkb/rules/base.lst` file (shipped by the
+ `xkb-data` package).
+ * First option: `compose:menu`. This sets the `menu` key as the
+ Compose key. More information about it can be found in the
+ `Compose` manpage.
+ * Second option: `terminate:ctrl_alt_bksp`. By default, the X server
+ is no longer killed through `Ctrl+Alt+Backspace`. This option
+ restores the old behaviour.
+
+Two ways to change the configuration:
+
+ * `dpkg-reconfigure keyboard-configuration` is going to ask questions
+ through debconf prompts.
+ * Manually editing `/etc/default/keyboard` also works.
+
+How does it propagate to X?
+
+ * When HAL is used (that is: on GNU/kFreeBSD and GNU/Hurd), one has
+ to restart it: `invoke-rc.d hal restart`
+ * When udev is used (on GNU/Linux, starting with `squeeze`), one has
+ to tell udev to reload input-related configuration:
+ `udevadm trigger --subsystem-match=input --action=change`
+ (that can be found in `keyboard-configuration`’s `README.Debian`
+ file). Properties attached to the input devices are then updated,
+ and X uses those properties when it starts, as can be seen by
+ searching for `xkb_` in the X log. Please note that trying
+ `invoke-rc.d udev restart` changes nothing, one has to use
+ `udevadm`. Properties can be inspected through:
+ `/sbin/udevadm info --export-db`
+
+
+## Pointer configuration
+
+### evdev configuration
+
+Available options are documented in the `evdev` manpage. Let’s check
+what a configuration snippet (mentioned in **General considerations**)
+would look like. Here is a fictional `/etc/X11/xorg.conf.d/42-evdev.conf`:
+
+ Section "InputClass"
+ Identifier "evdev pointer tweaked catchall"
+ MatchIsPointer "on"
+ Driver "evdev"
+ Option "Emulate3Buttons" True"
+ Option "SwapAxes" "True"
+ EndSection
+
+Line by line walkthrough:
+
+ * To avoid specifying any device under `/dev/input` (`event$N` might
+ change, remember it’s about hotplug support!), we use an
+ `InputClass`.
+ * We need an identifier, the actual name doesn’t matter.
+ * We match everything that looks like a touchpad. Meaning no generic
+ pointer, keyboard, or tablet.
+ * We specify the driver we want to use for the matched device(s).
+ * Finally the options we want to set. Here we enable the 3rd button
+ emulation (clicking left and right buttons at the same time then no
+ longer acts as if the middle button was clicked). Then we swap x
+ and y axes, just for the fun of it.
+
+
+### synaptics configuration
+
+The `synaptics` driver comes with two tools. The more interesting one
+is `synclient`, which can be used to list available options and
+current settings: `synclient -l`. The documentation for each option
+can be found in the `synaptics` manpage.
+
+`synclient` can also be used to set options. A common example is
+enabling tapping (upstream kept it disabled by default, Debian won’t
+deviate, no need to file bugs): `synclient TapButton1=1`; one can also
+disable the touchpad temporarily: `synclient TouchpadOff=1` to
+disable it, `synclient TouchpadOff=0` to enable it again.
+
+Let’s check what a configuration snippet (mentioned in **General
+considerations**) would look like. Here is a fictional
+`/etc/X11/xorg.conf.d/42-synaptics.conf`:
+
+ Section "InputClass"
+ Identifier "touchpad tweaked catchall"
+ MatchIsTouchpad "on"
+ Driver "synaptics"
+ Option "TapButton1" "1"
+ Option "HorizEdgeScroll" "1"
+ EndSection
+
+Line by line walkthrough:
+
+ * To avoid specifying any device under `/dev/input` (`event$N` might
+ change, remember it’s about hotplug support!), we use an
+ `InputClass`.
+ * We need an identifier, the actual name doesn’t matter.
+ * We match everything that looks like a touchpad. Meaning no generic
+ pointer, keyboard, or tablet.
+ * We specify the driver we want to use for the matched device(s).
+ * Finally the options we want to set. We enable tapping for the first
+ button. And we enable horizontal scrolling (by default, only
+ vertical scrolling is enabled).
+
+Settings can also be changed by various settings managers, like
+Gnome’s or KDE’s. An example of a graphical user interface making it
+possible to set options in a clicky way: `gpointing-device-settings`.
+
+There’s a palm detection setting but that relies on hardware/firmware
+support for the touchpad. The other tool shipped with the `synaptics`
+driver is `syndaemon`, which makes it trivial to disable the touchpad
+temporarily, when the keyboard is being used. Here’s an example:
+`syndaemon -d -i 0.5` makes `syndaemon` start in background (`-d` for
+daemon mode), waiting 0.5 second before enabling the touchpad again
+after the last keypress. Warning: it becomes quite difficult to use
+things like `Ctrl+click` in a browser, or `Alt+drag` to move
+windows.
diff --git a/xsf-docs/howto/report-bugs.mdwn b/xsf-docs/howto/report-bugs.mdwn
new file mode 100644
index 0000000..6fc7140
--- /dev/null
+++ b/xsf-docs/howto/report-bugs.mdwn
@@ -0,0 +1,35 @@
+# How to report bugs
+
+Cyril Brulebois <kibi@debian.org>
+
+
+## Simple as reportbug
+
+### Initial report
+
+Unless you know which package to report the bug against, you can
+report the bug against the `xorg` metapackage:
+
+ reportbug xorg
+
+Like most packages related to the X server, reporting a bug against
+this package triggers a bug script which is going to collect X-related
+information, be it installed packages, running kernel, X
+configuration, X log, and so on.
+
+Note: In case this metapackage wasn’t used to install your X stack,
+report a bug against `xserver-xorg` instead. And if that one isn’t
+installed either, go for `xserver-xorg-core`.
+
+
+### Follow-up with more info
+
+If you reported a bug against another package and if that bug was
+reassigned to an X-related package, we might need more
+information. You can run the bug script manually and attach its output
+to your mail to the bug report:
+
+ /usr/share/bug/xserver-xorg-core/script 3>/tmp/script.log
+
+Note: Make sure there’s no space between `3` and `>`, that’s a shell
+redirection.
diff --git a/xsf-docs/howto/triage-bugs.mdwn b/xsf-docs/howto/triage-bugs.mdwn
new file mode 100644
index 0000000..e523584
--- /dev/null
+++ b/xsf-docs/howto/triage-bugs.mdwn
@@ -0,0 +1,93 @@
+# How to triage bugs
+
+Cyril Brulebois <kibi@debian.org>
+
+
+## Packaging bugs or upstream bugs?
+
+It’d be nice to get all upstream bugs tagged as such (`upstream` tag),
+forwarded upstream (which means the bugzilla instance on
+<http://bugs.freedesktop.org/> for most packages), and marked as such.
+
+A mail to `control@bugs.debian.org` would look like:
+
+ tag X upstream
+ forwarded X https://bugs.freedesktop.org/show_bug.cgi?id=Y
+ thanks
+
+Then [`bts-link`](http://bts-link.alioth.debian.org/) comes into play
+and help us tracking upstream status, which is pretty nice to have.
+
+
+## Usertags
+
+Another feature of the BTS is usertagging. That lets people keep track
+of additional tags, “attached” to a given mail address. For XSF,
+that’s `debian-x@lists.debian.org`.
+
+The list of all usertagged bugs can be seen on the following page; the
+list of all used usertags is at the bottom, in the form.
+→ <http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=debian-x@lists.debian.org>
+
+Let’s give some examples:
+
+ * `i810`, `i915`: helps triaging `-video-intel` bugs depending on the
+ chipset.
+ * `r200`, `r300`: ditto for `-video-ati`.
+ * `xset`, `xrandr`: helps triaging `x11-xserver-utils` bugs depending
+ on the affected tool (like other `x11-*` packages, that’s a bundle
+ of teeny tiny apps).
+ * `squeeze-candidate`: helps keeping a list of bugs we’d like to get
+ fixed in a point release (through a stable update).
+ * `needs-forwarding`: of course, it’d be nice to have all upstream
+ bugs reported upstream, but some might need special attention
+ (*e.g.* security bugs).
+
+Here’s an example of URL, for the last tags:
+→ <http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=debian-x@lists.debian.org&tag=squeeze-candidate>
+→ <http://bugs.debian.org/cgi-bin/pkgreport.cgi?users=debian-x@lists.debian.org&tag=needs-forwarding>
+
+By the way one should keep an eye on the list of found/fixed
+versions since those bugs are likely marked as resolved (in `unstable`
+or `experimental`), but might still affect a stable release. Maybe we
+just need to have both `squeeze-candidate` and `squeeze-accepted`, and
+swap usertags when the stable upload happens.
+
+
+## Categories
+
+The BTS has yet another feature which can help, categories. That’s
+based on usertags as well, but one has to use the package address
+(`$package@packages.debian.org`), so that’s package-specific rather
+than team-specific.
+
+Categories are
+[documented on the wiki](http://wiki.debian.org/bugs.debian.org/usertags),
+and they would probably be welcome in the `intel` and `ati` cases
+above, as well as in the “multiple tools in a single bundle”
+cases… An example of what we could achieve is the
+[devscripts bug page](http://bugs.debian.org/devscripts) (it takes
+some time to load, plenty of bugs).
+
+Needed steps for that to happen:
+
+ * create usercategories.
+ * move usertags from `debian-x@lists.debian.org` to
+ `$package@packages.debian.org`, probably using the `bts select`
+ command to get the list over which to iterate.
+ * profit!
+
+To move the usertags, something like that should do the job:
+
+ # Adding usertags:
+ user $package1@packages.debian.org
+ usertag X xset
+ usertag Y xrandr
+ user $package2@packages.debian.org
+ usertag Z i810
+
+ # Removing tags which are no longer needed:
Reply to: