sam-t2/devtools/amd64/html/python/ext/win-cookbook.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="ext.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="ext.html" title='Extending and Embedding the Python Interpreter' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="dynamic-linking.html" />
<link rel="prev" href="building-on-windows.html" />
<link rel="parent" href="building-on-windows.html" />
<link rel="next" href="dynamic-linking.html" />
<meta name='aesop' content='information' />
<title>4.1 A Cookbook Approach </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4. Building C and"
  href="building-on-windows.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4. Building C and"
  href="building-on-windows.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.2 Differences Between Unix"
  href="dynamic-linking.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="building-on-windows.html">4. Building C and</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="building-on-windows.html">4. Building C and</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="dynamic-linking.html">4.2 Differences Between Unix</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION006100000000000000000"></A><A NAME="win-cookbook"></A>
<BR>
4.1 A Cookbook Approach
</H1>

<P>
There are two approaches to building extension modules on Windows,
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
control the build process, or do things manually.  The distutils
approach works well for most extensions; documentation on using
<tt class="module"><a href="module-distutils.html">distutils</a></tt> to build and package extension modules is
available in <em class="citetitle"><a
 href="../dist/dist.html"
 title="Distributing Python
Modules"
 >Distributing Python
Modules</a></em>.  This section describes the manual approach to building
Python extensions written in C or C++.

<P>
To build extensions using these instructions, you need to have a copy
of the Python sources of the same version as your installed Python.
You will need Microsoft Visual C++ ``Developer Studio''; project
files are supplied for VC++ version 7.1, but you can use older
versions of VC++.  Notice that you should use the same version of
VC++that was used to build Python itself. The example files
described here are distributed with the Python sources in the
<span class="file">PC&#92;example_nt&#92;</span> directory.

<P>

<OL>
<LI><strong>Copy the example files</strong>
<BR>
The <span class="file">example_nt</span> directory is a subdirectory of the <span class="file">PC</span>
    directory, in order to keep all the PC-specific files under the
    same directory in the source distribution.  However, the
    <span class="file">example_nt</span> directory can't actually be used from this
    location.  You first need to copy or move it up one level, so that
    <span class="file">example_nt</span> is a sibling of the <span class="file">PC</span> and <span class="file">Include</span>
    directories.  Do all your work from within this new location.

<P>
</LI>
<LI><strong>Open the project</strong>
<BR>
From VC++, use the <span class="guilabel">File </span> &gt; <span class="guilabel">Open Solution</span>
    dialog (not <span class="guilabel">File </span> &gt; <span class="guilabel">Open</span>!).  Navigate to and
    select the file <span class="file">example.sln</span>, in the <em>copy</em> of the
    <span class="file">example_nt</span> directory you made above.  Click Open.

<P>
</LI>
<LI><strong>Build the example DLL</strong>
<BR>
In order to check that everything is set up right, try building:

<P>

<OL>
<LI>Select a configuration.  This step is optional.  Choose
        <span class="guilabel">Build </span> &gt; <span class="guilabel">Configuration Manager </span> &gt; <span class="guilabel">Active
        Solution Configuration</span> and select either </span>Release
        or</span>Debug.  If you skip this step,
        VC++ will use the Debug configuration by default.

<P>
</LI>
<LI>Build the DLL.  Choose <span class="guilabel">Build </span> &gt; <span class="guilabel">Build
        Solution</span>.  This creates all intermediate and result files in
        a subdirectory called either <span class="file">Debug</span> or <span class="file">Release</span>,
        depending on which configuration you selected in the preceding
        step.

</LI>
</OL>

<P>
</LI>
<LI><strong>Testing the debug-mode DLL</strong>
<BR>
Once the Debug build has succeeded, bring up a DOS box, and change
    to the <span class="file">example_nt&#92;Debug</span> directory.  You
    should now be able to repeat the following session (<code>C&gt;</code> is
    the DOS prompt, <code>&gt;<code>&gt;</code>&gt;</code> is the Python prompt; note that
    build information and various debug output from Python may not
    match this screen dump exactly):

<P>
<div class="verbatim"><pre>
C&gt;..\..\PCbuild\python_d
Adding parser accelerators ...
Done.
Python 2.2 (#28, Dec 19 2001, 23:26:37) [MSC 32 bit (Intel)] on win32
Type "copyright", "credits" or "license" for more information.
&gt;&gt;&gt; import example
[4897 refs]
&gt;&gt;&gt; example.foo()
Hello, world
[4903 refs]
&gt;&gt;&gt;
</pre></div>

<P>
Congratulations!  You've successfully built your first Python
    extension module.

<P>
</LI>
<LI><strong>Creating your own project</strong>
<BR>
Choose a name and create a directory for it.  Copy your C sources
    into it.  Note that the module source file name does not
    necessarily have to match the module name, but the name of the
    initialization function should match the module name -- you can
    only import a module <tt class="module">spam</tt> if its initialization function
    is called <tt class="cfunction">initspam()</tt>, and it should call
    <tt class="cfunction">Py_InitModule()</tt> with the string <code>"spam"</code> as its
    first argument (use the minimal <span class="file">example.c</span> in this directory
    as a guide).  By convention, it lives in a file called
    <span class="file">spam.c</span> or <span class="file">spammodule.c</span>.  The output file should be
    called <span class="file">spam.dll</span> or <span class="file">spam.pyd</span> (the latter is supported
    to avoid confusion with a system library <span class="file">spam.dll</span> to which
    your module could be a Python interface) in Release mode, or
    <span class="file">spam_d.dll</span> or <span class="file">spam_d.pyd</span> in Debug mode.

<P>
Now your options are:

<P>

<OL>
<LI>Copy <span class="file">example.sln</span> and <span class="file">example.vcproj</span>, rename
             them to <span class="file">spam.*</span>, and edit them by hand, or
</LI>
<LI>Create a brand new project; instructions are below.

</LI>
</OL>

<P>
In either case, copy <span class="file">example_nt&#92;example.def</span>
    to <span class="file">spam&#92;spam.def</span>, and edit the new
    <span class="file">spam.def</span> so its second line contains the string
    `<code>initspam</code>'.  If you created a new project yourself, add the
    file <span class="file">spam.def</span> to the project now.  (This is an annoying
    little file with only two lines.  An alternative approach is to
    forget about the <span class="file">.def</span> file, and add the option
    <b class="programopt">/export:initspam</b> somewhere to the Link settings, by
    manually editing the setting in Project Properties dialog).

<P>
</LI>
<LI><strong>Creating a brand new project</strong>
<BR>
Use the <span class="guilabel">File </span> &gt; <span class="guilabel">New </span> &gt; <span class="guilabel">Project</span> dialog to
    create a new Project Workspace.  Select </span>Visual C++
    Projects/Win32/ Win32 Project, enter the name ("<tt class="samp">spam</tt>"), and
    make sure the Location is set to parent of the <span class="file">spam</span>
    directory you have created (which should be a direct subdirectory
    of the Python build tree, a sibling of <span class="file">Include</span> and
    <span class="file">PC</span>).  Select Win32 as the platform (in my version, this is
    the only choice).  Make sure the Create new workspace radio button
    is selected.  Click OK.

<P>
You should now create the file <span class="file">spam.def</span> as instructed in
    the previous section. Add the source files to the project, using
    <span class="guilabel">Project </span> &gt; <span class="guilabel">Add Existing Item</span>. Set the pattern to
    <code>*.*</code> and select both <span class="file">spam.c</span> and <span class="file">spam.def</span> and
    click OK.  (Inserting them one by one is fine too.)

<P>
Now open the <span class="guilabel">Project </span> &gt; <span class="guilabel">spam properties</span> dialog.
    You only need to change a few settings.  Make sure </span>All
    Configurations is selected from the </span>Settings for:
    dropdown list.  Select the C/C++ tab.  Choose the General
    category in the popup menu at the top.  Type the following text in
    the entry box labeled </span>Additional Include Directories:

<P>
<div class="verbatim"><pre>
..\Include,..\PC
</pre></div>

<P>
Then, choose the General category in the Linker tab, and enter

<P>
<div class="verbatim"><pre>
..\PCbuild
</pre></div>

<P>
in the text box labelled </span>Additional library Directories.

<P>
Now you need to add some mode-specific settings:

<P>
Select </span>Release in the </span>Configuration
    dropdown list.  Choose the </span>Link tab, choose the
    </span>Input category, and append <code>pythonXY.lib</code> to the
    list in the </span>Additional Dependencies box.

<P>
Select </span>Debug in the </span>Configuration dropdown
    list, and append <code>pythonXY_d.lib</code> to the list in the
    </span>Additional Dependencies box.  Then click the C/C++
    tab, select </span>Code Generation, and select
    </span>Multi-threaded Debug DLL from the </span>Runtime
    library dropdown list.

<P>
Select </span>Release again from the </span>Configuration
    dropdown list.  Select </span>Multi-threaded DLL from the
    </span>Runtime library dropdown list.
</LI>
</OL>

<P>
If your module creates a new type, you may have trouble with this line:

<P>
<div class="verbatim"><pre>
    PyObject_HEAD_INIT(&amp;PyType_Type)
</pre></div>

<P>
Change it to:

<P>
<div class="verbatim"><pre>
    PyObject_HEAD_INIT(NULL)
</pre></div>

<P>
and add the following to the module initialization function:

<P>
<div class="verbatim"><pre>
    MyObject_Type.ob_type = &amp;PyType_Type;
</pre></div>

<P>
Refer to section&nbsp;3 of the
<em class="citetitle"><a
 href="http://www.python.org/doc/FAQ.html"
 title="Python FAQ"
 >Python FAQ</a></em> for details
on why you must do this.

<P>
<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">
<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4. Building C and"
  href="building-on-windows.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4. Building C and"
  href="building-on-windows.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.2 Differences Between Unix"
  href="dynamic-linking.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="building-on-windows.html">4. Building C and</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="building-on-windows.html">4. Building C and</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="dynamic-linking.html">4.2 Differences Between Unix</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>