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