<HTML> <TITLE>Development Notes</TITLE> <link rel="stylesheet" type="text/css" href="mesa.css"></head> <BODY> <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>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> <p> Create/edit the docs/relnotes-x.y.html file to document what's new in the release. Add the new relnotes-x.y.html file to <a href="relnotes.html">relnotes.html</a>. </p> <p> Update the MESA_MAJOR, MESA_MINOR and MESA_TINY version numbers in configs/default. Also update the VERSION line in the top-level Makefile. </p> <p> Make sure the values in src/mesa/main/version.h are correct. </p> <p> Update docs/news.html. </p> <p> Check in all updates to git. </p> <p> Tag the files with the release name (in the form <b>mesa_X_Y</b>) with: <code>git tag -a mesa_X_Y</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> 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> Follow the directions on SourceForge for creating a new "release" and uploading the tarballs. </p> <p> Basically, to upload the tarball files with: <br> <code> rsync -avP ssh Mesa*-X.Y.* USERNAME@frs.sourceforge.net:uploads/ </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> </body> </html>