projects / OpenSPARC-T2-SAM / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / ext / win-cookbook.html
CommitLineData
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>
554.1 A Cookbook Approach
56</H1>
57
58<P>
59There are two approaches to building extension modules on Windows,
60just as there are on <span class="Unix">Unix</span>: use the <tt class="module"><a href="module-distutils.html">distutils</a></tt> package to
61control the build process, or do things manually. The distutils
62approach 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
64available in <em class="citetitle"><a
65 href="../dist/dist.html"
66 title="Distributing Python
67Modules"
68 >Distributing Python
69Modules</a></em>. This section describes the manual approach to building
70Python extensions written in C or C++.
71
72<P>
73To build extensions using these instructions, you need to have a copy
74of the Python sources of the same version as your installed Python.
75You will need Microsoft Visual C++ ``Developer Studio''; project
76files are supplied for VC++ version 7.1, but you can use older
77versions of VC++. Notice that you should use the same version of
78VC++that was used to build Python itself. The example files
79described here are distributed with the Python sources in the
80<span class="file">PC&#92;example_nt&#92;</span> directory.
81
82<P>
83
84<OL>
85<LI><strong>Copy the example files</strong>
86<BR>
87The <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>
99From VC++, use the <span class="guilabel">File </span> &gt; <span class="guilabel">Open Solution</span>
100 dialog (not <span class="guilabel">File </span> &gt; <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>
108In 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> &gt; <span class="guilabel">Configuration Manager </span> &gt; <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> &gt; <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>
134Once the Debug build has succeeded, bring up a DOS box, and change
135 to the <span class="file">example_nt&#92;Debug</span> directory. You
136 should now be able to repeat the following session (<code>C&gt;</code> is
137 the DOS prompt, <code>&gt;<code>&gt;</code>&gt;</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>
143C&gt;..\..\PCbuild\python_d
144Adding parser accelerators ...
145Done.
146Python 2.2 (#28, Dec 19 2001, 23:26:37) [MSC 32 bit (Intel)] on win32
147Type "copyright", "credits" or "license" for more information.
148&gt;&gt;&gt; import example
149[4897 refs]
150&gt;&gt;&gt; example.foo()
151Hello, world
152[4903 refs]
153&gt;&gt;&gt;
154</pre></div>
155
156<P>
157Congratulations! 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>
164Choose 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>
180Now 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>
194In either case, copy <span class="file">example_nt&#92;example.def</span>
195 to <span class="file">spam&#92;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>
208Use the <span class="guilabel">File </span> &gt; <span class="guilabel">New </span> &gt; <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>
219You 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> &gt; <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>
226Now open the <span class="guilabel">Project </span> &gt; <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>
239Then, 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>
247in the text box labelled </span>Additional library Directories.
248
249<P>
250Now you need to add some mode-specific settings:
251
252<P>
253Select </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>
259Select </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>
267Select </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>
274If 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(&amp;PyType_Type)
279</pre></div>
280
281<P>
282Change it to:
283
284<P>
285<div class="verbatim"><pre>
286 PyObject_HEAD_INIT(NULL)
287</pre></div>
288
289<P>
290and add the following to the module initialization function:
291
292<P>
293<div class="verbatim"><pre>
294 MyObject_Type.ob_type = &amp;PyType_Type;
295</pre></div>
296
297<P>
298Refer to section&nbsp;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
303on 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>
344See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
345</ADDRESS>
346</BODY>
347</HTML>
Full OpenSPARC architecture tarball including simulator, hypervisor, and OBP.