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