-To add a new GL extension to Mesa you have to do at least the following. -
- #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 --
gl_extensions struct in mtypes.h
-extensions.c file.
--Mesa's code style has changed over the years. Here's the latest. +Mesa is over 20 years old and the coding style has evolved over time. +Some old parts use a style that's a bit out of date. +If the guidelines below don't cover something, try following the format of +existing, neighboring code.
-Comment your code! It's extremely important that open-source code be -well documented. Also, strive to write clean, easily understandable code. +Basic formatting guidelines
--3-space indentation -
+
+ if (condition) {
+ foo;
+ } else {
+ bar;
+ }
+
--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). -
++ indent -br -i3 -npcs --no-tabs infile.c -o outfile.c +-
-Brace example: -
+
- if (condition) {
- foo;
- }
- else {
- bar;
- }
-
- switch (condition) {
- case 0:
- foo();
- break;
-
- case 1: {
- ...
- break;
- }
-
- default:
- ...
- break;
- }
+ /* null-out pointer to prevent dangling reference below */
+ bufferObj = NULL;
+
+Or,
++ bufferObj = NULL; /* prevent dangling reference below */ ++Multi-line comment: +
+ /* If this is a new buffer object id, or one which was generated but + * never used before, allocate a buffer object now. + */ ++We try to quote the OpenGL specification where prudent: +
+ /* Page 38 of the PDF of the OpenGL ES 3.0 spec says: + * + * "An INVALID_OPERATION error is generated for any of the following + * conditions: + * + * *+Function comment example: +is zero." + * + * Additionally, page 94 of the PDF of the OpenGL 4.5 core spec + * (30.10.2014) also says this, so it's no longer allowed for desktop GL, + * either. + */ +
+ /**
+ * Create and initialize a new buffer object. Called via the
+ * ctx->Driver.CreateObject() driver callback function.
+ * \param name integer name of the object
+ * \param type one of GL_FOO, GL_BAR, etc.
+ * \return pointer to new object or NULL if error
+ */
+ struct gl_object *
+ _mesa_create_object(GLuint name, GLenum type)
+ {
+ /* function body */
+ }
--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) -
+grep ^function_name dir/* to find function definitions. Also,
+the opening brace goes on the next line by itself (see above.)
+
+- indent -br -i3 -npcs --no-tabs infile.c -o outfile.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+
-Local variable name example: localVarName (no underscores) -
+-Constants and macros are ALL_UPPERCASE, with _ between words -
+ +-Global variables are not allowed. +The basic guidelines for submitting patches are:
+git bisect.)
+git send-email.
+-Function name examples: +The basic rules for patch formatting are:
+ ++ mesa: Add support for querying GL_VERTEX_ATTRIB_ARRAY_LONG + + gallium: add PIPE_CAP_DEVICE_RESET_STATUS_QUERY + + i965: Fix missing type in local variable declaration. ++
+ i965: Remove end-of-thread SEND alignment code. + + This was present in Eric's initial implementation of the compaction code + for Sandybridge (commit 077d01b6). There is no documentation saying this + is necessary, and removing it causes no regressions in piglit on any + platform. ++
+ Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=89689 ++
+ st/mesa: add ARB_texture_stencil8 support (v4) + + if we support stencil texturing, enable texture_stencil8 + there is no requirement to support native S8 for this, + the texture can be converted to x24s8 fine. + + v2: fold fixes from Marek in: + a) put S8 last in the list + b) fix renderable to always test for d/s renderable + fixup the texture case to use a stencil only format + for picking the format for the texture view. + v3: hit fallback for getteximage + v4: put s8 back in front, it shouldn't get picked now (Ilia) ++
+ Tested-by: Joe Hacker <jhacker@foo.com> ++
- 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 + Reviewed-by: Joe Hacker <jhacker@foo.com> + Acked-by: Joe Hacker <jhacker@foo.com>+
-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. +It should go without saying that patches must be tested. In general, +do whatever testing is prudent.
--You should always run the Mesa Testsuite before submitting patches. -The Testsuite can be run using the 'make check' command. All tests +You should always run the Mesa test suite before submitting patches. +The test suite 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.
++Whenever possible and applicable, test the patch with +Piglit to +check for regressions. +
+ + +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 @@ -179,7 +266,38 @@ re-sending the whole series). Using --in-reply-to makes it harder for reviewers to accidentally review old patches.
-+When submitting follow-up patches you should also login to +patchwork and change the +state of your old patches to Superseded. +
+ ++When you've reviewed a patch on the mailing list, please be unambiguous +about your review. That is, state either +
+ Reviewed-by: Joe Hacker <jhacker@foo.com> ++or +
+ Acked-by: Joe Hacker <jhacker@foo.com> ++Rather than saying just "LGTM" or "Seems OK". + + +
+If small changes are suggested, it's OK to say something like: +
+ With the above fixes, Reviewed-by: Joe Hacker <jhacker@foo.com> ++which tells the patch author that the patch can be committed, as long +as the issues are resolved first. + + + +
If you want a commit to be applied to a stable branch, @@ -211,14 +329,98 @@ you can send a note directly to the mesa-stable@lists.freedesktop.org where the Mesa stable-branch maintainers will receive it. Be sure to mention the commit ID of the commit of interest (as it appears in the mesa master branch). -
-Please use git cherry-pick -x <commit> for cherry-picking a commit
-from master to a stable branch.
-
git cherry-pick -x <commit>. The -x option is
+important so that the picked patch references the comit ID of the original
+patch.
+
+The stable-release manager may at times need to force-push changes to the
+stable branches, for example, to drop a previously-picked patch that was later
+identified as causing a regression). These force-pushes may cause changes to
+be lost from the stable branch if developers push things directly. Consider
+yourself warned.
+
+The stable-release manager is also given broad discretion in rejecting patches
+that have been nominated for the stable branch. The most basic rule is that
+the stable branch is for bug fixes only, (no new features, no
+regressions). Here is a non-exhaustive list of some reasons that a patch may
+be rejected:
+
+These are the instructions for making a new Mesa release. @@ -227,64 +429,205 @@ These are the instructions for making a new Mesa release.
Use git to get the latest Mesa files from the git repository, from whatever -branch is relevant. +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. +
+ ++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=1 ++ +And 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. -
-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. +Increment the version contained in the file VERSION at Mesa's top-level, then +commit this change.
+-Update docs/index.html. +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.
-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
+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 distribution files. From inside the Mesa directory: +From inside the Mesa directory:
./autogen.sh - make tarballs + make -j1 tarballs
-After the tarballs are created, the md5 checksums for the files will -be computed. -Add them to the docs/relnotes/x.y.html file. +After the tarballs are created, the sha256 checksums for the files will +be computed and printed. These will be used in a step below.
-Copy the distribution files to a temporary directory, unpack them, -compile everything, and run some demos to be sure everything works. +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 ++
-Make a new directory for the release on annarchy.freedesktop.org with:
-
-
-mkdir /srv/ftp.freedesktop.org/pub/mesa/x.y
-
+Some touch testing should also be performed at this point, (run glxgears or
+more involved OpenGL programs against the installed Mesa).
-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/
-
+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. +
+ ++Edit docs/relnotes/X.Y.Z.html to add the sha256sums printed as part of "make +tarballs" in the previous step. Commit this change. +
+ ++This is the first step that cannot easily be undone. The release is going +forward from this point: +
+ ++ git push origin X.Y --tags ++ +
+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* . ++ +
+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 ++ +
+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.
@@ -296,15 +639,74 @@ sftp USERNAME,mesa3d@web.sourceforge.net
+ +Make an announcement on the mailing lists: mesa-dev@lists.freedesktop.org, -mesa-users@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 ++ +
+To add a new GL extension to Mesa you have to do at least the following. + +
+ #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 ++
gl_extensions struct in mtypes.h
+extensions.c file.
+