Fred Drake | cc8f44b | 2001-08-20 19:30:29 +0000 | [diff] [blame] | 1 | \chapter{Building C and \Cpp{} Extensions on Windows |
| 2 | \label{building-on-windows}} |
| 3 | |
| 4 | |
| 5 | This chapter briefly explains how to create a Windows extension module |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 6 | for Python using Microsoft Visual \Cpp, and follows with more |
Fred Drake | cc8f44b | 2001-08-20 19:30:29 +0000 | [diff] [blame] | 7 | detailed background information on how it works. The explanatory |
| 8 | material is useful for both the Windows programmer learning to build |
| 9 | Python extensions and the \UNIX{} programmer interested in producing |
| 10 | software which can be successfully built on both \UNIX{} and Windows. |
| 11 | |
| 12 | |
| 13 | \section{A Cookbook Approach \label{win-cookbook}} |
| 14 | |
| 15 | \sectionauthor{Neil Schemenauer}{neil_schemenauer@transcanada.com} |
| 16 | |
| 17 | This section provides a recipe for building a Python extension on |
| 18 | Windows. |
| 19 | |
| 20 | Grab the binary installer from \url{http://www.python.org/} and |
| 21 | install Python. The binary installer has all of the required header |
| 22 | files except for \file{pyconfig.h}. |
| 23 | |
| 24 | Get the source distribution and extract it into a convenient location. |
| 25 | Copy the \file{pyconfig.h} from the \file{PC/} directory into the |
| 26 | \file{include/} directory created by the installer. |
| 27 | |
| 28 | Create a \file{Setup} file for your extension module, as described in |
| 29 | chapter \ref{building-on-unix}. |
| 30 | |
| 31 | Get David Ascher's \file{compile.py} script from |
| 32 | \url{http://starship.python.net/crew/da/compile/}. Run the script to |
| 33 | create Microsoft Visual \Cpp{} project files. |
| 34 | |
| 35 | Open the DSW file in Visual \Cpp{} and select \strong{Build}. |
| 36 | |
| 37 | If your module creates a new type, you may have trouble with this line: |
| 38 | |
| 39 | \begin{verbatim} |
| 40 | PyObject_HEAD_INIT(&PyType_Type) |
| 41 | \end{verbatim} |
| 42 | |
| 43 | Change it to: |
| 44 | |
| 45 | \begin{verbatim} |
| 46 | PyObject_HEAD_INIT(NULL) |
| 47 | \end{verbatim} |
| 48 | |
| 49 | and add the following to the module initialization function: |
| 50 | |
| 51 | \begin{verbatim} |
| 52 | MyObject_Type.ob_type = &PyType_Type; |
| 53 | \end{verbatim} |
| 54 | |
| 55 | Refer to section 3 of the |
| 56 | \citetitle[http://www.python.org/doc/FAQ.html]{Python FAQ} for details |
| 57 | on why you must do this. |
| 58 | |
| 59 | |
| 60 | \section{Differences Between \UNIX{} and Windows |
| 61 | \label{dynamic-linking}} |
| 62 | \sectionauthor{Chris Phoenix}{cphoenix@best.com} |
| 63 | |
| 64 | |
| 65 | \UNIX{} and Windows use completely different paradigms for run-time |
| 66 | loading of code. Before you try to build a module that can be |
| 67 | dynamically loaded, be aware of how your system works. |
| 68 | |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 69 | In \UNIX, a shared object (\file{.so}) file contains code to be used by the |
Fred Drake | cc8f44b | 2001-08-20 19:30:29 +0000 | [diff] [blame] | 70 | program, and also the names of functions and data that it expects to |
| 71 | find in the program. When the file is joined to the program, all |
| 72 | references to those functions and data in the file's code are changed |
| 73 | to point to the actual locations in the program where the functions |
| 74 | and data are placed in memory. This is basically a link operation. |
| 75 | |
| 76 | In Windows, a dynamic-link library (\file{.dll}) file has no dangling |
| 77 | references. Instead, an access to functions or data goes through a |
| 78 | lookup table. So the DLL code does not have to be fixed up at runtime |
| 79 | to refer to the program's memory; instead, the code already uses the |
| 80 | DLL's lookup table, and the lookup table is modified at runtime to |
| 81 | point to the functions and data. |
| 82 | |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 83 | In \UNIX, there is only one type of library file (\file{.a}) which |
Fred Drake | cc8f44b | 2001-08-20 19:30:29 +0000 | [diff] [blame] | 84 | contains code from several object files (\file{.o}). During the link |
| 85 | step to create a shared object file (\file{.so}), the linker may find |
| 86 | that it doesn't know where an identifier is defined. The linker will |
| 87 | look for it in the object files in the libraries; if it finds it, it |
| 88 | will include all the code from that object file. |
| 89 | |
| 90 | In Windows, there are two types of library, a static library and an |
| 91 | import library (both called \file{.lib}). A static library is like a |
| 92 | \UNIX{} \file{.a} file; it contains code to be included as necessary. |
| 93 | An import library is basically used only to reassure the linker that a |
| 94 | certain identifier is legal, and will be present in the program when |
| 95 | the DLL is loaded. So the linker uses the information from the |
| 96 | import library to build the lookup table for using identifiers that |
| 97 | are not included in the DLL. When an application or a DLL is linked, |
| 98 | an import library may be generated, which will need to be used for all |
| 99 | future DLLs that depend on the symbols in the application or DLL. |
| 100 | |
| 101 | Suppose you are building two dynamic-load modules, B and C, which should |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 102 | share another block of code A. On \UNIX, you would \emph{not} pass |
Fred Drake | cc8f44b | 2001-08-20 19:30:29 +0000 | [diff] [blame] | 103 | \file{A.a} to the linker for \file{B.so} and \file{C.so}; that would |
| 104 | cause it to be included twice, so that B and C would each have their |
| 105 | own copy. In Windows, building \file{A.dll} will also build |
| 106 | \file{A.lib}. You \emph{do} pass \file{A.lib} to the linker for B and |
| 107 | C. \file{A.lib} does not contain code; it just contains information |
| 108 | which will be used at runtime to access A's code. |
| 109 | |
| 110 | In Windows, using an import library is sort of like using \samp{import |
| 111 | spam}; it gives you access to spam's names, but does not create a |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 112 | separate copy. On \UNIX, linking with a library is more like |
Fred Drake | cc8f44b | 2001-08-20 19:30:29 +0000 | [diff] [blame] | 113 | \samp{from spam import *}; it does create a separate copy. |
| 114 | |
| 115 | |
| 116 | \section{Using DLLs in Practice \label{win-dlls}} |
| 117 | \sectionauthor{Chris Phoenix}{cphoenix@best.com} |
| 118 | |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 119 | Windows Python is built in Microsoft Visual \Cpp; using other |
Fred Drake | cc8f44b | 2001-08-20 19:30:29 +0000 | [diff] [blame] | 120 | compilers may or may not work (though Borland seems to). The rest of |
| 121 | this section is MSV\Cpp{} specific. |
| 122 | |
| 123 | When creating DLLs in Windows, you must pass \file{python15.lib} to |
| 124 | the linker. To build two DLLs, spam and ni (which uses C functions |
| 125 | found in spam), you could use these commands: |
| 126 | |
| 127 | \begin{verbatim} |
| 128 | cl /LD /I/python/include spam.c ../libs/python15.lib |
| 129 | cl /LD /I/python/include ni.c spam.lib ../libs/python15.lib |
| 130 | \end{verbatim} |
| 131 | |
| 132 | The first command created three files: \file{spam.obj}, |
| 133 | \file{spam.dll} and \file{spam.lib}. \file{Spam.dll} does not contain |
| 134 | any Python functions (such as \cfunction{PyArg_ParseTuple()}), but it |
| 135 | does know how to find the Python code thanks to \file{python15.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 |
| 139 | spam, and also from the Python executable. |
| 140 | |
| 141 | Not every identifier is exported to the lookup table. If you want any |
| 142 | other modules (including Python) to be able to see your identifiers, |
| 143 | you have to say \samp{_declspec(dllexport)}, as in \samp{void |
| 144 | _declspec(dllexport) initspam(void)} or \samp{PyObject |
| 145 | _declspec(dllexport) *NiGetSpamData(void)}. |
| 146 | |
| 147 | Developer Studio will throw in a lot of import libraries that you do |
| 148 | not really need, adding about 100K to your executable. To get rid of |
| 149 | them, use the Project Settings dialog, Link tab, to specify |
| 150 | \emph{ignore default libraries}. Add the correct |
| 151 | \file{msvcrt\var{xx}.lib} to the list of libraries. |