f | .. highlightlang:: c |
| |
| |
| .. _building-on-windows: |
| |
| **************************************** |
| Building C and C++ Extensions on Windows |
| **************************************** |
n | |
| .. % |
| |
| This chapter briefly explains how to create a Windows extension module for |
| Python using Microsoft Visual C++, and follows with more detailed background |
| information on how it works. The explanatory material is useful for both the |
| Windows programmer learning to build Python extensions and the Unix programmer |
| interested in producing software which can be successfully built on both Unix |
| and Windows. |
| |
| extension modules, instead of the one described in this section. You will still |
| need the C compiler that was used to build Python; typically Microsoft Visual |
| C++. |
| |
| .. note:: |
| |
| This chapter mentions a number of filenames that include an encoded Python |
| version number. These filenames are represented with the version number shown |
n | as ``XY``; in practive, ``'X'`` will be the major version number and ``'Y'`` |
n | as ``XY``; in practice, ``'X'`` will be the major version number and ``'Y'`` |
| will be the minor version number of the Python release you're working with. For |
| example, if you are using Python 2.2.1, ``XY`` will actually be ``22``. |
| |
| |
| .. _win-cookbook: |
| |
| A Cookbook Approach |
| =================== |
| |
| There are two approaches to building extension modules on Windows, just as there |
n | are on Unix: use the :mod:`distutils` (XXX reference: ../lib/module- |
n | are on Unix: use the :mod:`distutils` package to control the build process, or |
| distutils.html) package to control the build process, or do things manually. |
| do things manually. The distutils approach works well for most extensions; |
| The distutils approach works well for most extensions; documentation on using |
| documentation on using :mod:`distutils` to build and package extension modules |
| :mod:`distutils` (XXX reference: ../lib/module-distutils.html) to build and |
| is available in :ref:`distutils-index`. This section describes the manual |
| package extension modules is available in Distributing Python Modules (XXX |
| reference: ../dist/dist.html). This section describes the manual approach to |
| building Python extensions written in C or C++. |
| approach to building Python extensions written in C or C++. |
| |
| 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 |
| :file:`PC\\example_nt\\` directory. |
| #. **Open the project** --- From VC++, use the :menuselection:`File --> Open |
| Solution` dialog (not :menuselection:`File --> Open`!). Navigate to and select |
| the file :file:`example.sln`, in the *copy* of the :file:`example_nt` directory |
| you made above. Click Open. |
| |
| #. **Build the example DLL** --- In order to check that everything is set up |
| right, try building: |
| |
n | #. Select a configuration. This step is optional. Choose :menuselection:`Build |
n | #. Select a configuration. This step is optional. Choose |
| --> Configuration Manager --> Active Solution Configuration` and select either |
| :menuselection:`Build --> Configuration Manager --> Active Solution Configuration` |
| :guilabel:`Release` or\ :guilabel:`Debug`. If you skip this step, VC++ will |
| and select either :guilabel:`Release` or :guilabel:`Debug`. If you skip this |
| use the Debug configuration by default. |
| step, VC++ will use the Debug configuration by default. |
| |
| #. Build the DLL. Choose :menuselection:`Build --> Build Solution`. This |
n | creates all intermediate and result files in a subdirectory called either |
n | creates all intermediate and result files in a subdirectory called either |
| :file:`Debug` or :file:`Release`, depending on which configuration you selected |
| :file:`Debug` or :file:`Release`, depending on which configuration you selected |
| in the preceding step. |
| in the preceding step. |
| |
| #. **Testing the debug-mode DLL** --- Once the Debug build has succeeded, bring |
| up a DOS box, and change to the :file:`example_nt\\Debug` directory. You should |
| now be able to repeat the following session (``C>`` is the DOS prompt, ``>>>`` |
| is the Python prompt; note that build information and various debug output from |
| Python may not match this screen dump exactly):: |
| |
| C>..\..\PCbuild\python_d |
| #. **Creating 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 :mod:`spam` if its initialization function is called :cfunc:`initspam`, |
| and it should call :cfunc:`Py_InitModule` with the string ``"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`. |
n | The output file should be called :file:`spam.dll` or :file:`spam.pyd` (the |
n | The output file should be called :file:`spam.pyd` (in Release mode) or |
| :file:`spam_d.pyd` (in Debug mode). The extension :file:`.pyd` was chosen |
| latter is supported to avoid confusion with a system library :file:`spam.dll` to |
| to avoid confusion with a system library :file:`spam.dll` to which your module |
| which your module could be a Python interface) in Release mode, or |
| could be a Python interface. |
| :file:`spam_d.dll` or :file:`spam_d.pyd` in Debug mode. |
| |
| .. versionchanged:: 2.5 |
| Previously, file names like :file:`spam.dll` (in release mode) or |
| :file:`spam_d.dll` (in debug mode) were also recognized. |
| |
| Now your options are: |
| |
| #. Copy :file:`example.sln` and :file:`example.vcproj`, rename them to |
| :file:`spam.\*`, and edit them by hand, or |
| |
| #. Create a brand new project; instructions are below. |
| |