docs/devinfo.html

   1 <HTML>
   2
   3 <TITLE>Development Notes</TITLE>
   4
   5 <link rel="stylesheet" type="text/css" href="mesa.css"></head>
   6
   7 <BODY>
   8
   9 <H1>Development Notes</H1>
  10
  11
  12 <H2>Adding Extentions</H2>
  13
  14 <p>
  15 To add a new GL extension to Mesa you have to do at least the following.
  16
  17 <ul>
  18 <li>
  19    If glext.h doesn't define the extension, edit include/GL/gl.h and add
  20    code like this:
  21    <pre>
  22      #ifndef GL_EXT_the_extension_name
  23      #define GL_EXT_the_extension_name 1
  24      /* declare the new enum tokens */
  25      /* prototype the new functions */
  26      /* TYPEDEFS for the new functions */
  27      #endif
  28    </pre>
  29 </li>
  30 <li>
  31    In the src/mesa/glapi/ directory, add the new extension functions and
  32    enums to the gl_API.xml file.
  33    Then, a bunch of source files must be regenerated by executing the
  34    corresponding Python scripts.
  35 </li>
  36 <li>
  37    Find an existing extension that's similar to the new one and search
  38    the sources for code related to that extension.
  39    Implement new code as needed.
  40    In general, new state variables will be added to mtypes.h.  If the
  41    extension is rather large, try to implement it in a new source file.
  42 </li>
  43 <li>
  44    If the new extension adds new GL state, the functions in get.c, enable.c
  45    and attrib.c will most likely require new code.
  46 </li>
  47 </ul>
  48
  49
  50
  51 <H2>Coding Style</H2>
  52
  53 <p>
  54 Mesa's code style has changed over the years.  Here's the latest.
  55 </p>
  56
  57 <p>
  58 Comment your code!  It's extremely important that open-source code be
  59 well documented.  Also, strive to write clean, easily understandable code.
  60 </p>
  61
  62 <p>
  63 3-space indentation
  64 </p>
  65
  66 <p>
  67 If you use tabs, set them to 8 columns
  68 </p>
  69
  70 <p>
  71 Brace example:
  72 </p>
  73 <pre>
  74         if (condition) {
  75            foo;
  76         }
  77         else {
  78            bar;
  79         }
  80 </pre>
  81
  82 <p>
  83 Here's the GNU indent command which will best approximate my preferred style:
  84 </p>
  85 <pre>
  86         indent -br -i3 -npcs infile.c -o outfile.c
  87 </pre>
  88
  89
  90 <p>
  91 Local variable name example:  localVarName (no underscores)
  92 </p>
  93
  94 <p>
  95 Constants and macros are ALL_UPPERCASE, with _ between words
  96 </p>
  97
  98 <p>
  99 Global variables are not allowed.
 100 </p>
 101
 102 <p>
 103 Function name examples:
 104 </p>
 105 <pre>
 106         glFooBar()       - a public GL entry point (in dispatch.c)
 107         _mesa_FooBar()   - the internal immediate mode function
 108         save_FooBar()    - retained mode (display list) function in dlist.c
 109         foo_bar()        - a static (private) function
 110         _mesa_foo_bar()  - an internal non-static Mesa function
 111 </pre>
 112
 113
 114 <H2>Making a New Mesa Release</H2>
 115
 116 <p>
 117 These are the instructions for making a new Mesa release.
 118 </p>
 119
 120 <H3>Get latest source files</H3>
 121 <p>
 122 Use "cvs update -dAP " to get the latest Mesa files from CVS.
 123 </p>
 124
 125
 126 <H3>Verify and update version info</H3>
 127 <p>
 128 Create/edit the docs/RELNOTES-X.Y file to document what's new in the release.
 129 Add the new RELNOTES-X.Y file to <a href="relnotes.html">relnotes.html</a>.
 130 Update the docs/VERSIONS file too.
 131 </p>
 132
 133 <p>
 134 Edit configs/default and change the MESA_MAJOR, MESA_MINOR and MESA_TINY
 135 version numbers.
 136 </p>
 137
 138 <p>
 139 Make sure the values in src/mesa/main/version.h is correct.
 140 </p>
 141
 142 <p>
 143 Edit the top-level Makefile and verify that DIRECTORY, LIB_NAME and
 144 DEMO_NAME are correct.
 145 </p>
 146
 147 <p>
 148 Update the docs/news.html file and docs/contents.html files.
 149 </p>
 150
 151 <p>
 152 Check in all updates to CVS.
 153 </p>
 154
 155 <p>
 156 Tag the CVS files with the release name (in the form <b>mesa_X_Y</b>).
 157 </p>
 158
 159
 160 <H3>Make the tarballs</H3>
 161 <p>
 162 Make a symbolic link from $(DIRECTORY) to 'Mesa'.  For example,
 163 ln -s Mesa Mesa-6.3
 164 This is needed in order to make a correct tar file in the next step.
 165 </p>
 166
 167 <p>
 168 Make the distribution files.  From inside the Mesa directory:
 169 <pre>
 170         make tarballs
 171 </pre>
 172
 173 <p>
 174 After the tarballs are created, the md5 checksums for the files will
 175 be computed.
 176 Add them to the docs/news.html file.
 177 </p>
 178
 179 <p>
 180 Copy the distribution files to a temporary directory, unpack them,
 181 compile everything, and run some demos to be sure everything works.
 182 </p>
 183
 184 <H3>Update the website and announce the release</H3>
 185 <p>
 186 Follow the directions on SourceForge for creating a new "release" and
 187 uploading the tarballs.
 188 </p>
 189
 190 <p>
 191 Update the web site by copying the docs/ directory's files to
 192 /home/users/b/br/brianp/mesa-www/htdocs/
 193 </p>
 194
 195 <p>
 196 Make an announcement on the mailing lists:
 197 <em>m</em><em>e</em><em>s</em><em>a</em><em>3</em><em>d</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>s</em><em>f</em><em>.</em><em>n</em><em>e</em><em>t</em>,
 198 <em>m</em><em>e</em><em>s</em><em>a</em><em>3</em><em>d</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>s</em><em>f</em><em>.</em><em>n</em><em>e</em><em>t</em>
 199 and
 200 <em>m</em><em>e</em><em>s</em><em>a</em><em>3</em><em>d</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>s</em><em>f</em><em>.</em><em>n</em><em>e</em><em>t</em>
 201 </p>
 202
 203
 204
 205 </body>
 206 </html>