Development Notes
-Development Notes
- -Adding Extentions
+Adding Extensions
To add a new GL extension to Mesa you have to do at least the following. @@ -28,7 +36,7 @@ To add a new GL extension to Mesa you have to do at least the following.
Coding Style
+Coding Style
Mesa's code style has changed over the years. Here's the latest. @@ -71,6 +79,13 @@ well documented. Also, strive to write clean, easily understandable code. If you use tabs, set them to 8 columns
++Line width: the preferred width to fill comments and code in Mesa is 78 +columns. Exceptions are sometimes made for clarity (e.g. tabular data is +sometimes filled to a much larger width so that extraneous carriage returns +don't obscure the table). +
+Brace example:
@@ -81,10 +96,26 @@ Brace example: else { bar; } + + switch (condition) { + case 0: + foo(); + break; + + case 1: { + ... + break; + } + + default: + ... + break; + }Here's the GNU indent command which will best approximate my preferred style: +(Note that it won't format switch statements in the preferred way)
indent -br -i3 -npcs --no-tabs infile.c -o outfile.c @@ -107,77 +138,131 @@ Global variables are not allowed. Function name examples:- glFooBar() - a public GL entry point (in dispatch.c) + glFooBar() - a public GL entry point (in glapi_dispatch.c) _mesa_FooBar() - the internal immediate mode function save_FooBar() - retained mode (display list) function in dlist.c foo_bar() - a static (private) function _mesa_foo_bar() - an internal non-static Mesa function++Places that are not directly visible to the GL API should prefer the use +of bool, true, and +false over GLboolean, GL_TRUE, and +GL_FALSE. In C code, this may mean that +#include <stdbool.h> needs to be added. The +try_emit_* methods in src/mesa/program/ir_to_mesa.cpp and +src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples. +
-Making a New Mesa Release
+Submitting patches
-These are the instructions for making a new Mesa release. +You should always run the Mesa Testsuite before submitting patches. +The Testsuite can be run using the 'make check' command. All tests +must pass before patches will be accepted, this may mean you have +to update the tests themselves.
-Get latest source files
-Use "cvs update -dAP " to get the latest Mesa files from CVS. +Patches should be sent to the Mesa mailing list for review. +When submitting a patch make sure to use git send-email rather than attaching +patches to emails. Sending patches as attachments prevents people from being +able to provide in-line review comments.
- -Verify and update version info
-Create/edit the docs/RELNOTES-X.Y file to document what's new in the release. -Add the new RELNOTES-X.Y file to relnotes.html. -Update the docs/VERSIONS file too. +When submitting follow-up patches you can use --in-reply-to to make v2, v3, +etc patches show up as replies to the originals. This usually works well +when you're sending out updates to individual patches (as opposed to +re-sending the whole series). Using --in-reply-to makes +it harder for reviewers to accidentally review old patches.
+Marking a commit as a candidate for a stable branch
+-Edit the MESA_MAJOR, MESA_MINOR and MESA_TINY version numbers in -configs/default. +If you want a commit to be applied to a stable branch, +you should add an appropriate note to the commit message.
-Make sure the values in src/mesa/main/version.h are correct. +Here are some examples of such a note:
+
-
+
- CC: <mesa-stable@lists.freedesktop.org> +
- CC: "9.2 10.0" <mesa-stable@lists.freedesktop.org> +
- CC: "10.0" <mesa-stable@lists.freedesktop.org> +
Cherry-picking candidates for a stable branch
-Edit the top-level Makefile and verify that DIRECTORY, LIB_NAME and
-DEMO_NAME are correct.
+Please use git cherry-pick -x <commit> for cherry-picking a commit
+from master to a stable branch.
Making a New Mesa Release
+-Update the docs/news.html file and docs/download.html files. +These are the instructions for making a new Mesa release.
+Get latest source files
-Check in all updates to CVS. +Use git to get the latest Mesa files from the git repository, from whatever +branch is relevant.
+ +Verify and update version info in VERSION
+-Tag the CVS files with the release name (in the form mesa_X_Y). +Create a docs/relnotes/x.y.z.html file. +The bin/bugzilla_mesa.sh and bin/shortlog_mesa.sh scripts can be used to +create the HTML-formatted lists of bugfixes and changes to include in the file. +Link the new docs/relnotes/x.y.z.html file into the main relnotes.html file.
++Update docs/index.html. +
-Make the tarballs
-Make a symbolic link from $(DIRECTORY) to 'Mesa'. For example,
-ln -s Mesa Mesa-6.3
-This is needed in order to make a correct tar file in the next step.
+Tag the files with the release name (in the form mesa-x.y)
+with: git tag -s mesa-x.y -m "Mesa x.y Release"
+Then: git push origin mesa-x.y
Make the tarballs
Make the distribution files. From inside the Mesa directory:
+ ./autogen.sh make tarballs
After the tarballs are created, the md5 checksums for the files will be computed. -Add them to the docs/news.html file. +Add them to the docs/relnotes/x.y.html file.
@@ -185,26 +270,41 @@ Copy the distribution files to a temporary directory, unpack them, compile everything, and run some demos to be sure everything works.
-Update the website and announce the release
+Update the website and announce the release
+
+Make a new directory for the release on annarchy.freedesktop.org with:
+
+
+mkdir /srv/ftp.freedesktop.org/pub/mesa/x.y
+
+
-Follow the directions on SourceForge for creating a new "release" and
-uploading the tarballs.
+Basically, to upload the tarball files with:
+
+
+rsync -avP -e ssh MesaLib-x.y.* USERNAME@annarchy.freedesktop.org:/srv/ftp.freedesktop.org/pub/mesa/x.y/
+
Update the web site by copying the docs/ directory's files to
-/home/users/b/br/brianp/mesa-www/htdocs/
+/home/users/b/br/brianp/mesa-www/htdocs/ with:
+
+
+sftp USERNAME,mesa3d@web.sourceforge.net
+
Make an announcement on the mailing lists: -mesa3d-dev@lists.sf.net, -mesa3d-users@lists.sf.net + +mesa-dev@lists.freedesktop.org, +mesa-users@lists.freedesktop.org and -mesa3d-announce@lists.sf.net +mesa-announce@lists.freedesktop.org
- - +