@@ -37,150 +37,9 @@ There are two approaches to building extension modules on Windows, just as there
3737are on Unix: use the :mod: `distutils ` package to control the build process, or
3838do things manually. The distutils approach works well for most extensions;
3939documentation on using :mod: `distutils ` to build and package extension modules
40- is available in :ref: `distutils-index `. This section describes the manual
41- approach to building Python extensions written in C or C++.
42-
43- To build extensions using these instructions, you need to have a copy of the
44- Python sources of the same version as your installed Python. You will need
45- Microsoft Visual C++ "Developer Studio"; project files are supplied for VC++
46- version 7.1, but you can use older versions of VC++. Notice that you should use
47- the same version of VC++that was used to build Python itself. The example files
48- described here are distributed with the Python sources in the
49- :file: `PC\\ example_nt\\ ` directory.
50-
51- #. **Copy the example files ** --- The :file: `example_nt ` directory is a
52- subdirectory of the :file: `PC ` directory, in order to keep all the PC-specific
53- files under the same directory in the source distribution. However, the
54- :file: `example_nt ` directory can't actually be used from this location. You
55- first need to copy or move it up one level, so that :file: `example_nt ` is a
56- sibling of the :file: `PC ` and :file: `Include ` directories. Do all your work
57- from within this new location.
58-
59- #. **Open the project ** --- From VC++, use the :menuselection: `File --> Open
60- Solution ` dialog (not :menuselection: `File --> Open `!). Navigate to and select
61- the file :file: `example.sln `, in the *copy * of the :file: `example_nt ` directory
62- you made above. Click Open.
63-
64- #. **Build the example DLL ** --- In order to check that everything is set up
65- right, try building:
66-
67- #. Select a configuration. This step is optional. Choose
68- :menuselection: `Build --> Configuration Manager --> Active Solution Configuration `
69- and select either :guilabel: `Release ` or :guilabel: `Debug `. If you skip this
70- step, VC++ will use the Debug configuration by default.
71-
72- #. Build the DLL. Choose :menuselection: `Build --> Build Solution `. This
73- creates all intermediate and result files in a subdirectory called either
74- :file: `Debug ` or :file: `Release `, depending on which configuration you selected
75- in the preceding step.
76-
77- #. **Testing the debug-mode DLL ** --- Once the Debug build has succeeded, bring
78- up a DOS box, and change to the :file: `example_nt\\ Debug ` directory. You should
79- now be able to repeat the following session (``C> `` is the DOS prompt, ``>>> ``
80- is the Python prompt; note that build information and various debug output from
81- Python may not match this screen dump exactly)::
82-
83- C>..\..\PCbuild\python_d
84- Adding parser accelerators ...
85- Done.
86- Python 2.2 (#28, Dec 19 2001, 23:26:37) [MSC 32 bit (Intel)] on win32
87- Type "copyright", "credits" or "license" for more information.
88- >>> import example
89- [4897 refs]
90- >>> example.foo()
91- Hello, world
92- [4903 refs]
93- >>>
94-
95- Congratulations! You've successfully built your first Python extension module.
96-
97- #. **Creating your own project ** --- Choose a name and create a directory for
98- it. Copy your C sources into it. Note that the module source file name does
99- not necessarily have to match the module name, but the name of the
100- initialization function should match the module name --- you can only import a
101- module :mod: `spam ` if its initialization function is called :c:func: `initspam `,
102- and it should call :c:func: `Py_InitModule ` with the string ``"spam" `` as its
103- first argument (use the minimal :file: `example.c ` in this directory as a guide).
104- By convention, it lives in a file called :file: `spam.c ` or :file: `spammodule.c `.
105- 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
107- to avoid confusion with a system library :file: `spam.dll ` to which your module
108- could be a Python interface.
109-
110- Now your options are:
111-
112- #. Copy :file: `example.sln ` and :file: `example.vcproj `, rename them to
113- :file: `spam.\* `, and edit them by hand, or
114-
115- #. Create a brand new project; instructions are below.
116-
117- In either case, copy :file: `example_nt\\ example.def ` to :file: `spam\\ spam.def `,
118- and edit the new :file: `spam.def ` so its second line contains the string
119- '``initspam ``'. If you created a new project yourself, add the file
120- :file: `spam.def ` to the project now. (This is an annoying little file with only
121- two lines. An alternative approach is to forget about the :file: `.def ` file,
122- and add the option :option: `/export:initspam ` somewhere to the Link settings, by
123- manually editing the setting in Project Properties dialog).
124-
125- #. **Creating a brand new project ** --- Use the :menuselection: `File --> New
126- --> Project ` dialog to create a new Project Workspace. Select :guilabel: `Visual
127- C++ Projects/Win32/ Win32 Project `, enter the name (``spam ``), and make sure the
128- Location is set to parent of the :file: `spam ` directory you have created (which
129- should be a direct subdirectory of the Python build tree, a sibling of
130- :file: `Include ` and :file: `PC `). Select Win32 as the platform (in my version,
131- this is the only choice). Make sure the Create new workspace radio button is
132- selected. Click OK.
133-
134- You should now create the file :file: `spam.def ` as instructed in the previous
135- section. Add the source files to the project, using :menuselection: `Project -->
136- Add Existing Item `. Set the pattern to ``*.* `` and select both :file: `spam.c `
137- and :file: `spam.def ` and click OK. (Inserting them one by one is fine too.)
138-
139- Now open the :menuselection: `Project --> spam properties ` dialog. You only need
140- to change a few settings. Make sure :guilabel: `All Configurations ` is selected
141- from the :guilabel: `Settings for: ` dropdown list. Select the C/C++ tab. Choose
142- the General category in the popup menu at the top. Type the following text in
143- the entry box labeled :guilabel: `Additional Include Directories `::
144-
145- ..\Include,..\PC
146-
147- Then, choose the General category in the Linker tab, and enter ::
148-
149- ..\PCbuild
150-
151- in the text box labelled :guilabel: `Additional library Directories `.
152-
153- Now you need to add some mode-specific settings:
154-
155- Select :guilabel: `Release ` in the :guilabel: `Configuration ` dropdown list.
156- Choose the :guilabel: `Link ` tab, choose the :guilabel: `Input ` category, and
157- append ``pythonXY.lib `` to the list in the :guilabel: `Additional Dependencies `
158- box.
159-
160- Select :guilabel: `Debug ` in the :guilabel: `Configuration ` dropdown list, and
161- append ``pythonXY_d.lib `` to the list in the :guilabel: `Additional Dependencies `
162- box. Then click the C/C++ tab, select :guilabel: `Code Generation `, and select
163- :guilabel: `Multi-threaded Debug DLL ` from the :guilabel: `Runtime library `
164- dropdown list.
165-
166- Select :guilabel: `Release ` again from the :guilabel: `Configuration ` dropdown
167- list. Select :guilabel: `Multi-threaded DLL ` from the :guilabel: `Runtime
168- library ` dropdown list.
169-
170- If your module creates a new type, you may have trouble with this line::
171-
172- PyVarObject_HEAD_INIT(&PyType_Type, 0)
173-
174- Static type object initializers in extension modules may cause
175- compiles to fail with an error message like "initializer not a
176- constant". This shows up when building DLL under MSVC. Change it to::
177-
178- PyVarObject_HEAD_INIT(NULL, 0)
179-
180- and add the following to the module initialization function::
181-
182- if (PyType_Ready(&MyObject_Type) < 0)
183- return NULL;
40+ is available in :ref: `distutils-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.
18443
18544
18645.. _dynamic-linking :
0 commit comments