0,0 → 1,548 |
<!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> |