devinfo.html 6.41 KB
Newer Older
1 2 3 4 5 6 7 8
<!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>
9

Andreas Boll's avatar
Andreas Boll committed
10 11 12 13 14 15 16
<div class="header">
  <h1>The Mesa 3D Graphics Library</h1>
</div>

<iframe src="contents.html"></iframe>
<div class="content">

17
<h1>Development Notes</h1>
18

Brian Paul's avatar
Brian Paul committed
19

20
<h2>Adding Extentions</h2>
21 22

<p>
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
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>
Brian Paul's avatar
Brian Paul committed
45 46 47 48 49 50 51 52 53
   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.
54 55
</li>
<li>
Brian Paul's avatar
Brian Paul committed
56
   If the new extension adds new GL state, the functions in get.c, enable.c
57 58 59
   and attrib.c will most likely require new code.
</li>
</ul>
60 61 62



63
<h2>Coding Style</h2>
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81

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

82 83 84 85 86 87 88
<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>

89 90 91 92 93 94 95 96 97 98
<p>
Brace example:
</p>
<pre>
	if (condition) {
	   foo;
	}
	else {
	   bar;
	}
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113

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

	case 1: {
	   ...
	   break;
	}

	default:
	   ...
	   break;
	}
114 115 116 117
</pre>

<p>
Here's the GNU indent command which will best approximate my preferred style:
118
(Note that it won't format switch statements in the preferred way)
119 120
</p>
<pre>
Brian Paul's avatar
Brian Paul committed
121
	indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
122 123 124 125 126 127 128 129 130 131 132 133
</pre>


<p>
Local variable name example:  localVarName (no underscores)
</p>

<p>
Constants and macros are ALL_UPPERCASE, with _ between words
</p>

<p>
Brian Paul's avatar
Brian Paul committed
134
Global variables are not allowed.
135 136 137 138 139 140
</p>

<p>
Function name examples:
</p>
<pre>
141
	glFooBar()       - a public GL entry point (in glapi_dispatch.c)
142 143 144 145 146 147
	_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>

148 149 150 151 152
<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
Kai Wasserbäch's avatar
Kai Wasserbäch committed
153
<tt>#include &lt;stdbool.h&gt;</tt> needs to be added.  The
154
<tt>try_emit_</tt>* methods in src/mesa/program/ir_to_mesa.cpp and
Kai Wasserbäch's avatar
Kai Wasserbäch committed
155
src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples.
156 157
</p>

158

159
<h2>Making a New Mesa Release</h2>
160 161 162 163 164

<p>
These are the instructions for making a new Mesa release.
</p>

165
<h3>Get latest source files</h3>
166
<p>
167 168
Use git to get the latest Mesa files from the git repository, from whatever
branch is relevant.
169 170 171
</p>


172
<h3>Verify and update version info</h3>
173

174 175 176 177 178
<dl>
  <dt>configs/default</dt>
  <dd>MESA_MAJOR, MESA_MINOR and MESA_TINY</dd>
  <dt>Makefile.am</dt>
  <dd>PACKAGE_VERSION</dd>
Andreas Boll's avatar
Andreas Boll committed
179
  <dt>configure.ac</dt>
180 181 182 183
  <dd>AC_INIT</dd>
  <dt>src/mesa/main/version.h</dt>
  <dd>MESA_MAJOR, MESA_MINOR, MESA_PATCH and MESA_VERSION_STRING</dd>
</dl>
Brian Paul's avatar
Brian Paul committed
184 185

<p>
186 187 188
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.
189 190 191 192 193
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="news.html">docs/news.html</a>.
Brian Paul's avatar
Brian Paul committed
194 195 196
</p>

<p>
197 198 199
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>
Brian Paul's avatar
Brian Paul committed
200 201 202
</p>


203
<h3>Make the tarballs</h3>
204 205 206
<p>
Make the distribution files.  From inside the Mesa directory:
<pre>
Brian Paul's avatar
Brian Paul committed
207
	make tarballs
208 209
</pre>

Brian Paul's avatar
Brian Paul committed
210 211 212
<p>
After the tarballs are created, the md5 checksums for the files will
be computed.
213
Add them to the docs/relnotes-x.y.html file.
Brian Paul's avatar
Brian Paul committed
214 215
</p>

216 217 218 219 220
<p>
Copy the distribution files to a temporary directory, unpack them,
compile everything, and run some demos to be sure everything works.
</p>

221
<h3>Update the website and announce the release</h3>
222
<p>
Brian Paul's avatar
Brian Paul committed
223 224
Follow the directions on SourceForge for creating a new "release" and
uploading the tarballs.
225 226
</p>

227 228 229 230 231 232 233 234
<p>
Basically, to upload the tarball files with:
<br>
<code>
rsync -avP ssh Mesa*-X.Y.* USERNAME@frs.sourceforge.net:uploads/
</code>
</p>

235
<p>
Brian Paul's avatar
Brian Paul committed
236
Update the web site by copying the docs/ directory's files to 
237 238 239 240 241
/home/users/b/br/brianp/mesa-www/htdocs/ with:
<br>
<code>
sftp USERNAME,mesa3d@web.sourceforge.net
</code>
242 243 244
</p>

<p>
245
Make an announcement on the mailing lists:
246 247 248

<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>
249
and
250
<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>
251 252
</p>

Andreas Boll's avatar
Andreas Boll committed
253
</div>
254 255
</body>
</html>