docs/devinfo.html

   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>
  16 To 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>
  59 Mesa's code style has changed over the years.  Here's the latest.
  60 </p>
  61
  62 <p>
  63 Comment your code!  It's extremely important that open-source code be
  64 well documented.  Also, strive to write clean, easily understandable code.
  65 </p>
  66
  67 <p>
  68 3-space indentation
  69 </p>
  70
  71 <p>
  72 If you use tabs, set them to 8 columns
  73 </p>
  74
  75 <p>
  76 Line width: the preferred width to fill comments and code in Mesa is 78
  77 columns.  Exceptions are sometimes made for clarity (e.g. tabular data is
  78 sometimes filled to a much larger width so that extraneous carriage returns
  79 don't obscure the table).
  80 </p>
  81
  82 <p>
  83 Brace 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>
 110 Here'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>
 119 Local variable name example:  localVarName (no underscores)
 120 </p>
 121
 122 <p>
 123 Constants and macros are ALL_UPPERCASE, with _ between words
 124 </p>
 125
 126 <p>
 127 Global variables are not allowed.
 128 </p>
 129
 130 <p>
 131 Function 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>
 142 Places that are not directly visible to the GL API should prefer the use
 143 of <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
 148 src/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>
 155 These are the instructions for making a new Mesa release.
 156 </p>
 157
 158 <h3>Get latest source files</h3>
 159 <p>
 160 Use git to get the latest Mesa files from the git repository, from whatever
 161 branch 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>
 179 Create a docs/relnotes-x.y.z.html file.
 180 The bin/shortlog_mesa.sh script can be used to create a HTML-formatted list
 181 of changes to include in the file.
 182 Link 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>
 186 Update <a href="news.html">docs/news.html</a>.
 187 </p>
 188
 189 <p>
 190 Tag the files with the release name (in the form <b>mesa-x.y</b>)
 191 with: <code>git tag -a mesa-x.y</code>
 192 Then: <code>git push origin mesa-x.y</code>
 193 </p>
 194
 195
 196 <h3>Make the tarballs</h3>
 197 <p>
 198 Make the distribution files.  From inside the Mesa directory:
 199 <pre>
 200         make tarballs
 201 </pre>
 202
 203 <p>
 204 After the tarballs are created, the md5 checksums for the files will
 205 be computed.
 206 Add them to the docs/relnotes-x.y.html file.
 207 </p>
 208
 209 <p>
 210 Copy the distribution files to a temporary directory, unpack them,
 211 compile 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>
 216 Follow the directions on SourceForge for creating a new "release" and
 217 uploading the tarballs.
 218 </p>
 219
 220 <p>
 221 Basically, to upload the tarball files with:
 222 <br>
 223 <code>
 224 rsync -avP ssh Mesa*-X.Y.* USERNAME@frs.sourceforge.net:uploads/
 225 </code>
 226 </p>
 227
 228 <p>
 229 Update 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>
 233 sftp USERNAME,mesa3d@web.sourceforge.net
 234 </code>
 235 </p>
 236
 237 <p>
 238 Make 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>
 242 and
 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>