= How to bisect mesa =

== Prerequisites ==
Pull in packages needed for building mesa
{{{
sudo apt-get build-dep mesa
sudo apt-get install libx11-dev libxt-dev libxmu-dev libxi-dev
}}}

== Copy the mesa git repository ==
{{{
cd
git clone git://anongit.freedesktop.org/git/mesa/mesa
cd mesa/
}}}
That's like a 30MB download for you...

== Picking the good and the bad ==

Example: It worked in 7.6.0~git20090817.7c422387-0ubuntu8 (good version) but not in 7.6.0-1ubuntu1 (bad version).

As can be seen in its package version, the good version is identified by commit 7c422387. The 7.6.0 release can be identified with the "mesa_7_6" git tag (or with its corresponding commit 86cd188f).

Use "git log", "git show COMMIT" etc to identify commits, or browse them on http://cgit.freedesktop.org/mesa/mesa/

== Verify the "bad" build ==

We will first test the build with the "bad" version.
{{{
git checkout mesa_7_6
make clean
./autogen.sh
./configure --prefix=/usr --mandir=\${prefix}/share/man \
    --infodir=\${prefix}/share/info --sysconfdir=/etc \
    --localstatedir=/var --build=i486-linux-gnu --disable-gallium --with-driver=dri \
    --with-dri-drivers="r200 r300 radeon" --with-demos=xdemos --libdir=/usr/lib/glx \
    --with-dri-driverdir=/usr/lib/dri --enable-glx-tls --enable-driglx-direct --disable-egl \
    --disable-glu --disable-glut --disable-glw CFLAGS="-Wall -g -O2"
make
}}}
Now verify that the build process worked and that you can reproduce the bug, before starting the bisecting.
{{{
LD_LIBRARY_PATH="~/mesa/glx" LIBGL_DRIVERS_PATH="~/mesa/src/mesa/drivers/dri/radeon" your-test-program
}}}

 * Note 1: some of the configure options are probably not needed
 * Note 2: modify the "--with-dri-drivers" list if needed
 * Note 3: for debugging the -O2 flag is usually omitted to help gdb

== Start bisecting ==
{{{
git bisect start
git bisect bad mesa_7_6
git bisect good 7c422387
}}}
Now git will roll back to a place in the middle between these two commits, and you will have to test it and tell git how it worked.

== Build and test the current commit ==
{{{
make
}}}
If building a version fails, you might have to rerun the "make clean", autogen and configure commands above.

You can test this version with your test program:
{{{
LD_LIBRARY_PATH="~/mesa/glx" LIBGL_DRIVERS_PATH="~/mesa/src/mesa/drivers/dri/radeon" your-test-program
}}}

If the bug was present here tell git:
{{{
git bisect bad
}}}
otherwise tell git:
{{{
git bisect good
}}}
Accordingly, git will choose another commit. Go back to "make" and repeat this section until git has identified the single commit that introduced the issue.

== References ==
 * http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#using-bisect
 * http://dri.freedesktop.org/wiki/TestingAndDebugging