docs/devinfo.html - platform/external/mesa3d - Gitiles

 <!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>
	<!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>