| <!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> |
| |
| |
| <ul> |
| <li><a href="#release">Making a New Mesa Release</a> |
| <li><a href="#extensions">Adding Extensions</a> |
| </ul> |
| |
| <h2 id="release">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 created 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, add 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> |
| |
| |
| <h2 id="extensions">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 |
| if the extension requires driver capabilities not already exposed by |
| another extension. |
| </li> |
| <li> |
| Add a new entry to the src/mesa/main/extensions_table.h 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> |
| 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. |
| </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> |
| </p> |
| |
| |
| |
| |
| </div> |
| </body> |
| </html> |