mirror of https://gitlab.freedesktop.org/mesa/mesa
725 lines
23 KiB
HTML
725 lines
23 KiB
HTML
<!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="#style">Coding Style</a>
|
|
<li><a href="#submitting">Submitting Patches</a>
|
|
<li><a href="#release">Making a New Mesa Release</a>
|
|
<li><a href="#extensions">Adding Extensions</a>
|
|
</ul>
|
|
|
|
|
|
<h2 id="style">Coding Style</h2>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
Basic formatting guidelines
|
|
</p>
|
|
|
|
<ul>
|
|
<li>3-space indentation, no tabs.
|
|
<li>Limit lines to 78 or fewer characters. The idea is to prevent line
|
|
wrapping in 80-column editors and terminals. There are exceptions, such
|
|
as if you're defining a large, static table of information.
|
|
<li>Opening braces go on the same line as the if/for/while statement.
|
|
For example:
|
|
<pre>
|
|
if (condition) {
|
|
foo;
|
|
} else {
|
|
bar;
|
|
}
|
|
</pre>
|
|
|
|
<li>Put a space before/after operators. For example, <tt>a = b + c;</tt>
|
|
and not <tt>a=b+c;</tt>
|
|
|
|
<li>This GNU indent command generally does the right thing for formatting:
|
|
<pre>
|
|
indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
|
|
</pre>
|
|
|
|
<li>Use comments wherever you think it would be helpful for other developers.
|
|
Several specific cases and style examples follow. Note that we roughly
|
|
follow <a href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a> conventions.
|
|
<br>
|
|
<br>
|
|
Single-line comments:
|
|
<pre>
|
|
/* null-out pointer to prevent dangling reference below */
|
|
bufferObj = NULL;
|
|
</pre>
|
|
Or,
|
|
<pre>
|
|
bufferObj = NULL; /* prevent dangling reference below */
|
|
</pre>
|
|
Multi-line comment:
|
|
<pre>
|
|
/* If this is a new buffer object id, or one which was generated but
|
|
* never used before, allocate a buffer object now.
|
|
*/
|
|
</pre>
|
|
We try to quote the OpenGL specification where prudent:
|
|
<pre>
|
|
/* 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:
|
|
*
|
|
* * <length> 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.
|
|
*/
|
|
</pre>
|
|
Function comment example:
|
|
<pre>
|
|
/**
|
|
* 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 */
|
|
}
|
|
</pre>
|
|
|
|
<li>Put the function return type and qualifiers on one line and the function
|
|
name and parameters on the next, as seen above. This makes it easy to use
|
|
<code>grep ^function_name dir/*</code> to find function definitions. Also,
|
|
the opening brace goes on the next line by itself (see above.)
|
|
|
|
<li>Function names follow various conventions depending on the type of function:
|
|
<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>
|
|
|
|
<li>Constants, macros and enumerant names are ALL_UPPERCASE, with _ between
|
|
words.
|
|
<li>Mesa usually uses camel case for local variables (Ex: "localVarname")
|
|
while gallium typically uses underscores (Ex: "local_var_name").
|
|
<li>Global variables are almost never used because Mesa should be thread-safe.
|
|
|
|
<li>Booleans. 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.
|
|
|
|
</ul>
|
|
|
|
|
|
<h2 id="submitting">Submitting patches</h2>
|
|
|
|
<p>
|
|
The basic guidelines for submitting patches are:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>Patches should be sufficiently tested before submitting.
|
|
<li>Code patches should follow Mesa coding conventions.
|
|
<li>Whenever possible, patches should only effect individual Mesa/Gallium
|
|
components.
|
|
<li>Patches should never introduce build breaks and should be bisectable (see
|
|
<code>git bisect</code>.)
|
|
<li>Patches should be properly formatted (see below).
|
|
<li>Patches should be submitted to mesa-dev for review using
|
|
<code>git send-email</code>.
|
|
<li>Patches should not mix code changes with code formatting changes (except,
|
|
perhaps, in very trivial cases.)
|
|
</ul>
|
|
|
|
<h3>Patch formatting</h3>
|
|
|
|
<p>
|
|
The basic rules for patch formatting are:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>Lines should be limited to 75 characters or less so that git logs
|
|
displayed in 80-column terminals avoid line wrapping. Note that git
|
|
log uses 4 spaces of indentation (4 + 75 < 80).
|
|
<li>The first line should be a short, concise summary of the change prefixed
|
|
with a module name. Examples:
|
|
<pre>
|
|
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.
|
|
</pre>
|
|
<li>Subsequent patch comments should describe the change in more detail,
|
|
if needed. For example:
|
|
<pre>
|
|
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.
|
|
</pre>
|
|
<li>A "Signed-off-by:" line is not required, but not discouraged either.
|
|
<li>If a patch address a bugzilla issue, that should be noted in the
|
|
patch comment. For example:
|
|
<pre>
|
|
Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=89689
|
|
</pre>
|
|
<li>If there have been several revisions to a patch during the review
|
|
process, they should be noted such as in this example:
|
|
<pre>
|
|
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)
|
|
</pre>
|
|
<li>If someone tested your patch, document it with a line like this:
|
|
<pre>
|
|
Tested-by: Joe Hacker <jhacker@foo.com>
|
|
</pre>
|
|
<li>If the patch was reviewed (usually the case) or acked by someone,
|
|
that should be documented with:
|
|
<pre>
|
|
Reviewed-by: Joe Hacker <jhacker@foo.com>
|
|
Acked-by: Joe Hacker <jhacker@foo.com>
|
|
</pre>
|
|
</ul>
|
|
|
|
|
|
|
|
<h3>Testing Patches</h3>
|
|
|
|
<p>
|
|
It should go without saying that patches must be tested. In general,
|
|
do whatever testing is prudent.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
Whenever possible and applicable, test the patch with
|
|
<a href="http://piglit.freedesktop.org">Piglit</a> to
|
|
check for regressions.
|
|
</p>
|
|
|
|
|
|
<h3>Mailing Patches</h3>
|
|
|
|
<p>
|
|
Patches should be sent to the mesa-dev mailing list for review:
|
|
<a href="https://lists.freedesktop.org/mailman/listinfo/mesa-dev">
|
|
mesa-dev@lists.freedesktop.org<a/>.
|
|
When submitting a patch make sure to use
|
|
<a href="https://git-scm.com/docs/git-send-email">git send-email</a>
|
|
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>
|
|
|
|
<p>
|
|
When submitting follow-up patches you should also login to
|
|
<a href="https://patchwork.freedesktop.org">patchwork</a> and change the
|
|
state of your old patches to Superseded.
|
|
</p>
|
|
|
|
<h3>Reviewing Patches</h3>
|
|
|
|
<p>
|
|
When you've reviewed a patch on the mailing list, please be unambiguous
|
|
about your review. That is, state either
|
|
<pre>
|
|
Reviewed-by: Joe Hacker <jhacker@foo.com>
|
|
</pre>
|
|
or
|
|
<pre>
|
|
Acked-by: Joe Hacker <jhacker@foo.com>
|
|
</pre>
|
|
Rather than saying just "LGTM" or "Seems OK".
|
|
</p>
|
|
|
|
<p>
|
|
If small changes are suggested, it's OK to say something like:
|
|
<pre>
|
|
With the above fixes, Reviewed-by: Joe Hacker <jhacker@foo.com>
|
|
</pre>
|
|
which tells the patch author that the patch can be committed, as long
|
|
as the issues are resolved first.
|
|
</p>
|
|
|
|
|
|
<h3>Marking a commit as a candidate for a stable branch</h3>
|
|
|
|
<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.
|
|
|
|
<h3>Criteria for accepting patches to the stable branch</h3>
|
|
|
|
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 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>
|