1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
|
<!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>
<div class="header">
<h1>The Mesa 3D Graphics Library</h1>
</div>
<iframe src="contents.html"></iframe>
<div class="content">
<h1>Development Notes</h1>
<ul>
<li><a href="#release">Making a New Mesa Release</a>
<li><a href="#extensions">Adding Extensions</a>
</ul>
<h2 id="release">Making a New Mesa Release</h2>
<p>
These are the instructions for making a new Mesa release.
</p>
<h3>Get latest source files</h3>
<p>
Use git to get the latest Mesa files from the git repository, from whatever
branch is relevant. This document uses the convention X.Y.Z for the release
being created, which should be created from a branch named X.Y.
</p>
<h3>Perform basic testing</h3>
<p>
The release manager should, at the very least, test the code by compiling it,
installing it, and running the latest piglit to ensure that no piglit tests
have regressed since the previous release.
</p>
<p>
The release manager should do this testing with at least one hardware driver,
(say, whatever is contained in the local development machine), as well as on
both Gallium and non-Gallium software drivers. The software testing can be
performed by running piglit with the following environment-variable set:
</p>
<pre>
LIBGL_ALWAYS_SOFTWARE=1
</pre>
And Gallium vs. non-Gallium software drivers can be obtained by using the
following configure flags on separate builds:
<pre>
--with-dri-drivers=swrast
--with-gallium-drivers=swrast
</pre>
<p>
Note: If both options are given in one build, both swrast_dri.so drivers will
be compiled, but only one will be installed. The following command can be used
to ensure the correct driver is being tested:
</p>
<pre>
LIBGL_ALWAYS_SOFTWARE=1 glxinfo | grep "renderer string"
</pre>
If any regressions are found in this testing with piglit, stop here, and do
not perform a release until regressions are fixed.
<h3>Update version in file VERSION</h3>
<p>
Increment the version contained in the file VERSION at Mesa's top-level, then
commit this change.
</p>
<h3>Create release notes for the new release</h3>
<p>
Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous
release notes). Note that the sha256sums section of the release notes should
be empty at this point.
</p>
<p>
Two scripts are available to help generate portions of the release notes:
<pre>
./bin/bugzilla_mesa.sh
./bin/shortlog_mesa.sh
</pre>
<p>
The first script identifies commits that reference bugzilla bugs and obtains
the descriptions of those bugs from bugzilla. The second script generates a
log of all commits. In both cases, HTML-formatted lists are printed to stdout
to be included in the release notes.
</p>
<p>
Commit these changes
</p>
<h3>Make the release archives, signatures, and the release tag</h3>
<p>
From inside the Mesa directory:
<pre>
./autogen.sh
make -j1 tarballs
</pre>
<p>
After the tarballs are created, the sha256 checksums for the files will
be computed and printed. These will be used in a step below.
</p>
<p>
It's important at this point to also verify that the constructed tar file
actually builds:
</p>
<pre>
tar xjf MesaLib-X.Y.Z.tar.bz2
cd Mesa-X.Y.Z
./configure --enable-gallium-llvm
make -j6
make install
</pre>
<p>
Some touch testing should also be performed at this point, (run glxgears or
more involved OpenGL programs against the installed Mesa).
</p>
<p>
Create detached GPG signatures for each of the archive files created above:
</p>
<pre>
gpg --sign --detach MesaLib-X.Y.Z.tar.gz
gpg --sign --detach MesaLib-X.Y.Z.tar.bz2
gpg --sign --detach MesaLib-X.Y.Z.zip
</pre>
<p>
Tag the commit used for the build:
</p>
<pre>
git tag -s mesa-X.Y.X -m "Mesa X.Y.Z release"
</pre>
<p>
Note: It would be nice to investigate and fix the issue that causes the
tarballs target to fail with multiple build process, such as with "-j4". It
would also be nice to incorporate all of the above commands into a single
makefile target. And instead of a custom "tarballs" target, we should
incorporate things into the standard "make dist" and "make distcheck" targets.
</p>
<h3>Add the sha256sums to the release notes</h3>
<p>
Edit docs/relnotes/X.Y.Z.html to add the sha256sums printed as part of "make
tarballs" in the previous step. Commit this change.
</p>
<h3>Push all commits and the tag created above</h3>
<p>
This is the first step that cannot easily be undone. The release is going
forward from this point:
</p>
<pre>
git push origin X.Y --tags
</pre>
<h3>Install the release files and signatures on the distribution server</h3>
<p>
The following commands can be used to copy the release archive files and
signatures to the freedesktop.org server:
</p>
<pre>
scp MesaLib-X.Y.Z* people.freedesktop.org:
ssh people.freedesktop.org
cd /srv/ftp.freedesktop.org/pub/mesa
mkdir X.Y.Z
cd X.Y.Z
mv ~/MesaLib-X.Y.Z* .
</pre>
<h3>Back on mesa master, add the new release notes into the tree</h3>
<p>
Something like the following steps will do the trick:
</p>
<pre>
cp docs/relnotes/X.Y.Z.html /tmp
git checkout master
cp /tmp/X.Y.Z.html docs/relnotes
git add docs/relnotes/X.Y.Z.html
</pre>
<p>
Also, edit docs/relnotes.html to add a link to the new release notes, and edit
docs/index.html to add a news entry. Then commit and push:
</p>
<pre>
git commit -a -m "docs: Import X.Y.Z release notes, add news item."
git push origin
</pre>
<h3>Update the mesa3d.org website</h3>
<p>
NOTE: The recent release managers have not been performing this step
themselves, but leaving this to Brian Paul, (who has access to the
sourceforge.net hosting for mesa3d.org). Brian is more than willing to grant
the permission necessary to future release managers to do this step on their
own.
</p>
<p>
Update the web site by copying the docs/ directory's files to
/home/users/b/br/brianp/mesa-www/htdocs/ with:
<br>
<code>
sftp USERNAME,mesa3d@web.sourceforge.net
</code>
</p>
<h3>Announce the release</h3>
<p>
Make an announcement on the mailing lists:
<em>mesa-dev@lists.freedesktop.org</em>,
and
<em>mesa-announce@lists.freedesktop.org</em>
Follow the template of previously-sent release announcements. The following
command can be used to generate the log of changes to be included in the
release announcement:
<pre>
git shortlog mesa-X.Y.Z-1..mesa-X.Y.Z
</pre>
</p>
<h2 id="extensions">Adding Extensions</h2>
<p>
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/mapi/glapi/gen/ 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>
Add a new entry to the <code>gl_extensions</code> struct in mtypes.h
if the extension requires driver capabilities not already exposed by
another extension.
</li>
<li>
Add a new entry to the src/mesa/main/extensions_table.h 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.
</li>
<li>
If the new extension adds new GL state, the functions in get.c, enable.c
and attrib.c will most likely require new code.
</li>
<li>
To determine if the new extension is active in the current context,
use the auto-generated _mesa_has_##name_str() function defined in
src/mesa/main/extensions.h.
</li>
<li>
The dispatch tests check_table.cpp and dispatch_sanity.cpp
should be updated with details about the new extensions functions. These
tests are run using 'make check'
</li>
</ul>
</p>
</div>
</body>
</html>
|
