| <!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 Extentions</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/mesa/glapi/ 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> |
| </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>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>NOTE: This is a candidate for the 9.0 branch.</li> |
| <li>NOTE: This is a candidate for the 8.0 and 9.0 branches.</li> |
| <li>NOTE: This is a candidate for the stable branches.</li> |
| </ul> |
| |
| |
| <h2>Cherry-picking candidates for a stable branch</h2> |
| |
| <p> |
| Please use <code>git cherry-pick -x <commit></code> for cherry-picking a commit |
| from master to a stable branch. |
| </p> |
| |
| <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. |
| </p> |
| |
| |
| <h3>Verify and update version info</h3> |
| |
| <dl> |
| <dt>SConstruct</dt> |
| <dt>Android.common.mk</dt> |
| <dd>PACKAGE_VERSION</dd> |
| <dt>configure.ac</dt> |
| <dd>AC_INIT</dd> |
| </dl> |
| |
| <p> |
| Create a docs/relnotes/x.y.z.html file. |
| The bin/bugzilla_mesa.sh and bin/shortlog_mesa.sh scripts can be used to |
| create the HTML-formatted lists of bugfixes and changes to include in the file. |
| Link the new docs/relnotes/x.y.z.html file into the main <a href="relnotes.html">relnotes.html</a> file. |
| </p> |
| |
| <p> |
| Update <a href="index.html">docs/index.html</a>. |
| </p> |
| |
| <p> |
| Tag the files with the release name (in the form <b>mesa-x.y</b>) |
| with: <code>git tag -s mesa-x.y -m "Mesa x.y Release"</code> |
| Then: <code>git push origin mesa-x.y</code> |
| </p> |
| |
| |
| <h3>Make the tarballs</h3> |
| <p> |
| Make the distribution files. From inside the Mesa directory: |
| <pre> |
| ./autogen.sh |
| make tarballs |
| </pre> |
| |
| <p> |
| After the tarballs are created, the md5 checksums for the files will |
| be computed. |
| Add them to the docs/relnotes/x.y.html file. |
| </p> |
| |
| <p> |
| Copy the distribution files to a temporary directory, unpack them, |
| compile everything, and run some demos to be sure everything works. |
| </p> |
| |
| <h3>Update the website and announce the release</h3> |
| <p> |
| Make a new directory for the release on annarchy.freedesktop.org with: |
| <br> |
| <code> |
| mkdir /srv/ftp.freedesktop.org/pub/mesa/x.y |
| </code> |
| </p> |
| |
| <p> |
| Basically, to upload the tarball files with: |
| <br> |
| <code> |
| rsync -avP -e ssh MesaLib-x.y.* USERNAME@annarchy.freedesktop.org:/srv/ftp.freedesktop.org/pub/mesa/x.y/ |
| </code> |
| </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> |
| |
| <p> |
| Make an announcement on the mailing lists: |
| |
| <em>m</em><em>e</em><em>s</em><em>a</em><em>-</em><em>d</em><em>e</em><em>v</em><em>@</em><em>l</em><em>i</em><em>s</em><em>t</em><em>s</em><em>.</em><em>f</em><em>r</em><em>e</em><em>e</em><em>d</em><em>e</em><em>s</em><em>k</em><em>t</em><em>o</em><em>p</em><em>.</em><em>o</em><em>r</em><em>g</em>, |
| <em>m</em><em>e</em><em>s</em><em>a</em><em>-</em><em>u</em><em>s</em><em>e</em><em>r</em><em>s</em><em>@</em><em>l</em><em>i</em><em>s</em><em>t</em><em>s</em><em>.</em><em>f</em><em>r</em><em>e</em><em>e</em><em>d</em><em>e</em><em>s</em><em>k</em><em>t</em><em>o</em><em>p</em><em>.</em><em>o</em><em>r</em><em>g</em> |
| and |
| <em>m</em><em>e</em><em>s</em><em>a</em><em>-</em><em>a</em><em>n</em><em>n</em><em>o</em><em>u</em><em>n</em><em>c</em><em>e</em><em>@</em><em>l</em><em>i</em><em>s</em><em>t</em><em>s</em><em>.</em><em>f</em><em>r</em><em>e</em><em>e</em><em>d</em><em>e</em><em>s</em><em>k</em><em>t</em><em>o</em><em>p</em><em>.</em><em>o</em><em>r</em><em>g</em> |
| </p> |
| |
| </div> |
| </body> |
| </html> |
