Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / b347bb5dbca9ab2973399bc933470514110e688c / . / docs / devinfo.html
blob: a469cbaa63ac52c63541c87101308189b78bbbfa [file] [log] [blame]
Andreas Bollecd5c7c2012-06-12 09:05:03 +0200[diff] [blame]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>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]9
Andreas Bollecd5c7c2012-06-12 09:05:03 +0200[diff] [blame]10<h1>Development Notes</h1>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]11
12
Andreas Bollecd5c7c2012-06-12 09:05:03 +0200[diff] [blame]13<h2>Adding Extentions</h2>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]14
15<p>
Brian Paul51830612004-08-17 14:08:59 +0000[diff] [blame]16To add a new GL extension to Mesa you have to do at least the following.
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]17
Brian Paul51830612004-08-17 14:08:59 +0000[diff] [blame]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>
Brian Paulbb086292006-09-21 22:53:15 +0000[diff] [blame]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.
Brian Paul51830612004-08-17 14:08:59 +0000[diff] [blame]47</li>
48<li>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]49 If the new extension adds new GL state, the functions in get.c, enable.c
Brian Paul51830612004-08-17 14:08:59 +0000[diff] [blame]50 and attrib.c will most likely require new code.
51</li>
52</ul>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]53
54
55
Andreas Boll210a27d2012-06-12 09:05:36 +0200[diff] [blame]56<h2>Coding Style</h2>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]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>
Paul Berry43968262011-08-16 14:09:32 -0700[diff] [blame]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>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]83Brace example:
84</p>
85<pre>
86 if (condition) {
87 foo;
88 }
89 else {
90 bar;
91 }
Paul Berry43968262011-08-16 14:09:32 -0700[diff] [blame]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 }
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]107</pre>
108
109<p>
110Here's the GNU indent command which will best approximate my preferred style:
Paul Berry43968262011-08-16 14:09:32 -0700[diff] [blame]111(Note that it won't format switch statements in the preferred way)
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]112</p>
113<pre>
Brian Paule3f41ce2006-03-31 23:10:21 +0000[diff] [blame]114 indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]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>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]127Global variables are not allowed.
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]128</p>
129
130<p>
131Function name examples:
132</p>
133<pre>
Chia-I Wu27d260b42010-02-24 11:20:14 +0800[diff] [blame]134 glFooBar() - a public GL entry point (in glapi_dispatch.c)
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]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
Kai Wasserbächdbec3a52011-08-23 10:48:58 +0200[diff] [blame]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
Kai Wasserbäche106d4c2011-08-27 17:51:47 +0200[diff] [blame]146<tt>#include &lt;stdbool.h&gt;</tt> needs to be added. The
Kai Wasserbächdbec3a52011-08-23 10:48:58 +0200[diff] [blame]147<tt>try_emit_</tt>* methods in src/mesa/program/ir_to_mesa.cpp and
Kai Wasserbäche106d4c2011-08-27 17:51:47 +0200[diff] [blame]148src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples.
Kai Wasserbächdbec3a52011-08-23 10:48:58 +0200[diff] [blame]149</p>
150
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]151
Andreas Boll210a27d2012-06-12 09:05:36 +0200[diff] [blame]152<h2>Making a New Mesa Release</h2>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]153
154<p>
155These are the instructions for making a new Mesa release.
156</p>
157
Andreas Boll210a27d2012-06-12 09:05:36 +0200[diff] [blame]158<h3>Get latest source files</h3>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]159<p>
Brian Paul84c5e482009-06-23 19:21:04 -0600[diff] [blame]160Use git to get the latest Mesa files from the git repository, from whatever
161branch is relevant.
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]162</p>
163
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]164
Andreas Boll210a27d2012-06-12 09:05:36 +0200[diff] [blame]165<h3>Verify and update version info</h3>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]166
Andreas Bollb347bb52012-06-25 21:53:06 +0200[diff] [blame^]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>autoconf.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>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]177
178<p>
Brian Paul8031aa12012-06-14 12:17:31 -0600[diff] [blame]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.
Andreas Bollb347bb52012-06-25 21:53:06 +0200[diff] [blame^]182Link the new docs/relnotes-x.y.z.html file into the main <a href="relnotes.html">relnotes.html</a> file.
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]183</p>
184
185<p>
Andreas Bollb347bb52012-06-25 21:53:06 +0200[diff] [blame^]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>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]193</p>
194
195
Andreas Boll210a27d2012-06-12 09:05:36 +0200[diff] [blame]196<h3>Make the tarballs</h3>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]197<p>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]198Make the distribution files. From inside the Mesa directory:
199<pre>
Brian Paul9cef3ef2004-10-02 15:43:14 +0000[diff] [blame]200 make tarballs
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]201</pre>
202
203<p>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]204After the tarballs are created, the md5 checksums for the files will
205be computed.
Andreas Bollb347bb52012-06-25 21:53:06 +0200[diff] [blame^]206Add them to the docs/relnotes-x.y.html file.
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]207</p>
208
209<p>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]210Copy the distribution files to a temporary directory, unpack them,
211compile everything, and run some demos to be sure everything works.
212</p>
213
Andreas Boll210a27d2012-06-12 09:05:36 +0200[diff] [blame]214<h3>Update the website and announce the release</h3>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]215<p>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]216Follow the directions on SourceForge for creating a new "release" and
217uploading the tarballs.
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]218</p>
219
220<p>
Brian Paul84c5e482009-06-23 19:21:04 -0600[diff] [blame]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>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]229Update the web site by copying the docs/ directory's files to
Brian Paul84c5e482009-06-23 19:21:04 -0600[diff] [blame]230/home/users/b/br/brianp/mesa-www/htdocs/ with:
231<br>
232<code>
233sftp USERNAME,mesa3d@web.sourceforge.net
234</code>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]235</p>
236
237<p>
Brian Paulefe56712003-03-19 19:15:28 +0000[diff] [blame]238Make an announcement on the mailing lists:
Ian Romanick8f32c642010-06-16 14:28:08 -0700[diff] [blame]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>
Brian Paulefe56712003-03-19 19:15:28 +0000[diff] [blame]242and
Ian Romanick8f32c642010-06-16 14:28:08 -0700[diff] [blame]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>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]244</p>
245
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]246</body>
247</html>