diff options
Diffstat (limited to 'Doc/ext')
| -rw-r--r-- | Doc/ext/windows.tex | 181 |
1 files changed, 166 insertions, 15 deletions
diff --git a/Doc/ext/windows.tex b/Doc/ext/windows.tex index d42263b..9623eab 100644 --- a/Doc/ext/windows.tex +++ b/Doc/ext/windows.tex @@ -12,27 +12,178 @@ software which can be successfully built on both \UNIX{} and Windows. \section{A Cookbook Approach \label{win-cookbook}} -\sectionauthor{Neil Schemenauer}{neil_schemenauer@transcanada.com} +There are two approaches to building extension modules on Windows, +just as there are on \UNIX: use the \refmodule{distutils} package to +control the build process, or do things manually. The distutils +approach works well for most extensions; documentation on using +\refmodule{distutils} to build and package extension modules is +available in \citetitle[../dist/dist.html]{Distributing Python +Modules}. This section describes the manual approach to building +Python extensions written in C or \Cpp. + +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 \Cpp{} ``Developer Studio''; project +files are supplied for V\Cpp{} version 6, but you can use older +versions of V\Cpp. The example files described here are distributed +with the Python sources in the \file{PC\textbackslash +example_nt\textbackslash} directory. + +\begin{enumerate} + \item + \strong{Copy the example files}\\ + The \file{example_nt} directory is a subdirectory of the \file{PC} + directory, in order to keep all the PC-specific files under the + same directory in the source distribution. However, the + \file{example_nt} directory can't actually be used from this + location. You first need to copy or move it up one level, so that + \file{example_nt} is a sibling of the \file{PC} and \file{Include} + directories. Do all your work from within this new location. + + \item + \strong{Open the project}\\ + From V\Cpp, use the \menuselection{File \sub Open Workspace} + dialog (not \menuselection{File \sub Open}!). Navigate to and + select the file \file{example.dsw}, in the \emph{copy} of the + \file{example_nt} directory you made above. Click Open. + + \item + \strong{Build the example DLL}\\ + In order to check that everything is set up right, try building: + + \begin{enumerate} + \item + Select a configuration. This step is optional. Choose + \menuselection{Build \sub Select Active Configuration} and + select either ``example - Win32 Release'' or ``example - Win32 + Debug.'' If you skip this step, V\Cpp{} will use the Debug + configuration by default. + + \item + Build the DLL. Choose \menuselection{Build \sub Build + example_d.dll} in Debug mode, or \menuselection{Build \sub + Build example.dll} in Release mode. This creates all + intermediate and result files in a subdirectory called either + \file{Debug} or \file{Release}, depending on which + configuration you selected in the preceding step. + \end{enumerate} + + \item + \strong{Testing the debug-mode DLL}\\ + Once the Debug build has succeeded, bring up a DOS box, and change + to the \file{example_nt\textbackslash Debug} directory. You + should now be able to repeat the following session (\code{C>} is + the DOS prompt, \code{>\code{>}>} is the Python prompt; note that + build information and various debug output from Python may not + match this screen dump exactly): -This section provides a recipe for building a Python extension on -Windows. +\begin{verbatim} +C>..\..\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. +>>> import example +[4897 refs] +>>> example.foo() +Hello, world +[4903 refs] +>>> +\end{verbatim} + + Congratulations! You've successfully built your first Python + extension module. + + \item + \strong{Cretating your own project}\\ + 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 \module{spam} if its initialization function + is called \cfunction{initspam()}, and it should call + \cfunction{Py_InitModule()} with the string \code{"spam"} as its + first argument (use the minimal \file{example.c} in this directory + as a guide). By convention, it lives in a file called + \file{spam.c} or \file{spammodule.c}. The output file should be + called \file{spam.dll} or \file{spam.pyd} (the latter is supported + to avoid confusion with a system library \file{spam.dll} to which + your module could be a Python interface) in Release mode, or + \file{spam_d.dll} or \file{spam_d.pyd} in Debug mode. + + Now your options are: + + \begin{enumerate} + \item Copy \file{example.dsw} and \file{example.dsp}, rename + them to \file{spam.*}, and edit them by hand, or + \item Create a brand new project; instructions are below. + \end{enumerate} + + In either case, copy \file{example_nt\textbackslash example.def} + to \file{spam\textbackslash spam.def}, and edit the new + \file{spam.def} so its second line contains the string + `\code{initspam}'. If you created a new project yourself, add the + file \file{spam.def} to the project now. (This is an annoying + little file with only two lines. An alternative approach is to + forget about the \file{.def} file, and add the option + \programopt{/export:initspam} somewhere to the Link settings, by + manually editing the setting in Project Options dialog). + + \item + \strong{Creating a brand new project}\\ + Use the \menuselection{File \sub New \sub Projects} dialog to + create a new Project Workspace. Select ``Win32 Dynamic-Link + Library,'' enter the name (\samp{spam}), and make sure the + Location is set to the \file{spam} directory you have created + (which should be a direct subdirectory of the Python build tree, a + sibling of \file{Include} and \file{PC}). 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. + + Now open the \menuselection{Project \sub Settings} dialog. You + only need to change a few settings. Make sure All Configurations + is selected from the Settings for: dropdown list. Select the + C/\Cpp{} tab. Choose the Preprocessor category in the popup menu + at the top. Type the following text in the entry box labeled + Addditional include directories: + +\begin{verbatim} +..\Include,..\PC +\end{verbatim} + + Then, choose the Input category in the Link tab, and enter + +\begin{verbatim} +..\PCbuild +\end{verbatim} + + in the text box labelled ``Additional library path.'' + + Now you need to add some mode-specific settings: -Grab the binary installer from \url{http://www.python.org/} and -install Python. The binary installer has all of the required header -files except for \file{pyconfig.h}. + Select ``Win32 Release'' in the ``Settings for'' dropdown list. + Click the Link tab, choose the Input Category, and append + \code{python22.lib} to the list in the ``Object/library modules'' + box. -Get the source distribution and extract it into a convenient location. -Copy the \file{pyconfig.h} from the \file{PC/} directory into the -\file{include/} directory created by the installer. + Select ``Win32 Debug'' in the ``Settings for'' dropdown list, and + append \code{python22_d.lib} to the list in the ``Object/library + modules'' box. Then click the C/\Cpp{} tab, select ``Code + Generation'' from the Category dropdown list, and select ``Debug + Multithreaded DLL'' from the ``Use run-time library'' dropdown + list. -Create a \file{Setup} file for your extension module, as described in -chapter \ref{building-on-unix}. + Select ``Win32 Release'' again from the ``Settings for'' dropdown + list. Select ``Multithreaded DLL'' from the ``Use run-time + library:'' dropdown list. -Get David Ascher's \file{compile.py} script from -\url{http://starship.python.net/crew/da/compile/}. Run the script to -create Microsoft Visual \Cpp{} project files. + You should now create the file spam.def as instructed in the + previous section. Then chose the \menuselection{Insert \sub Files + into Project} dialog. Set the pattern to \code{*.*} and select + both \file{spam.c} and \file{spam.def} and click OK. (Inserting + them one by one is fine too.) +\end{enumerate} -Open the DSW file in Visual \Cpp{} and select \strong{Build}. If your module creates a new type, you may have trouble with this line: |