| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="ext.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="ext.html" title='Extending and Embedding the Python Interpreter' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='last' href='about.html' title='About this document...' /> |
| 10 | <link rel='help' href='about.html' title='About this document...' /> |
| 11 | <link rel="next" href="dynamic-linking.html" /> |
| 12 | <link rel="prev" href="building-on-windows.html" /> |
| 13 | <link rel="parent" href="building-on-windows.html" /> |
| 14 | <link rel="next" href="dynamic-linking.html" /> |
| 15 | <meta name='aesop' content='information' /> |
| 16 | <title>4.1 A Cookbook Approach </title> |
| 17 | </head> |
| 18 | <body> |
| 19 | <DIV CLASS="navigation"> |
| 20 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 21 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 22 | <tr> |
| 23 | <td class='online-navigation'><a rel="prev" title="4. Building C and" |
| 24 | href="building-on-windows.html"><img src='../icons/previous.png' |
| 25 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 26 | <td class='online-navigation'><a rel="parent" title="4. Building C and" |
| 27 | href="building-on-windows.html"><img src='../icons/up.png' |
| 28 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 29 | <td class='online-navigation'><a rel="next" title="4.2 Differences Between Unix" |
| 30 | href="dynamic-linking.html"><img src='../icons/next.png' |
| 31 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 32 | <td align="center" width="100%">Extending and Embedding the Python Interpreter</td> |
| 33 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 34 | href="contents.html"><img src='../icons/contents.png' |
| 35 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 36 | <td class='online-navigation'><img src='../icons/blank.png' |
| 37 | border='0' height='32' alt='' width='32' /></td> |
| 38 | <td class='online-navigation'><img src='../icons/blank.png' |
| 39 | border='0' height='32' alt='' width='32' /></td> |
| 40 | </tr></table> |
| 41 | <div class='online-navigation'> |
| 42 | <b class="navlabel">Previous:</b> |
| 43 | <a class="sectref" rel="prev" href="building-on-windows.html">4. Building C and</A> |
| 44 | <b class="navlabel">Up:</b> |
| 45 | <a class="sectref" rel="parent" href="building-on-windows.html">4. Building C and</A> |
| 46 | <b class="navlabel">Next:</b> |
| 47 | <a class="sectref" rel="next" href="dynamic-linking.html">4.2 Differences Between Unix</A> |
| 48 | </div> |
| 49 | <hr /></div> |
| 50 | </DIV> |
| 51 | <!--End of Navigation Panel--> |
| 52 | |
| 53 | <H1><A NAME="SECTION006100000000000000000"></A><A NAME="win-cookbook"></A> |
| 54 | <BR> |
| 55 | 4.1 A Cookbook Approach |
| 56 | </H1> |
| 57 | |
| 58 | <P> |
| 59 | There are two approaches to building extension modules on Windows, |
| 60 | just as there are on <span class="Unix">Unix</span>: use the <tt class="module"><a href="module-distutils.html">distutils</a></tt> package to |
| 61 | control the build process, or do things manually. The distutils |
| 62 | approach works well for most extensions; documentation on using |
| 63 | <tt class="module"><a href="module-distutils.html">distutils</a></tt> to build and package extension modules is |
| 64 | available in <em class="citetitle"><a |
| 65 | href="../dist/dist.html" |
| 66 | title="Distributing Python |
| 67 | Modules" |
| 68 | >Distributing Python |
| 69 | Modules</a></em>. This section describes the manual approach to building |
| 70 | Python extensions written in C or C++. |
| 71 | |
| 72 | <P> |
| 73 | To build extensions using these instructions, you need to have a copy |
| 74 | of the Python sources of the same version as your installed Python. |
| 75 | You will need Microsoft Visual C++ ``Developer Studio''; project |
| 76 | files are supplied for VC++ version 7.1, but you can use older |
| 77 | versions of VC++. Notice that you should use the same version of |
| 78 | VC++that was used to build Python itself. The example files |
| 79 | described here are distributed with the Python sources in the |
| 80 | <span class="file">PC\example_nt\</span> directory. |
| 81 | |
| 82 | <P> |
| 83 | |
| 84 | <OL> |
| 85 | <LI><strong>Copy the example files</strong> |
| 86 | <BR> |
| 87 | The <span class="file">example_nt</span> directory is a subdirectory of the <span class="file">PC</span> |
| 88 | directory, in order to keep all the PC-specific files under the |
| 89 | same directory in the source distribution. However, the |
| 90 | <span class="file">example_nt</span> directory can't actually be used from this |
| 91 | location. You first need to copy or move it up one level, so that |
| 92 | <span class="file">example_nt</span> is a sibling of the <span class="file">PC</span> and <span class="file">Include</span> |
| 93 | directories. Do all your work from within this new location. |
| 94 | |
| 95 | <P> |
| 96 | </LI> |
| 97 | <LI><strong>Open the project</strong> |
| 98 | <BR> |
| 99 | From VC++, use the <span class="guilabel">File </span> > <span class="guilabel">Open Solution</span> |
| 100 | dialog (not <span class="guilabel">File </span> > <span class="guilabel">Open</span>!). Navigate to and |
| 101 | select the file <span class="file">example.sln</span>, in the <em>copy</em> of the |
| 102 | <span class="file">example_nt</span> directory you made above. Click Open. |
| 103 | |
| 104 | <P> |
| 105 | </LI> |
| 106 | <LI><strong>Build the example DLL</strong> |
| 107 | <BR> |
| 108 | In order to check that everything is set up right, try building: |
| 109 | |
| 110 | <P> |
| 111 | |
| 112 | <OL> |
| 113 | <LI>Select a configuration. This step is optional. Choose |
| 114 | <span class="guilabel">Build </span> > <span class="guilabel">Configuration Manager </span> > <span class="guilabel">Active |
| 115 | Solution Configuration</span> and select either </span>Release |
| 116 | or</span>Debug. If you skip this step, |
| 117 | VC++ will use the Debug configuration by default. |
| 118 | |
| 119 | <P> |
| 120 | </LI> |
| 121 | <LI>Build the DLL. Choose <span class="guilabel">Build </span> > <span class="guilabel">Build |
| 122 | Solution</span>. This creates all intermediate and result files in |
| 123 | a subdirectory called either <span class="file">Debug</span> or <span class="file">Release</span>, |
| 124 | depending on which configuration you selected in the preceding |
| 125 | step. |
| 126 | |
| 127 | </LI> |
| 128 | </OL> |
| 129 | |
| 130 | <P> |
| 131 | </LI> |
| 132 | <LI><strong>Testing the debug-mode DLL</strong> |
| 133 | <BR> |
| 134 | Once the Debug build has succeeded, bring up a DOS box, and change |
| 135 | to the <span class="file">example_nt\Debug</span> directory. You |
| 136 | should now be able to repeat the following session (<code>C></code> is |
| 137 | the DOS prompt, <code>><code>></code>></code> is the Python prompt; note that |
| 138 | build information and various debug output from Python may not |
| 139 | match this screen dump exactly): |
| 140 | |
| 141 | <P> |
| 142 | <div class="verbatim"><pre> |
| 143 | C>..\..\PCbuild\python_d |
| 144 | Adding parser accelerators ... |
| 145 | Done. |
| 146 | Python 2.2 (#28, Dec 19 2001, 23:26:37) [MSC 32 bit (Intel)] on win32 |
| 147 | Type "copyright", "credits" or "license" for more information. |
| 148 | >>> import example |
| 149 | [4897 refs] |
| 150 | >>> example.foo() |
| 151 | Hello, world |
| 152 | [4903 refs] |
| 153 | >>> |
| 154 | </pre></div> |
| 155 | |
| 156 | <P> |
| 157 | Congratulations! You've successfully built your first Python |
| 158 | extension module. |
| 159 | |
| 160 | <P> |
| 161 | </LI> |
| 162 | <LI><strong>Creating your own project</strong> |
| 163 | <BR> |
| 164 | Choose a name and create a directory for it. Copy your C sources |
| 165 | into it. Note that the module source file name does not |
| 166 | necessarily have to match the module name, but the name of the |
| 167 | initialization function should match the module name -- you can |
| 168 | only import a module <tt class="module">spam</tt> if its initialization function |
| 169 | is called <tt class="cfunction">initspam()</tt>, and it should call |
| 170 | <tt class="cfunction">Py_InitModule()</tt> with the string <code>"spam"</code> as its |
| 171 | first argument (use the minimal <span class="file">example.c</span> in this directory |
| 172 | as a guide). By convention, it lives in a file called |
| 173 | <span class="file">spam.c</span> or <span class="file">spammodule.c</span>. The output file should be |
| 174 | called <span class="file">spam.dll</span> or <span class="file">spam.pyd</span> (the latter is supported |
| 175 | to avoid confusion with a system library <span class="file">spam.dll</span> to which |
| 176 | your module could be a Python interface) in Release mode, or |
| 177 | <span class="file">spam_d.dll</span> or <span class="file">spam_d.pyd</span> in Debug mode. |
| 178 | |
| 179 | <P> |
| 180 | Now your options are: |
| 181 | |
| 182 | <P> |
| 183 | |
| 184 | <OL> |
| 185 | <LI>Copy <span class="file">example.sln</span> and <span class="file">example.vcproj</span>, rename |
| 186 | them to <span class="file">spam.*</span>, and edit them by hand, or |
| 187 | </LI> |
| 188 | <LI>Create a brand new project; instructions are below. |
| 189 | |
| 190 | </LI> |
| 191 | </OL> |
| 192 | |
| 193 | <P> |
| 194 | In either case, copy <span class="file">example_nt\example.def</span> |
| 195 | to <span class="file">spam\spam.def</span>, and edit the new |
| 196 | <span class="file">spam.def</span> so its second line contains the string |
| 197 | `<code>initspam</code>'. If you created a new project yourself, add the |
| 198 | file <span class="file">spam.def</span> to the project now. (This is an annoying |
| 199 | little file with only two lines. An alternative approach is to |
| 200 | forget about the <span class="file">.def</span> file, and add the option |
| 201 | <b class="programopt">/export:initspam</b> somewhere to the Link settings, by |
| 202 | manually editing the setting in Project Properties dialog). |
| 203 | |
| 204 | <P> |
| 205 | </LI> |
| 206 | <LI><strong>Creating a brand new project</strong> |
| 207 | <BR> |
| 208 | Use the <span class="guilabel">File </span> > <span class="guilabel">New </span> > <span class="guilabel">Project</span> dialog to |
| 209 | create a new Project Workspace. Select </span>Visual C++ |
| 210 | Projects/Win32/ Win32 Project, enter the name ("<tt class="samp">spam</tt>"), and |
| 211 | make sure the Location is set to parent of the <span class="file">spam</span> |
| 212 | directory you have created (which should be a direct subdirectory |
| 213 | of the Python build tree, a sibling of <span class="file">Include</span> and |
| 214 | <span class="file">PC</span>). Select Win32 as the platform (in my version, this is |
| 215 | the only choice). Make sure the Create new workspace radio button |
| 216 | is selected. Click OK. |
| 217 | |
| 218 | <P> |
| 219 | You should now create the file <span class="file">spam.def</span> as instructed in |
| 220 | the previous section. Add the source files to the project, using |
| 221 | <span class="guilabel">Project </span> > <span class="guilabel">Add Existing Item</span>. Set the pattern to |
| 222 | <code>*.*</code> and select both <span class="file">spam.c</span> and <span class="file">spam.def</span> and |
| 223 | click OK. (Inserting them one by one is fine too.) |
| 224 | |
| 225 | <P> |
| 226 | Now open the <span class="guilabel">Project </span> > <span class="guilabel">spam properties</span> dialog. |
| 227 | You only need to change a few settings. Make sure </span>All |
| 228 | Configurations is selected from the </span>Settings for: |
| 229 | dropdown list. Select the C/C++ tab. Choose the General |
| 230 | category in the popup menu at the top. Type the following text in |
| 231 | the entry box labeled </span>Additional Include Directories: |
| 232 | |
| 233 | <P> |
| 234 | <div class="verbatim"><pre> |
| 235 | ..\Include,..\PC |
| 236 | </pre></div> |
| 237 | |
| 238 | <P> |
| 239 | Then, choose the General category in the Linker tab, and enter |
| 240 | |
| 241 | <P> |
| 242 | <div class="verbatim"><pre> |
| 243 | ..\PCbuild |
| 244 | </pre></div> |
| 245 | |
| 246 | <P> |
| 247 | in the text box labelled </span>Additional library Directories. |
| 248 | |
| 249 | <P> |
| 250 | Now you need to add some mode-specific settings: |
| 251 | |
| 252 | <P> |
| 253 | Select </span>Release in the </span>Configuration |
| 254 | dropdown list. Choose the </span>Link tab, choose the |
| 255 | </span>Input category, and append <code>pythonXY.lib</code> to the |
| 256 | list in the </span>Additional Dependencies box. |
| 257 | |
| 258 | <P> |
| 259 | Select </span>Debug in the </span>Configuration dropdown |
| 260 | list, and append <code>pythonXY_d.lib</code> to the list in the |
| 261 | </span>Additional Dependencies box. Then click the C/C++ |
| 262 | tab, select </span>Code Generation, and select |
| 263 | </span>Multi-threaded Debug DLL from the </span>Runtime |
| 264 | library dropdown list. |
| 265 | |
| 266 | <P> |
| 267 | Select </span>Release again from the </span>Configuration |
| 268 | dropdown list. Select </span>Multi-threaded DLL from the |
| 269 | </span>Runtime library dropdown list. |
| 270 | </LI> |
| 271 | </OL> |
| 272 | |
| 273 | <P> |
| 274 | If your module creates a new type, you may have trouble with this line: |
| 275 | |
| 276 | <P> |
| 277 | <div class="verbatim"><pre> |
| 278 | PyObject_HEAD_INIT(&PyType_Type) |
| 279 | </pre></div> |
| 280 | |
| 281 | <P> |
| 282 | Change it to: |
| 283 | |
| 284 | <P> |
| 285 | <div class="verbatim"><pre> |
| 286 | PyObject_HEAD_INIT(NULL) |
| 287 | </pre></div> |
| 288 | |
| 289 | <P> |
| 290 | and add the following to the module initialization function: |
| 291 | |
| 292 | <P> |
| 293 | <div class="verbatim"><pre> |
| 294 | MyObject_Type.ob_type = &PyType_Type; |
| 295 | </pre></div> |
| 296 | |
| 297 | <P> |
| 298 | Refer to section 3 of the |
| 299 | <em class="citetitle"><a |
| 300 | href="http://www.python.org/doc/FAQ.html" |
| 301 | title="Python FAQ" |
| 302 | >Python FAQ</a></em> for details |
| 303 | on why you must do this. |
| 304 | |
| 305 | <P> |
| 306 | <span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"><span class="guilabel"> |
| 307 | <DIV CLASS="navigation"> |
| 308 | <div class='online-navigation'> |
| 309 | <p></p><hr /> |
| 310 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 311 | <tr> |
| 312 | <td class='online-navigation'><a rel="prev" title="4. Building C and" |
| 313 | href="building-on-windows.html"><img src='../icons/previous.png' |
| 314 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 315 | <td class='online-navigation'><a rel="parent" title="4. Building C and" |
| 316 | href="building-on-windows.html"><img src='../icons/up.png' |
| 317 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 318 | <td class='online-navigation'><a rel="next" title="4.2 Differences Between Unix" |
| 319 | href="dynamic-linking.html"><img src='../icons/next.png' |
| 320 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 321 | <td align="center" width="100%">Extending and Embedding the Python Interpreter</td> |
| 322 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 323 | href="contents.html"><img src='../icons/contents.png' |
| 324 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 325 | <td class='online-navigation'><img src='../icons/blank.png' |
| 326 | border='0' height='32' alt='' width='32' /></td> |
| 327 | <td class='online-navigation'><img src='../icons/blank.png' |
| 328 | border='0' height='32' alt='' width='32' /></td> |
| 329 | </tr></table> |
| 330 | <div class='online-navigation'> |
| 331 | <b class="navlabel">Previous:</b> |
| 332 | <a class="sectref" rel="prev" href="building-on-windows.html">4. Building C and</A> |
| 333 | <b class="navlabel">Up:</b> |
| 334 | <a class="sectref" rel="parent" href="building-on-windows.html">4. Building C and</A> |
| 335 | <b class="navlabel">Next:</b> |
| 336 | <a class="sectref" rel="next" href="dynamic-linking.html">4.2 Differences Between Unix</A> |
| 337 | </div> |
| 338 | </div> |
| 339 | <hr /> |
| 340 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 341 | </DIV> |
| 342 | <!--End of Navigation Panel--> |
| 343 | <ADDRESS> |
| 344 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 345 | </ADDRESS> |
| 346 | </BODY> |
| 347 | </HTML> |