| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html lang="en"> |
| <head> |
| <meta http-equiv="content-type" content="text/html; charset=utf-8"> |
| <title>Development Notes</title> |
| <link rel="stylesheet" type="text/css" href="mesa.css"> |
| </head> |
| <body> |
| |
| <div class="header"> |
| <h1>The Mesa 3D Graphics Library</h1> |
| </div> |
| |
| <iframe src="contents.html"></iframe> |
| <div class="content"> |
| |
| <h1>Development Notes</h1> |
| |
| |
| <h2>Adding Extensions</h2> |
| |
| <p> |
| To add a new GL extension to Mesa you have to do at least the following. |
| |
| <ul> |
| <li> |
| If glext.h doesn't define the extension, edit include/GL/gl.h and add |
| code like this: |
| <pre> |
| #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 |
| </pre> |
| </li> |
| <li> |
| 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. |
| </li> |
| <li> |
| Add a new entry to the <code>gl_extensions</code> struct in mtypes.h |
| </li> |
| <li> |
| Update the <code>extensions.c</code> file. |
| </li> |
| <li> |
| 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. |
| </li> |
| <li> |
| If the new extension adds new GL state, the functions in get.c, enable.c |
| and attrib.c will most likely require new code. |
| </li> |
| <li> |
| 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' |
| </li> |
| </ul> |
| |
| |
| |
| <h2>Coding Style</h2> |
| |
| <p> |
| Mesa's code style has changed over the years. Here's the latest. |
| </p> |
| |
| <p> |
| Comment your code! It's extremely important that open-source code be |
| well documented. Also, strive to write clean, easily understandable code. |
| </p> |
| |
| <p> |
| 3-space indentation |
| </p> |
| |
| <p> |
| If you use tabs, set them to 8 columns |
| </p> |
| |
| <p> |
| 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). |
| </p> |
| |
| <p> |
| Brace example: |
| </p> |
| <pre> |
| if (condition) { |
| foo; |
| } |
| else { |
| bar; |
| } |
| |
| switch (condition) { |
| case 0: |
| foo(); |
| break; |
| |
| case 1: { |
| ... |
| break; |
| } |
| |
| default: |
| ... |
| break; |
| } |
| </pre> |
| |
| <p> |
| 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) |
| </p> |
| <pre> |
| indent -br -i3 -npcs --no-tabs infile.c -o outfile.c |
| </pre> |
| |
| |
| <p> |
| Local variable name example: localVarName (no underscores) |
| </p> |
| |
| <p> |
| Constants and macros are ALL_UPPERCASE, with _ between words |
| </p> |
| |
| <p> |
| Global variables are not allowed. |
| </p> |
| |
| <p> |
| Function name examples: |
| </p> |
| <pre> |
| 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 |
| </pre> |
| |
| <p> |
| Places that are not directly visible to the GL API should prefer the use |
| of <tt>bool</tt>, <tt>true</tt>, and |
| <tt>false</tt> over <tt>GLboolean</tt>, <tt>GL_TRUE</tt>, and |
| <tt>GL_FALSE</tt>. In C code, this may mean that |
| <tt>#include <stdbool.h></tt> needs to be added. The |
| <tt>try_emit_</tt>* methods in src/mesa/program/ir_to_mesa.cpp and |
| src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples. |
| </p> |
| |
| <h2>Submitting patches</h2> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| 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. |
| </p> |
| |
| <h2>Marking a commit as a candidate for a stable branch</h2> |
| |
| <p> |
| If you want a commit to be applied to a stable branch, |
| you should add an appropriate note to the commit message. |
| </p> |
| |
| <p> |
| Here are some examples of such a note: |
| </p> |
| <ul> |
| <li>CC: <mesa-stable@lists.freedesktop.org></li> |
| <li>CC: "9.2 10.0" <mesa-stable@lists.freedesktop.org></li> |
| <li>CC: "10.0" <mesa-stable@lists.freedesktop.org></li> |
| </ul> |
| |
| Simply adding the CC to the mesa-stable list address is adequate to nominate |
| the commit for the most-recently-created stable branch. It is only necessary |
| to specify a specific branch name, (such as "9.2 10.0" or "10.0" in the |
| examples above), if you want to nominate the commit for an older stable |
| branch. And, as in these examples, you can nominate the commit for the older |
| branch in addition to the more recent branch, or nominate the commit |
| exclusively for the older branch. |
| |
| This "CC" syntax for patch nomination will cause patches to automatically be |
| copied to the mesa-stable@ mailing list when you use "git send-email" to send |
| patches to the mesa-dev@ mailing list. Also, if you realize that a commit |
| should be nominated for the stable branch after it has already been committed, |
| 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). |
| |
| The latest set of patches that have been nominated, accepted, or rejected for |
| the upcoming stable release can always be seen on the |
| <a href="http://cworth.org/~cworth/mesa-stable-queue/">Mesa Stable Queue</a> |
| page. |
| |
| <h2>Criteria for accepting patches to the stable branch</h2> |
| |
| Mesa has a designated release manager for each stable branch, and the release |
| manager is the only developer that should be pushing changes to these |
| branches. Everyone else should simply nominate patches using the mechanism |
| described above. |
| |
| The stable-release manager will work with the list of nominated patches, and |
| for each patch that meets the crtieria below will cherry-pick the patch with: |
| <code>git cherry-pick -x <commit></code>. The <code>-x</code> 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: |
| |
| <ul> |
| <li>Patch introduces a regression. Any reported build breakage or other |
| regression caused by a particular patch, (game no longer work, piglit test |
| changes from PASS to FAIL), is justification for rejecting a patch.</li> |
| |
| <li>Patch is too large, (say, larger than 100 lines)</li> |
| |
| <li>Patch is not a fix. For example, a commit that moves code around with no |
| functional change should be rejected.</li> |
| |
| <li>Patch fix is not clearly described. For example, a commit message |
| of only a single line, no description of the bug, no mention of bugzilla, |
| etc.</li> |
| |
| <li>Patch has not obviously been reviewed, For example, the commit message |
| has no Reviewed-by, Signed-off-by, nor Tested-by tags from anyone but the |
| author.</li> |
| |
| <li>Patch has not already been merged to the master branch. As a rule, bug |
| fixes should never be applied first to a stable branch. Patches should land |
| first on the master branch and then be cherry-picked to a stable |
| branch. (This is to avoid future releases causing regressions if the patch |
| is not also applied to master.) The only things that might look like |
| exceptions would be backports of patches from master that happen to look |
| significantly different.</li> |
| |
| <li>Patch depends on too many other patches. Ideally, all stable-branch |
| patches should be self-contained. It sometimes occurs that a single, logical |
| bug-fix occurs as two separate patches on master, (such as an original |
| patch, then a subsequent fix-up to that patch). In such a case, these two |
| patches should be squashed into a single, self-contained patch for the |
| stable branch. (Of course, if the squashing makes the patch too large, then |
| that could be a reason to reject the patch.)</li> |
| |
| <li>Patch includes new feature development, not bug fixes. New OpenGL |
| features, extensions, etc. should be applied to Mesa master and included in |
| the next major release. Stable releases are intended only for bug fixes. |
| |
| Note: As an exception to this rule, the stable-release manager may accept |
| hardware-enabling "features". For example, backports of new code to support |
| a newly-developed hardware product can be accepted if they can be reasonably |
| determined to not have effects on other hardware.</li> |
| |
| <li>Patch is a performance optimization. As a rule, performance patches are |
| not candidates for the stable branch. The only exception might be a case |
| where an application's performance was recently severely impacted so as to |
| become unusable. The fix for this performance regression could then be |
| considered for a stable branch. The optimization must also be |
| non-controversial and the patches still need to meet the other criteria of |
| being simple and self-contained</li> |
| |
| <li>Patch introduces a new failure mode (such as an assert). While the new |
| assert might technically be correct, for example to make Mesa more |
| conformant, this is not the kind of "bug fix" we want in a stable |
| release. The potential problem here is that an OpenGL program that was |
| previously working, (even if technically non-compliant with the |
| specification), could stop working after this patch. So that would be a |
| regression that is unaacceptable for the stable branch.</li> |
| </ul> |
| |
| <h2>Making a New Mesa Release</h2> |
| |
| <p> |
| These are the instructions for making a new Mesa release. |
| </p> |
| |
| <h3>Get latest source files</h3> |
| <p> |
| 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. |
| </p> |
| |
| <h3>Perform basic testing</h3> |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| 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: |
| </p> |
| |
| <pre> |
| LIBGL_ALWAYS_SOFTWARE=1 |
| </pre> |
| |
| And Gallium vs. non-Gallium software drivers can be obtained by using the |
| following configure flags on separate builds: |
| |
| <pre> |
| --with-dri-drivers=swrast |
| --with-gallium-drivers=swrast |
| </pre> |
| |
| <p> |
| 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: |
| </p> |
| |
| <pre> |
| LIBGL_ALWAYS_SOFTWARE=1 glxinfo | grep "renderer string" |
| </pre> |
| |
| If any regressions are found in this testing with piglit, stop here, and do |
| not perform a release until regressions are fixed. |
| |
| <h3>Update version in file VERSION</h3> |
| |
| <p> |
| Increment the version contained in the file VERSION at Mesa's top-level, then |
| commit this change. |
| </p> |
| |
| <h3>Create release notes for the new release</h3> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| Two scripts are available to help generate portions of the release notes: |
| |
| <pre> |
| ./bin/bugzilla_mesa.sh |
| ./bin/shortlog_mesa.sh |
| </pre> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| Commit these changes |
| </p> |
| |
| <h3>Make the release archives, signatures, and the release tag</h3> |
| <p> |
| From inside the Mesa directory: |
| <pre> |
| ./autogen.sh |
| make -j1 tarballs |
| </pre> |
| |
| <p> |
| After the tarballs are created, the sha256 checksums for the files will |
| be computed and printed. These will be used in a step below. |
| </p> |
| |
| <p> |
| It's important at this point to also verify that the constructed tar file |
| actually builds: |
| </p> |
| |
| <pre> |
| tar xjf MesaLib-X.Y.Z.tar.bz2 |
| cd Mesa-X.Y.Z |
| ./configure --enable-gallium-llvm |
| make -j6 |
| make install |
| </pre> |
| |
| <p> |
| Some touch testing should also be performed at this point, (run glxgears or |
| more involved OpenGL programs against the installed Mesa). |
| </p> |
| |
| <p> |
| Create detached GPG signatures for each of the archive files created above: |
| </p> |
| |
| <pre> |
| 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 |
| </pre> |
| |
| <p> |
| Tag the commit used for the build: |
| </p> |
| |
| <pre> |
| git tag -s mesa-X.Y.X -m "Mesa X.Y.Z release" |
| </pre> |
| |
| <p> |
| 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. |
| </p> |
| |
| <h3>Add the sha256sums to the release notes</h3> |
| |
| <p> |
| Edit docs/relnotes/X.Y.Z.html to add the sha256sums printed as part of "make |
| tarballs" in the previous step. Commit this change. |
| </p> |
| |
| <h3>Push all commits and the tag creates above</h3> |
| |
| <p> |
| This is the first step that cannot easily be undone. The release is going |
| forward from this point: |
| </p> |
| |
| <pre> |
| git push origin X.Y --tags |
| </pre> |
| |
| <h3>Install the release files and signatures on the distribution server</h3> |
| |
| <p> |
| The following commands can be used to copy the release archive files and |
| signatures to the freedesktop.org server: |
| </p> |
| |
| <pre> |
| 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* . |
| </pre> |
| |
| <h3>Back on mesa master, andd the new release notes into the tree</h3> |
| |
| <p> |
| Something like the following steps will do the trick: |
| </p> |
| |
| <pre> |
| 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 |
| </pre> |
| |
| <p> |
| 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: |
| </p> |
| |
| <pre> |
| git commit -a -m "docs: Import X.Y.Z release notes, add news item." |
| git push origin |
| </pre> |
| |
| <h3>Update the mesa3d.org website</h3> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| Update the web site by copying the docs/ directory's files to |
| /home/users/b/br/brianp/mesa-www/htdocs/ with: |
| <br> |
| <code> |
| sftp USERNAME,mesa3d@web.sourceforge.net |
| </code> |
| </p> |
| |
| |
| <h3>Announce the release</h3> |
| <p> |
| Make an announcement on the mailing lists: |
| |
| <em>mesa-dev@lists.freedesktop.org</em>, |
| and |
| <em>mesa-announce@lists.freedesktop.org</em> |
| |
| 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: |
| |
| <pre> |
| git shortlog mesa-X.Y.Z-1..mesa-X.Y.Z |
| </pre> |
| </p> |
| |
| </div> |
| </body> |
| </html> |