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 <[email protected]> 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 <[email protected]> Mon, 21 Feb 2011 19:28:58 -0800 + -- Cyril Brulebois <[email protected]> Fri, 25 Feb 2011 21:05:36 +0100 xorg (1:7.6+3) unstable; urgency=low commit 73984c6b0576f15d8848cdf0cb36765f01914222 Author: Cyril Brulebois <[email protected]> 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 <[email protected]> Mon, 21 Feb 2011 19:28:58 -0800 xorg (1:7.6+3) unstable; urgency=low commit 4d4bfa3eaff329d4fb51d970aa2f048ee0ae815d Author: Cyril Brulebois <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> +## 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 <[email protected]> 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 <[email protected]> (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 <[email protected]> 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 <[email protected]> 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 <[email protected]> + + +## 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 <[email protected]> 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 <[email protected]> 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/[email protected]&tag=squeeze-candidate&exclude=tag:squeeze-accepted> ## Categories commit a6a400729c813eb8c2ce4b62b5bd022d889fd984 Author: Cyril Brulebois <[email protected]> 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 <[email protected]> + + +## 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 <[email protected]> + + +## 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 <[email protected]> + + +## 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 <[email protected]> + + +## 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 `[email protected]` 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 `[email protected]`. + +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/[email protected]> + +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/[email protected]&tag=squeeze-candidate> +→ <http://bugs.debian.org/cgi-bin/[email protected]&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 +(`[email protected]`), 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 `[email protected]` to + `[email protected]`, 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 [email protected] + usertag X xset + usertag Y xrandr + user [email protected] + usertag Z i810 + + # Removing tags which are no longer needed: -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected] Archive: http://lists.debian.org/[email protected]
