Commit | Line | Data |
---|---|---|
920dae64 AT |
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> |