|
1 Example Python extension for Windows NT |
|
2 ======================================= |
|
3 |
|
4 This directory contains everything needed (except for the Python |
|
5 distribution!) to build a Python extension module using Microsoft VC++. |
|
6 Notice that you need to use the same compiler version that was used to build |
|
7 Python itself. |
|
8 |
|
9 The simplest way to build this example is to use the distutils script |
|
10 'setup.py'. To do this, simply execute: |
|
11 |
|
12 % python setup.py install |
|
13 |
|
14 after everything builds and installs, you can test it: |
|
15 |
|
16 % python -c "import example; example.foo()" |
|
17 Hello, world |
|
18 |
|
19 See setup.py for more details. alternatively, see below for instructions on |
|
20 how to build inside the Visual Studio environment. |
|
21 |
|
22 Visual Studio Build Instructions |
|
23 ================================ |
|
24 |
|
25 These are instructions how to build an extension using Visual C++. The |
|
26 instructions and project files have not been updated to the latest VC |
|
27 version. In general, it is recommended you use the 'setup.py' instructions |
|
28 above. |
|
29 |
|
30 It has been tested with VC++ 7.1 on Python 2.4. You can also use earlier |
|
31 versions of VC to build Python extensions, but the sample VC project file |
|
32 (example.dsw in this directory) is in VC 7.1 format. |
|
33 |
|
34 COPY THIS DIRECTORY! |
|
35 -------------------- |
|
36 This "example_nt" directory is a subdirectory of the PC directory, in order |
|
37 to keep all the PC-specific files under the same directory. However, the |
|
38 example_nt directory can't actually be used from this location. You first |
|
39 need to copy or move it up one level, so that example_nt is a direct |
|
40 sibling of the PC\ and Include\ directories. Do all your work from within |
|
41 this new location -- sorry, but you'll be sorry if you don't. |
|
42 |
|
43 OPEN THE PROJECT |
|
44 ---------------- |
|
45 From VC 7.1, use the |
|
46 File -> Open Solution... |
|
47 dialog (*not* the "File -> Open..." dialog!). Navigate to and select the |
|
48 file "example.sln", in the *copy* of the example_nt directory you made |
|
49 above. |
|
50 Click Open. |
|
51 |
|
52 BUILD THE EXAMPLE DLL |
|
53 --------------------- |
|
54 In order to check that everything is set up right, try building: |
|
55 |
|
56 1. Select a configuration. This step is optional. Do |
|
57 Build -> Configuration Manager... -> Active Solution Configuration |
|
58 and select either "Release" or "Debug". |
|
59 If you skip this step, you'll use the Debug configuration by default. |
|
60 |
|
61 2. Build the DLL. Do |
|
62 Build -> Build Solution |
|
63 This creates all intermediate and result files in a subdirectory which |
|
64 is called either Debug or Release, depending on which configuration you |
|
65 picked in the preceding step. |
|
66 |
|
67 TESTING THE DEBUG-MODE DLL |
|
68 -------------------------- |
|
69 Once the Debug build has succeeded, bring up a DOS box, and cd to |
|
70 example_nt\Debug. You should now be able to repeat the following session |
|
71 ("C>" is the DOS prompt, ">>>" is the Python prompt) (note that various |
|
72 debug output from Python may not match this screen dump exactly): |
|
73 |
|
74 C>..\..\PCbuild\python_d |
|
75 Adding parser accelerators ... |
|
76 Done. |
|
77 Python 2.2c1+ (#28, Dec 14 2001, 18:06:39) [MSC 32 bit (Intel)] on win32 |
|
78 Type "help", "copyright", "credits" or "license" for more information. |
|
79 >>> import example |
|
80 [7052 refs] |
|
81 >>> example.foo() |
|
82 Hello, world |
|
83 [7052 refs] |
|
84 >>> |
|
85 |
|
86 TESTING THE RELEASE-MODE DLL |
|
87 ---------------------------- |
|
88 Once the Release build has succeeded, bring up a DOS box, and cd to |
|
89 example_nt\Release. You should now be able to repeat the following session |
|
90 ("C>" is the DOS prompt, ">>>" is the Python prompt): |
|
91 |
|
92 C>..\..\PCbuild\python |
|
93 Python 2.2c1+ (#28, Dec 14 2001, 18:06:04) [MSC 32 bit (Intel)] on win32 |
|
94 Type "help", "copyright", "credits" or "license" for more information. |
|
95 >>> import example |
|
96 >>> example.foo() |
|
97 Hello, world |
|
98 >>> |
|
99 |
|
100 Congratulations! You've successfully built your first Python extension |
|
101 module. |
|
102 |
|
103 CREATING YOUR OWN PROJECT |
|
104 ------------------------- |
|
105 Choose a name ("spam" is always a winner :-) and create a directory for |
|
106 it. Copy your C sources into it. Note that the module source file name |
|
107 does not necessarily have to match the module name, but the "init" function |
|
108 name should match the module name -- i.e. you can only import a module |
|
109 "spam" if its init function is called "initspam()", and it should call |
|
110 Py_InitModule with the string "spam" as its first argument (use the minimal |
|
111 example.c in this directory as a guide). By convention, it lives in a file |
|
112 called "spam.c" or "spammodule.c". The output file should be called |
|
113 "spam.dll" or "spam.pyd" (the latter is supported to avoid confusion with a |
|
114 system library "spam.dll" to which your module could be a Python interface) |
|
115 in Release mode, or spam_d.dll or spam_d.pyd in Debug mode. |
|
116 |
|
117 Now your options are: |
|
118 |
|
119 1) Copy example.sln and example.vcproj, rename them to spam.*, and edit them |
|
120 by hand. |
|
121 |
|
122 or |
|
123 |
|
124 2) Create a brand new project; instructions are below. |
|
125 |
|
126 In either case, copy example_nt\example.def to spam\spam.def, and edit the |
|
127 new spam.def so its second line contains the string "initspam". If you |
|
128 created a new project yourself, add the file spam.def to the project now. |
|
129 (This is an annoying little file with only two lines. An alternative |
|
130 approach is to forget about the .def file, and add the option |
|
131 "/export:initspam" somewhere to the Link settings, by manually editing the |
|
132 "Project -> Properties -> Linker -> Command Line -> Additional Options" |
|
133 box). |
|
134 |
|
135 You are now all set to build your extension, unless it requires other |
|
136 external libraries, include files, etc. See Python's Extending and |
|
137 Embedding manual for instructions on how to write an extension. |
|
138 |
|
139 |
|
140 CREATING A BRAND NEW PROJECT |
|
141 ---------------------------- |
|
142 Use the |
|
143 File -> New -> Project... |
|
144 dialog to create a new Project Workspace. Select "Visual C++ Projects/Win32/ |
|
145 Win32 Project", enter the name ("spam"), and make sure the "Location" is |
|
146 set to parent of the spam directory you have created (which should be a direct |
|
147 subdirectory of the Python build tree, a sibling of Include and PC). |
|
148 In "Application Settings", select "DLL", and "Empty Project". Click OK. |
|
149 |
|
150 You should now create the file spam.def as instructed in the previous |
|
151 section. Add the source files (including the .def file) to the project, |
|
152 using "Project", "Add Existing Item". |
|
153 |
|
154 Now open the |
|
155 Project -> spam properties... |
|
156 dialog. (Impressive, isn't it? :-) You only need to change a few |
|
157 settings. Make sure "All Configurations" is selected from the "Settings |
|
158 for:" dropdown list. Select the "C/C++" tab. Choose the "General" |
|
159 category in the popup menu at the top. Type the following text in the |
|
160 entry box labeled "Addditional Include Directories:" |
|
161 |
|
162 ..\Include,..\PC |
|
163 |
|
164 Then, choose the "General" category in the "Linker" tab, and enter |
|
165 ..\PCbuild |
|
166 in the "Additional library Directories" box. |
|
167 |
|
168 Now you need to add some mode-specific settings (select "Accept" |
|
169 when asked to confirm your changes): |
|
170 |
|
171 Select "Release" in the "Configuration" dropdown list. Click the |
|
172 "Link" tab, choose the "Input" Category, and append "python24.lib" to the |
|
173 list in the "Additional Dependencies" box. |
|
174 |
|
175 Select "Debug" in the "Settings for:" dropdown list, and append |
|
176 "python24_d.lib" to the list in the Additional Dependencies" box. Then |
|
177 click on the C/C++ tab, select "Code Generation", and select |
|
178 "Multi-threaded Debug DLL" from the "Runtime library" dropdown list. |
|
179 |
|
180 Select "Release" again from the "Settings for:" dropdown list. |
|
181 Select "Multi-threaded DLL" from the "Use run-time library:" dropdown list. |
|
182 |
|
183 That's all <wink>. |