Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / 8031aa134ebcdcaad3c7b1d10f41c1f033382d30 / . / docs / devinfo.html
blob: 4828cc61d6c22eaec43c70477f3f59c6dd901850 [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<p>
Brian Paul84c5e482009-06-23 19:21:04 -0600[diff] [blame]167Create/edit the docs/relnotes-x.y.html file to document what's new in the release.
168Add the new relnotes-x.y.html file to <a href="relnotes.html">relnotes.html</a>.
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]169</p>
170
171<p>
Brian Paul84c5e482009-06-23 19:21:04 -0600[diff] [blame]172Update the MESA_MAJOR, MESA_MINOR and MESA_TINY version numbers in
Dan Nicholson00994ac2008-04-30 15:06:00 -0700[diff] [blame]173configs/default.
Brian Paul84c5e482009-06-23 19:21:04 -0600[diff] [blame]174Also update the VERSION line in the top-level Makefile.
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]175</p>
176
177<p>
Dan Nicholson00994ac2008-04-30 15:06:00 -0700[diff] [blame]178Make sure the values in src/mesa/main/version.h are correct.
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]179</p>
180
181<p>
Ian Romanick13a90e82010-06-16 14:24:46 -0700[diff] [blame]182Update docs/news.html.
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]183</p>
184
185<p>
Brian Paul8031aa12012-06-14 12:17:31 -0600[diff] [blame^]186Create a docs/relnotes-x.y.z.html file.
187The bin/shortlog_mesa.sh script can be used to create a HTML-formatted list
188of changes to include in the file.
189Link the new docs/relnotes-x.y.z.html file into the main relnotes.html file.
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]190</p>
191
192<p>
Brian Paul84c5e482009-06-23 19:21:04 -0600[diff] [blame]193Tag the files with the release name (in the form <b>mesa_X_Y</b>)
194with: <code>git tag -a mesa_X_Y</code>
195Then: <code>git push origin mesa_X_Y</code>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]196</p>
197
198
Andreas Boll210a27d2012-06-12 09:05:36 +0200[diff] [blame]199<h3>Make the tarballs</h3>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]200<p>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]201Make the distribution files. From inside the Mesa directory:
202<pre>
Brian Paul9cef3ef2004-10-02 15:43:14 +0000[diff] [blame]203 make tarballs
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]204</pre>
205
206<p>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]207After the tarballs are created, the md5 checksums for the files will
208be computed.
Brian Paul84c5e482009-06-23 19:21:04 -0600[diff] [blame]209Add them to the docs/relnotes-X.Y.html file.
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]210</p>
211
212<p>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]213Copy the distribution files to a temporary directory, unpack them,
214compile everything, and run some demos to be sure everything works.
215</p>
216
Andreas Boll210a27d2012-06-12 09:05:36 +0200[diff] [blame]217<h3>Update the website and announce the release</h3>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]218<p>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]219Follow the directions on SourceForge for creating a new "release" and
220uploading the tarballs.
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]221</p>
222
223<p>
Brian Paul84c5e482009-06-23 19:21:04 -0600[diff] [blame]224Basically, to upload the tarball files with:
225<br>
226<code>
227rsync -avP ssh Mesa*-X.Y.* USERNAME@frs.sourceforge.net:uploads/
228</code>
229</p>
230
231<p>
Brian Paul65b79052004-11-22 17:49:15 +0000[diff] [blame]232Update the web site by copying the docs/ directory's files to
Brian Paul84c5e482009-06-23 19:21:04 -0600[diff] [blame]233/home/users/b/br/brianp/mesa-www/htdocs/ with:
234<br>
235<code>
236sftp USERNAME,mesa3d@web.sourceforge.net
237</code>
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]238</p>
239
240<p>
Brian Paulefe56712003-03-19 19:15:28 +0000[diff] [blame]241Make an announcement on the mailing lists:
Ian Romanick8f32c642010-06-16 14:28:08 -0700[diff] [blame]242
243<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>,
244<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]245and
Ian Romanick8f32c642010-06-16 14:28:08 -0700[diff] [blame]246<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]247</p>
248
Brian Paul0b27ace2003-03-08 17:38:57 +0000[diff] [blame]249</body>
250</html>