# The Mesa 3D Graphics Library

# Development Notes

## Adding Extentions

To add a new GL extension to Mesa you have to do at least the following.

- If glext.h doesn't define the extension, edit include/GL/gl.h and add code like this:

           #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

- 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.
- Add a new entry to the `gl_extensions` struct in mtypes.h
- Update the `extensions.c` file.
- 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.
- If the new extension adds new GL state, the functions in get.c, enable.c and attrib.c will most likely require new code.

## Coding Style

Mesa's code style has changed over the years. Here's the latest.

Comment your code! It's extremely important that open-source code be well documented. Also, strive to write clean, easily understandable code.

3-space indentation

If you use tabs, set them to 8 columns

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).

Brace example:

    	if (condition) {
    	   foo;
    	}
    	else {
    	   bar;
    	}

    	switch (condition) {
    	case 0:
    	   foo();
    	   break;

    	case 1: {
    	   ...
    	   break;
    	}

    	default:
    	   ...
    	   break;
    	}

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)

    	indent -br -i3 -npcs --no-tabs infile.c -o outfile.c

Local variable name example: localVarName (no underscores)

Constants and macros are ALL_UPPERCASE, with _ between words

Global variables are not allowed.

Function name examples:

    	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

Places that are not directly visible to the GL API should prefer the use of `bool`, `true`, and `false` over `GLboolean`, `GL_TRUE`, and `GL_FALSE`. In C code, this may mean that `#include <stdbool.h>` needs to be added. The `try_emit_`* methods in src/mesa/program/ir_to_mesa.cpp and src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples.

## Marking a commit as a candidate for a stable branch

If you want a commit to be applied to a stable branch, you should add an appropriate note to the commit message.

Here are some examples of such a note:

- NOTE: This is a candidate for the 9.0 branch.
- NOTE: This is a candidate for the 8.0 and 9.0 branches.
- NOTE: This is a candidate for the stable branches.

## Cherry-picking candidates for a stable branch

Please use `git cherry-pick -x <commit>` for cherry-picking a commit from master to a stable branch.

## Making a New Mesa Release

These are the instructions for making a new Mesa release.

### Get latest source files

Use git to get the latest Mesa files from the git repository, from whatever branch is relevant.

### Verify and update version info

Makefile.am
  PACKAGE_VERSION
configure.ac
  AC_INIT
src/mesa/main/version.h
  MESA_MAJOR, MESA_MINOR, MESA_PATCH and MESA_VERSION_STRING

Create a docs/relnotes-x.y.z.html file. The bin/shortlog_mesa.sh script can be used to create a HTML-formatted list of changes to include in the file. Link the new docs/relnotes-x.y.z.html file into the main relnotes.html file.

Update docs/index.html.

Tag the files with the release name (in the form mesa-x.y) with: `git tag -a mesa-x.y` Then: `git push origin mesa-x.y`

### Make the tarballs

Make the distribution files. From inside the Mesa directory:

    	make tarballs

After the tarballs are created, the md5 checksums for the files will be computed. Add them to the docs/relnotes-x.y.html file.

Copy the distribution files to a temporary directory, unpack them, compile everything, and run some demos to be sure everything works.

### Update the website and announce the release

Follow the directions on SourceForge for creating a new "release" and uploading the tarballs.

Basically, to upload the tarball files with:
`rsync -avP ssh Mesa*-X.Y.* USERNAME@frs.sourceforge.net:uploads/`

Update the web site by copying the docs/ directory's files to /home/users/b/br/brianp/mesa-www/htdocs/ with:
`sftp USERNAME,mesa3d@web.sourceforge.net`

Make an announcement on the mailing lists: m e s a-d e v@l i s t s.f r e e d e s k t o p.o r g, m e s a-u s e r s@l i s t s.f r e e d e s k t o p.o r g and m e s a-a n n o u n c e@l i s t s.f r e e d e s k t o p.o r g