mirror of
https://gitlab.freedesktop.org/mesa/mesa.git
synced 2024-12-04 15:44:06 +08:00
259e65c03e
Signed-off-by: Emil Velikov <emil.velikov@collabora.com> Reviewed-by: Brian Paul <brianp@vmware.com>
323 lines
8.1 KiB
HTML
323 lines
8.1 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="#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>
|