1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html lang="en">
3<head>
4  <meta http-equiv="content-type" content="text/html; charset=utf-8">
5  <title>Development Notes</title>
6  <link rel="stylesheet" type="text/css" href="mesa.css">
7</head>
8<body>
9
10<h1>Development Notes</h1>
11
12
13<h2>Adding Extentions</h2>
14
15<p>
16To add a new GL extension to Mesa you have to do at least the following.
17
18<ul>
19<li>
20   If glext.h doesn't define the extension, edit include/GL/gl.h and add
21   code like this:
22   <pre>
23     #ifndef GL_EXT_the_extension_name
24     #define GL_EXT_the_extension_name 1
25     /* declare the new enum tokens */
26     /* prototype the new functions */
27     /* TYPEDEFS for the new functions */
28     #endif
29   </pre>
30</li>
31<li>
32   In the src/mesa/glapi/ directory, add the new extension functions and
33   enums to the gl_API.xml file.
34   Then, a bunch of source files must be regenerated by executing the
35   corresponding Python scripts.
36</li>
37<li>
38   Add a new entry to the <code>gl_extensions</code> struct in mtypes.h
39</li>
40<li>
41   Update the <code>extensions.c</code> file.
42</li>
43<li>
44   From this point, the best way to proceed is to find another extension,
45   similar to the new one, that's already implemented in Mesa and use it
46   as an example.
47</li>
48<li>
49   If the new extension adds new GL state, the functions in get.c, enable.c
50   and attrib.c will most likely require new code.
51</li>
52</ul>
53
54
55
56<h2>Coding Style</h2>
57
58<p>
59Mesa's code style has changed over the years.  Here's the latest.
60</p>
61
62<p>
63Comment your code!  It's extremely important that open-source code be
64well documented.  Also, strive to write clean, easily understandable code.
65</p>
66
67<p>
683-space indentation
69</p>
70
71<p>
72If you use tabs, set them to 8 columns
73</p>
74
75<p>
76Line width: the preferred width to fill comments and code in Mesa is 78
77columns.  Exceptions are sometimes made for clarity (e.g. tabular data is
78sometimes filled to a much larger width so that extraneous carriage returns
79don't obscure the table).
80</p>
81
82<p>
83Brace example:
84</p>
85<pre>
86	if (condition) {
87	   foo;
88	}
89	else {
90	   bar;
91	}
92
93	switch (condition) {
94	case 0:
95	   foo();
96	   break;
97
98	case 1: {
99	   ...
100	   break;
101	}
102
103	default:
104	   ...
105	   break;
106	}
107</pre>
108
109<p>
110Here's the GNU indent command which will best approximate my preferred style:
111(Note that it won't format switch statements in the preferred way)
112</p>
113<pre>
114	indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
115</pre>
116
117
118<p>
119Local variable name example:  localVarName (no underscores)
120</p>
121
122<p>
123Constants and macros are ALL_UPPERCASE, with _ between words
124</p>
125
126<p>
127Global variables are not allowed.
128</p>
129
130<p>
131Function name examples:
132</p>
133<pre>
134	glFooBar()       - a public GL entry point (in glapi_dispatch.c)
135	_mesa_FooBar()   - the internal immediate mode function
136	save_FooBar()    - retained mode (display list) function in dlist.c
137	foo_bar()        - a static (private) function
138	_mesa_foo_bar()  - an internal non-static Mesa function
139</pre>
140
141<p>
142Places that are not directly visible to the GL API should prefer the use
143of <tt>bool</tt>, <tt>true</tt>, and
144<tt>false</tt> over <tt>GLboolean</tt>, <tt>GL_TRUE</tt>, and
145<tt>GL_FALSE</tt>.  In C code, this may mean that
146<tt>#include &lt;stdbool.h&gt;</tt> needs to be added.  The
147<tt>try_emit_</tt>* methods in src/mesa/program/ir_to_mesa.cpp and
148src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples.
149</p>
150
151
152<h2>Making a New Mesa Release</h2>
153
154<p>
155These are the instructions for making a new Mesa release.
156</p>
157
158<h3>Get latest source files</h3>
159<p>
160Use git to get the latest Mesa files from the git repository, from whatever
161branch is relevant.
162</p>
163
164
165<h3>Verify and update version info</h3>
166
167<dl>
168  <dt>configs/default</dt>
169  <dd>MESA_MAJOR, MESA_MINOR and MESA_TINY</dd>
170  <dt>Makefile.am</dt>
171  <dd>PACKAGE_VERSION</dd>
172  <dt>configure.ac</dt>
173  <dd>AC_INIT</dd>
174  <dt>src/mesa/main/version.h</dt>
175  <dd>MESA_MAJOR, MESA_MINOR, MESA_PATCH and MESA_VERSION_STRING</dd>
176</dl>
177
178<p>
179Create a docs/relnotes-x.y.z.html file.
180The bin/shortlog_mesa.sh script can be used to create a HTML-formatted list
181of changes to include in the file.
182Link the new docs/relnotes-x.y.z.html file into the main <a href="relnotes.html">relnotes.html</a> file.
183</p>
184
185<p>
186Update <a href="news.html">docs/news.html</a>.
187</p>
188
189<p>
190Tag the files with the release name (in the form <b>mesa-x.y</b>)
191with: <code>git tag -a mesa-x.y</code>
192Then: <code>git push origin mesa-x.y</code>
193</p>
194
195
196<h3>Make the tarballs</h3>
197<p>
198Make the distribution files.  From inside the Mesa directory:
199<pre>
200	make tarballs
201</pre>
202
203<p>
204After the tarballs are created, the md5 checksums for the files will
205be computed.
206Add them to the docs/relnotes-x.y.html file.
207</p>
208
209<p>
210Copy the distribution files to a temporary directory, unpack them,
211compile everything, and run some demos to be sure everything works.
212</p>
213
214<h3>Update the website and announce the release</h3>
215<p>
216Follow the directions on SourceForge for creating a new "release" and
217uploading the tarballs.
218</p>
219
220<p>
221Basically, to upload the tarball files with:
222<br>
223<code>
224rsync -avP ssh Mesa*-X.Y.* USERNAME@frs.sourceforge.net:uploads/
225</code>
226</p>
227
228<p>
229Update the web site by copying the docs/ directory's files to 
230/home/users/b/br/brianp/mesa-www/htdocs/ with:
231<br>
232<code>
233sftp USERNAME,mesa3d@web.sourceforge.net
234</code>
235</p>
236
237<p>
238Make an announcement on the mailing lists:
239
240<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>,
241<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>
242and
243<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>
244</p>
245
246</body>
247</html>
248