| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
|
| 4 |
.. _building-on-windows: |
| 5 |
|
| 6 |
**************************************** |
| 7 |
Building C and C++ Extensions on Windows |
| 8 |
**************************************** |
| 9 |
|
| 10 |
This chapter briefly explains how to create a Windows extension module for |
| 11 |
Python using Microsoft Visual C++, and follows with more detailed background |
| 12 |
information on how it works. The explanatory material is useful for both the |
| 13 |
Windows programmer learning to build Python extensions and the Unix programmer |
| 14 |
interested in producing software which can be successfully built on both Unix |
| 15 |
and Windows. |
| 16 |
|
| 17 |
Module authors are encouraged to use the distutils approach for building |
| 18 |
extension modules, instead of the one described in this section. You will still |
| 19 |
need the C compiler that was used to build Python; typically Microsoft Visual |
| 20 |
C++. |
| 21 |
|
| 22 |
.. note:: |
| 23 |
|
| 24 |
This chapter mentions a number of filenames that include an encoded Python |
| 25 |
version number. These filenames are represented with the version number shown |
| 26 |
as ``XY``; in practice, ``'X'`` will be the major version number and ``'Y'`` |
| 27 |
will be the minor version number of the Python release you're working with. For |
| 28 |
example, if you are using Python 2.2.1, ``XY`` will actually be ``22``. |
| 29 |
|
| 30 |
|
| 31 |
.. _win-cookbook: |
| 32 |
|
| 33 |
A Cookbook Approach |
| 34 |
=================== |
| 35 |
|
| 36 |
There are two approaches to building extension modules on Windows, just as there |
| 37 |
are on Unix: use the ``setuptools`` package to control the build process, or |
| 38 |
do things manually. The setuptools approach works well for most extensions; |
| 39 |
documentation on using ``setuptools`` to build and package extension modules |
| 40 |
is available in :ref:`setuptools-index`. If you find you really need to do |
| 41 |
things manually, it may be instructive to study the project file for the |
| 42 |
:source:`winsound <PCbuild/winsound.vcxproj>` standard library module. |
| 43 |
|
| 44 |
|
| 45 |
.. _dynamic-linking: |
| 46 |
|
| 47 |
Differences Between Unix and Windows |
| 48 |
==================================== |
| 49 |
|
| 50 |
.. sectionauthor:: Chris Phoenix <[email protected]> |
| 51 |
|
| 52 |
|
| 53 |
Unix and Windows use completely different paradigms for run-time loading of |
| 54 |
code. Before you try to build a module that can be dynamically loaded, be aware |
| 55 |
of how your system works. |
| 56 |
|
| 57 |
In Unix, a shared object (:file:`.so`) file contains code to be used by the |
| 58 |
program, and also the names of functions and data that it expects to find in the |
| 59 |
program. When the file is joined to the program, all references to those |
| 60 |
functions and data in the file's code are changed to point to the actual |
| 61 |
locations in the program where the functions and data are placed in memory. |
| 62 |
This is basically a link operation. |
| 63 |
|
| 64 |
In Windows, a dynamic-link library (:file:`.dll`) file has no dangling |
| 65 |
references. Instead, an access to functions or data goes through a lookup |
| 66 |
table. So the DLL code does not have to be fixed up at runtime to refer to the |
| 67 |
program's memory; instead, the code already uses the DLL's lookup table, and the |
| 68 |
lookup table is modified at runtime to point to the functions and data. |
| 69 |
|
| 70 |
In Unix, there is only one type of library file (:file:`.a`) which contains code |
| 71 |
from several object files (:file:`.o`). During the link step to create a shared |
| 72 |
object file (:file:`.so`), the linker may find that it doesn't know where an |
| 73 |
identifier is defined. The linker will look for it in the object files in the |
| 74 |
libraries; if it finds it, it will include all the code from that object file. |
| 75 |
|
| 76 |
In Windows, there are two types of library, a static library and an import |
| 77 |
library (both called :file:`.lib`). A static library is like a Unix :file:`.a` |
| 78 |
file; it contains code to be included as necessary. An import library is |
| 79 |
basically used only to reassure the linker that a certain identifier is legal, |
| 80 |
and will be present in the program when the DLL is loaded. So the linker uses |
| 81 |
the information from the import library to build the lookup table for using |
| 82 |
identifiers that are not included in the DLL. When an application or a DLL is |
| 83 |
linked, an import library may be generated, which will need to be used for all |
| 84 |
future DLLs that depend on the symbols in the application or DLL. |
| 85 |
|
| 86 |
Suppose you are building two dynamic-load modules, B and C, which should share |
| 87 |
another block of code A. On Unix, you would *not* pass :file:`A.a` to the |
| 88 |
linker for :file:`B.so` and :file:`C.so`; that would cause it to be included |
| 89 |
twice, so that B and C would each have their own copy. In Windows, building |
| 90 |
:file:`A.dll` will also build :file:`A.lib`. You *do* pass :file:`A.lib` to the |
| 91 |
linker for B and C. :file:`A.lib` does not contain code; it just contains |
| 92 |
information which will be used at runtime to access A's code. |
| 93 |
|
| 94 |
In Windows, using an import library is sort of like using ``import spam``; it |
| 95 |
gives you access to spam's names, but does not create a separate copy. On Unix, |
| 96 |
linking with a library is more like ``from spam import *``; it does create a |
| 97 |
separate copy. |
| 98 |
|
| 99 |
.. c:macro:: Py_NO_LINK_LIB |
| 100 |
|
| 101 |
Turn off the implicit, ``#pragma``-based linkage with the Python |
| 102 |
library, performed inside CPython header files. |
| 103 |
|
| 104 |
.. versionadded:: 3.14 |
| 105 |
|
| 106 |
|
| 107 |
.. _win-dlls: |
| 108 |
|
| 109 |
Using DLLs in Practice |
| 110 |
====================== |
| 111 |
|
| 112 |
.. sectionauthor:: Chris Phoenix <[email protected]> |
| 113 |
|
| 114 |
|
| 115 |
Windows Python is built in Microsoft Visual C++; using other compilers may or |
| 116 |
may not work. The rest of this section is MSVC++ specific. |
| 117 |
|
| 118 |
When creating DLLs in Windows, you can use the CPython library in two ways: |
| 119 |
|
| 120 |
1. By default, inclusion of :file:`PC/pyconfig.h` directly or via |
| 121 |
:file:`Python.h` triggers an implicit, configure-aware link with the |
| 122 |
library. The header file chooses :file:`pythonXY_d.lib` for Debug, |
| 123 |
:file:`pythonXY.lib` for Release, and :file:`pythonX.lib` for Release with |
| 124 |
the :ref:`Limited API <stable-application-binary-interface>` enabled. |
| 125 |
|
| 126 |
To build two DLLs, spam and ni (which uses C functions found in spam), you |
| 127 |
could use these commands:: |
| 128 |
|
| 129 |
cl /LD /I/python/include spam.c |
| 130 |
cl /LD /I/python/include ni.c spam.lib |
| 131 |
|
| 132 |
The first command created three files: :file:`spam.obj`, :file:`spam.dll` |
| 133 |
and :file:`spam.lib`. :file:`Spam.dll` does not contain any Python |
| 134 |
functions (such as :c:func:`PyArg_ParseTuple`), but it does know how to find |
| 135 |
the Python code thanks to the implicitly linked :file:`pythonXY.lib`. |
| 136 |
|
| 137 |
The second command created :file:`ni.dll` (and :file:`.obj` and |
| 138 |
:file:`.lib`), which knows how to find the necessary functions from spam, |
| 139 |
and also from the Python executable. |
| 140 |
|
| 141 |
2. Manually by defining :c:macro:`Py_NO_LINK_LIB` macro before including |
| 142 |
:file:`Python.h`. You must pass :file:`pythonXY.lib` to the linker. |
| 143 |
|
| 144 |
To build two DLLs, spam and ni (which uses C functions found in spam), you |
| 145 |
could use these commands:: |
| 146 |
|
| 147 |
cl /LD /DPy_NO_LINK_LIB /I/python/include spam.c ../libs/pythonXY.lib |
| 148 |
cl /LD /DPy_NO_LINK_LIB /I/python/include ni.c spam.lib ../libs/pythonXY.lib |
| 149 |
|
| 150 |
The first command created three files: :file:`spam.obj`, :file:`spam.dll` |
| 151 |
and :file:`spam.lib`. :file:`Spam.dll` does not contain any Python |
| 152 |
functions (such as :c:func:`PyArg_ParseTuple`), but it does know how to find |
| 153 |
the Python code thanks to :file:`pythonXY.lib`. |
| 154 |
|
| 155 |
The second command created :file:`ni.dll` (and :file:`.obj` and |
| 156 |
:file:`.lib`), which knows how to find the necessary functions from spam, |
| 157 |
and also from the Python executable. |
| 158 |
|
| 159 |
Not every identifier is exported to the lookup table. If you want any other |
| 160 |
modules (including Python) to be able to see your identifiers, you have to say |
| 161 |
``_declspec(dllexport)``, as in ``void _declspec(dllexport) initspam(void)`` or |
| 162 |
``PyObject _declspec(dllexport) *NiGetSpamData(void)``. |
| 163 |
|
| 164 |
Developer Studio will throw in a lot of import libraries that you do not really |
| 165 |
need, adding about 100K to your executable. To get rid of them, use the Project |
| 166 |
Settings dialog, Link tab, to specify *ignore default libraries*. Add the |
| 167 |
correct :file:`msvcrt{xx}.lib` to the list of libraries. |