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