Development Notes
Making a New Mesa Release
These are the instructions for making a new Mesa release.
Get latest source files
Use git to get the latest Mesa files from the git repository, from whatever branch is relevant. This document uses the convention X.Y.Z for the release being created, which should be created from a branch named X.Y.
Perform basic testing
The release manager should, at the very least, test the code by compiling it, installing it, and running the latest piglit to ensure that no piglit tests have regressed since the previous release.
The release manager should do this testing with at least one hardware driver, (say, whatever is contained in the local development machine), as well as on both Gallium and non-Gallium software drivers. The software testing can be performed by running piglit with the following environment-variable set:
LIBGL_ALWAYS_SOFTWARE=1And Gallium vs. non-Gallium software drivers can be obtained by using the following configure flags on separate builds:
--with-dri-drivers=swrast --with-gallium-drivers=swrast
Note: If both options are given in one build, both swrast_dri.so drivers will be compiled, but only one will be installed. The following command can be used to ensure the correct driver is being tested:
LIBGL_ALWAYS_SOFTWARE=1 glxinfo | grep "renderer string"If any regressions are found in this testing with piglit, stop here, and do not perform a release until regressions are fixed.
Update version in file VERSION
Increment the version contained in the file VERSION at Mesa's top-level, then commit this change.
Create release notes for the new release
Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous release notes). Note that the sha256sums section of the release notes should be empty at this point.
Two scripts are available to help generate portions of the release notes:
./bin/bugzilla_mesa.sh ./bin/shortlog_mesa.sh
The first script identifies commits that reference bugzilla bugs and obtains the descriptions of those bugs from bugzilla. The second script generates a log of all commits. In both cases, HTML-formatted lists are printed to stdout to be included in the release notes.
Commit these changes
Make the release archives, signatures, and the release tag
From inside the Mesa directory:
./autogen.sh make -j1 tarballs
After the tarballs are created, the sha256 checksums for the files will be computed and printed. These will be used in a step below.
It's important at this point to also verify that the constructed tar file actually builds:
tar xjf MesaLib-X.Y.Z.tar.bz2 cd Mesa-X.Y.Z ./configure --enable-gallium-llvm make -j6 make install
Some touch testing should also be performed at this point, (run glxgears or more involved OpenGL programs against the installed Mesa).
Create detached GPG signatures for each of the archive files created above:
gpg --sign --detach MesaLib-X.Y.Z.tar.gz gpg --sign --detach MesaLib-X.Y.Z.tar.bz2 gpg --sign --detach MesaLib-X.Y.Z.zip
Tag the commit used for the build:
git tag -s mesa-X.Y.X -m "Mesa X.Y.Z release"
Note: It would be nice to investigate and fix the issue that causes the tarballs target to fail with multiple build process, such as with "-j4". It would also be nice to incorporate all of the above commands into a single makefile target. And instead of a custom "tarballs" target, we should incorporate things into the standard "make dist" and "make distcheck" targets.
Add the sha256sums to the release notes
Edit docs/relnotes/X.Y.Z.html to add the sha256sums printed as part of "make tarballs" in the previous step. Commit this change.
Push all commits and the tag created above
This is the first step that cannot easily be undone. The release is going forward from this point:
git push origin X.Y --tags
Install the release files and signatures on the distribution server
The following commands can be used to copy the release archive files and signatures to the freedesktop.org server:
scp MesaLib-X.Y.Z* people.freedesktop.org: ssh people.freedesktop.org cd /srv/ftp.freedesktop.org/pub/mesa mkdir X.Y.Z cd X.Y.Z mv ~/MesaLib-X.Y.Z* .
Back on mesa master, add the new release notes into the tree
Something like the following steps will do the trick:
cp docs/relnotes/X.Y.Z.html /tmp git checkout master cp /tmp/X.Y.Z.html docs/relnotes git add docs/relnotes/X.Y.Z.html
Also, edit docs/relnotes.html to add a link to the new release notes, and edit docs/index.html to add a news entry. Then commit and push:
git commit -a -m "docs: Import X.Y.Z release notes, add news item." git push origin
Update the mesa3d.org website
NOTE: The recent release managers have not been performing this step themselves, but leaving this to Brian Paul, (who has access to the sourceforge.net hosting for mesa3d.org). Brian is more than willing to grant the permission necessary to future release managers to do this step on their own.
Update the web site by copying the docs/ directory's files to
/home/users/b/br/brianp/mesa-www/htdocs/ with:
sftp USERNAME,mesa3d@web.sourceforge.net
Announce the release
Make an announcement on the mailing lists: mesa-dev@lists.freedesktop.org, and mesa-announce@lists.freedesktop.org Follow the template of previously-sent release announcements. The following command can be used to generate the log of changes to be included in the release announcement:
git shortlog mesa-X.Y.Z-1..mesa-X.Y.Z
Adding Extensions
To add a new GL extension to Mesa you have to do at least the following.
-
If glext.h doesn't define the extension, edit include/GL/gl.h and add
code like this:
#ifndef GL_EXT_the_extension_name #define GL_EXT_the_extension_name 1 /* declare the new enum tokens */ /* prototype the new functions */ /* TYPEDEFS for the new functions */ #endif
- In the src/mapi/glapi/gen/ directory, add the new extension functions and enums to the gl_API.xml file. Then, a bunch of source files must be regenerated by executing the corresponding Python scripts.
-
Add a new entry to the
gl_extensions
struct in mtypes.h if the extension requires driver capabilities not already exposed by another extension. - Add a new entry to the src/mesa/main/extensions_table.h file.
- From this point, the best way to proceed is to find another extension, similar to the new one, that's already implemented in Mesa and use it as an example.
- If the new extension adds new GL state, the functions in get.c, enable.c and attrib.c will most likely require new code.
- To determine if the new extension is active in the current context, use the auto-generated _mesa_has_##name_str() function defined in src/mesa/main/extensions.h.
- The dispatch tests check_table.cpp and dispatch_sanity.cpp should be updated with details about the new extensions functions. These tests are run using 'make check'