rest25/extending/windows.rst => rest262/extending/windows.rst
f1.. highlightlang:: c
2
3
4.. _building-on-windows:
5
6****************************************
7Building C and C++ Extensions on Windows
8****************************************
n9- 
10-.. % 
11
12This chapter briefly explains how to create a Windows extension module for
13Python using Microsoft Visual C++, and follows with more detailed background
14information on how it works.  The explanatory material is useful for both the
15Windows programmer learning to build Python extensions and the Unix programmer
16interested in producing software which can be successfully built on both Unix
17and Windows.
18
20extension modules, instead of the one described in this section. You will still
21need the C compiler that was used to build Python; typically Microsoft Visual
22C++.
23
24.. note::
25
26   This chapter mentions a number of filenames that include an encoded Python
27   version number.  These filenames are represented with the version number shown
n28-   as ``XY``; in practive, ``'X'`` will be the major version number and ``'Y'``
n26+   as ``XY``; in practice, ``'X'`` will be the major version number and ``'Y'``
29   will be the minor version number of the Python release you're working with.  For
30   example, if you are using Python 2.2.1, ``XY`` will actually be ``22``.
31
32
33.. _win-cookbook:
34
35A Cookbook Approach
36===================
37
38There are two approaches to building extension modules on Windows, just as there
n39-are on Unix: use the :mod:`distutils` (XXX reference: ../lib/module-
n37+are on Unix: use the :mod:`distutils` package to control the build process, or
40-distutils.html) package to control the build process, or do things manually.
38+do things manually.  The distutils approach works well for most extensions;
41-The distutils approach works well for most extensions; documentation on using
39+documentation on using :mod:`distutils` to build and package extension modules
42-:mod:`distutils` (XXX reference: ../lib/module-distutils.html) to build and
40+is available in :ref:`distutils-index`.  This section describes the manual
43-package extension modules is available in Distributing Python Modules (XXX
44-reference: ../dist/dist.html).  This section describes the manual approach to
45-building Python extensions written in C or C++.
41+approach to building Python extensions written in C or C++.
46
47To build extensions using these instructions, you need to have a copy of the
48Python sources of the same version as your installed Python. You will need
49Microsoft Visual C++ "Developer Studio"; project files are supplied for VC++
50version 7.1, but you can use older versions of VC++.  Notice that you should use
51the same version of VC++that was used to build Python itself. The example files
52described here are distributed with the Python sources in the
53:file:`PC\\example_nt\\` directory.
63#. **Open the project** ---  From VC++, use the :menuselection:`File --> Open
64   Solution` dialog (not :menuselection:`File --> Open`!).  Navigate to and select
65   the file :file:`example.sln`, in the *copy* of the :file:`example_nt` directory
66   you made above.  Click Open.
67
68#. **Build the example DLL** ---  In order to check that everything is set up
69   right, try building:
70
n71-#. Select a configuration.  This step is optional.  Choose :menuselection:`Build
n67+#. Select a configuration.  This step is optional.  Choose
72-      --> Configuration Manager --> Active  Solution Configuration` and select either
68+   :menuselection:`Build --> Configuration Manager --> Active Solution Configuration`
73-      :guilabel:`Release`  or\ :guilabel:`Debug`.  If you skip this step, VC++ will
69+   and select either :guilabel:`Release`  or :guilabel:`Debug`.  If you skip this
74-      use the Debug configuration by default.
70+   step, VC++ will use the Debug configuration by default.
75
76#. Build the DLL.  Choose :menuselection:`Build --> Build Solution`.  This
n77-      creates all intermediate and result files in a subdirectory called either
n73+   creates all intermediate and result files in a subdirectory called either
78-      :file:`Debug` or :file:`Release`, depending on which configuration you selected
74+   :file:`Debug` or :file:`Release`, depending on which configuration you selected
79-      in the preceding step.
75+   in the preceding step.
80
81#. **Testing the debug-mode DLL** ---  Once the Debug build has succeeded, bring
82   up a DOS box, and change to the :file:`example_nt\\Debug` directory.  You should
83   now be able to repeat the following session (``C>`` is the DOS prompt, ``>>>``
84   is the Python prompt; note that build information and various debug output from
85   Python may not match this screen dump exactly)::
86
87      C>..\..\PCbuild\python_d
101#. **Creating your own project** ---  Choose a name and create a directory for
102   it.  Copy your C sources into it.  Note that the module source file name does
103   not necessarily have to match the module name, but the name of the
104   initialization function should match the module name --- you can only import a
105   module :mod:`spam` if its initialization function is called :cfunc:`initspam`,
106   and it should call :cfunc:`Py_InitModule` with the string ``"spam"`` as its
107   first argument (use the minimal :file:`example.c` in this directory as a guide).
108   By convention, it lives in a file called :file:`spam.c` or :file:`spammodule.c`.
n109-   The output file should be called :file:`spam.dll` or :file:`spam.pyd` (the
n105+   The output file should be called :file:`spam.pyd` (in Release mode) or
106+   :file:`spam_d.pyd` (in Debug mode). The extension :file:`.pyd` was chosen
110-   latter is supported to avoid confusion with a system library :file:`spam.dll` to
107+   to avoid confusion with a system library :file:`spam.dll` to which your module
111-   which your module could be a Python interface) in Release mode, or
108+   could be a Python interface.
112-   :file:`spam_d.dll` or :file:`spam_d.pyd` in Debug mode.
109+ 
110+   .. versionchanged:: 2.5
111+      Previously, file names like :file:`spam.dll` (in release mode) or
112+      :file:`spam_d.dll` (in debug mode) were also recognized.
113
114   Now your options are:
115
116#. Copy :file:`example.sln` and :file:`example.vcproj`, rename them to
117      :file:`spam.\*`, and edit them by hand, or
118
119#. Create a brand new project; instructions are below.
120
178Change it to::
179
180   PyObject_HEAD_INIT(NULL)
181
182and add the following to the module initialization function::
183
184   MyObject_Type.ob_type = &PyType_Type;
185
t186-Refer to section 3 of the `Python FAQ <http://www.python.org/doc/FAQ.html>`_ for
t186+Refer to section 3 of the `Python FAQ <http://www.python.org/doc/faq>`_ for
187details on why you must do this.
188
189
190.. _dynamic-linking:
191
192Differences Between Unix and Windows
193====================================
194
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op