+First, create a build script, named build-script.sh, containing:
+
+ #!/bin/sh
+ set -e
+ export PATH=/usr/lib/ccache:$PATH
+ export CFLAGS='-g'
+ export CXXFLAGS='-g'
+ ./autogen.sh --disable-egl --disable-gallium --disable-glut --disable-glu --disable-glw --with-dri-drivers=i965
+ make clean
+ make "$@"
+
+It is important that builds are both robust, and efficient. Due to broken
+dependency discovery in Mesa's makefile system, it was necessary invoke `make
+clean` in every iteration step. `ccache` should be installed to avoid
+recompiling unchanged source files.
+
+Then do:
+
+ cd /path/to/mesa
+ export LIBGL_DEBUG=verbose
+ export LD_LIBRARY_PATH=$PWD/lib
+ export LIBGL_DRIVERS_DIR=$PWD/lib
+ git bisect start \
+ 6491e9593d5cbc5644eb02593a2f562447efdcbb 71acbb54f49089b03d3498b6f88c1681d3f649ac \
+ -- src/mesa/drivers/dri/intel src/mesa/drivers/dri/i965/
+ git bisect run /path/to/tracecheck.py \
+ --precision-threshold 8.0 \
+ --build /path/to/build-script.sh \
+ --gl-renderer '.*Mesa.*Intel.*' \
+ --retrace=/path/to/glretrace \
+ -c /path/to/reference/snapshots/ \
+ topogun-1.06-orc-84k.trace
+
+The trace-check.py script will skip automatically when there are build
+failures.
+
+The `--gl-renderer` option will also cause a commit to be skipped if the
+`GL_RENDERER` is unexpected (e.g., when a software renderer or another GL
+driver is unintentionally loaded due to missing symbol in the DRI driver, or
+another runtime fault).
+
+
+Side by side retracing
+----------------------
+
+In order to determine which draw call a regression first manifests one could
+generate snapshots for every draw call, using the `-S` option. That is, however,
+very inefficient for big traces with many draw calls.
+
+A faster approach is to run both the bad and a good GL driver side-by-side.
+The latter can be either a previously known good build of the GL driver, or a
+reference software renderer.
+
+This can be achieved with retracediff.py script, which invokes glretrace with
+different environments, allowing to choose the desired GL driver by
+manipulating variables such as `LD_LIBRARY_PATH`, `LIBGL_DRIVERS_DIR`, or
+`TRACE_LIBGL`.
+
+For example, on Linux:
+
+ ./scripts/retracediff.py \
+ --ref-env LD_LIBRARY_PATH=/path/to/reference/GL/implementation \
+ --retrace /path/to/glretrace \
+ --diff-prefix=/path/to/output/diffs \
+ application.trace
+
+Or on Windows:
+
+ python scripts\retracediff.py --retrace \path\to\glretrace.exe --ref-env TRACE_LIBGL=\path\to\reference\opengl32.dll application.trace
+
+
+[![githalytics.com alpha](https://cruel-carlota.pagodabox.com/c1062ad633aa7a458e9d7520021307e4 "githalytics.com")](http://githalytics.com/apitrace/apitrace)
+
+Advanced GUI usage
+==================
+qapitrace has rudimentary support for replaying traces on a remote
+target device. This can be useful, for example, when developing for an
+embedded system. The primary GUI will run on the local host, while any
+replays will be performed on the target device.
+
+In order to target a remote device, use the command-line:
+
+ qapitrace --remote-target <HOST> <trace-file>
+
+In order for this to work, the following must be available in the
+system configuration:
+
+1. It must be possible for the current user to initiate an ssh session
+ that has access to the target's window system. The command to be
+ exectuted by qapitrace will be:
+
+ ssh <HOST> glretrace
+
+ For example, if the target device is using the X window system, one
+ can test whether an ssh session has access to the target X server
+ with:
+
+ ssh <HOST> xdpyinfo
+
+ If this command fails with something like "cannot open display"
+ then the user will have to configure the target to set the DISPLAY
+ environment variable, (for example, setting DISPLAY=:0 in the
+ .bashrc file on the target or similar).
+
+ Also, note that if the ssh session requires a custom username, then
+ this must be configured on the host side so that ssh can be
+ initiated without a username.
+
+ For example, if you normally connect with "ssh user@192.168.0.2"
+ you could configure ~/.ssh/config on the host with a block such as:
+
+ Host target
+ HostName 192.168.0.2
+ User user
+
+ And after this you should be able to connect with "ssh target" so
+ that you can also use "qapitrace --remote-target target".
+
+2. The target host must have a functional glretrace binary available
+
+3. The target host must have access to <trace-file> at the same path
+ in the filesystem as the <trace-file> path on the host system being
+ passed to the qapitrace command line.