Guido van Rossum | 29168ce | 1997-05-16 16:17:20 +0000 | [diff] [blame] | 1 | Example Python extension for Windows NT
|
| 2 | =======================================
|
| 3 |
|
| 4 | This directory contains everything you need to build a Python
|
Guido van Rossum | 55b8b03 | 1997-12-11 04:01:25 +0000 | [diff] [blame^] | 5 | extension module using Microsoft VC++ ("Developer Studio") version 4.x
|
| 6 | or 5.x, except for the Python distribution. It has been tested with
|
| 7 | VC++ 4.2 on Python 1.5a3, and with VC++ 5.0 on Python 1.5b2.
|
Guido van Rossum | 29168ce | 1997-05-16 16:17:20 +0000 | [diff] [blame] | 8 |
|
| 9 | The "example_nt" subdirectory should be an immediate subdirectory of
|
| 10 | the Python source directory -- a direct sibling of Include and PC, in
|
| 11 | particular, which are referenced as "..\Include" and "..\PC". In
|
| 12 | other words, it should *not* be used "as is". Copy or move it up one
|
| 13 | level or you will regret it! (This is done to keep all the PC
|
| 14 | specific files inside the PC subdirectory of the distribution, where
|
| 15 | they belong.)
|
| 16 |
|
Guido van Rossum | 55b8b03 | 1997-12-11 04:01:25 +0000 | [diff] [blame^] | 17 | When using the VC++ 4.x project (makefile), it is assumed that the
|
| 18 | build results of Python are in the directory ..\vc40. In particular,
|
| 19 | the python15.lib file is referred to as "..\vc40\python15.lib". If
|
| 20 | you have problems with this file, the best thing to do is to delete it
|
| 21 | from the project and add it again.
|
Guido van Rossum | 29168ce | 1997-05-16 16:17:20 +0000 | [diff] [blame] | 22 |
|
Guido van Rossum | 55b8b03 | 1997-12-11 04:01:25 +0000 | [diff] [blame^] | 23 | When using the VC++ 5.x project (workspace), the build results of
|
| 24 | Python are assumed to be in ..\PCbuild. Since the provided VC++ 5.x
|
| 25 | project and workspace files have a different structure (to support
|
| 26 | separate "release" and "debug" builds), the example project and
|
| 27 | workspace match this structure.
|
| 28 |
|
| 29 | In order to use the example project from VC++ 4.x, use the "File->Open
|
| 30 | Workspace..." dialog (*not* the "File->Open..." dialog!). Change the
|
| 31 | pattern to "*.mak" and select the file "example.mak". Now choose
|
| 32 | "File->Save All" and the othe project files will be created.
|
| 33 |
|
| 34 | From VC+ 5.x, do the same except don't change the pattern, and select
|
| 35 | the example.dsw workspace file.
|
Guido van Rossum | 29168ce | 1997-05-16 16:17:20 +0000 | [diff] [blame] | 36 |
|
| 37 | In order to check that everything is set up right, try building:
|
| 38 | choose "Build->Build example.dll". This creates all intermediate and
|
| 39 | result files in a subdirectory which is called either Debug or Release
|
Guido van Rossum | 55b8b03 | 1997-12-11 04:01:25 +0000 | [diff] [blame^] | 40 | depending on which configuration you have chosen.
|
Guido van Rossum | 29168ce | 1997-05-16 16:17:20 +0000 | [diff] [blame] | 41 |
|
| 42 | Once the build has succeeded, test the resulting DLL. In a DOS
|
| 43 | command window, chdir to that directory. You should now be able to
|
| 44 | repeat the following session "(C>" is the DOS prompt, ">>>" is the
|
| 45 | Python prompt):
|
| 46 |
|
| 47 | C> ..\..\vc40\python.exe
|
| 48 | >>> import example
|
| 49 | >>> example.foo()
|
| 50 | Hello, world
|
| 51 | >>>
|
| 52 |
|
Guido van Rossum | 55b8b03 | 1997-12-11 04:01:25 +0000 | [diff] [blame^] | 53 | When using VC++ 5.x, issue these commands:
|
| 54 |
|
| 55 | C> ..\..\PCbuild\Release\python.exe
|
| 56 | >>> import example
|
| 57 | >>> example.foo()
|
| 58 | Hello, world
|
| 59 | >>>
|
| 60 |
|
Guido van Rossum | 29168ce | 1997-05-16 16:17:20 +0000 | [diff] [blame] | 61 |
|
| 62 | Creating the project
|
| 63 | --------------------
|
| 64 |
|
| 65 | There are two ways to use this example to create a project for your
|
| 66 | own module. First, choose a name ("spam" is always a winner :-) and
|
| 67 | create a directory for it. Copy your C sources into it. Note that
|
| 68 | the module source file name does not necessarily have to match the
|
| 69 | module name, but the "init" function name should match the module name
|
| 70 | -- i.e. you can only import a module "spam" if its init function is
|
| 71 | called "initspam()", and it should call Py_InitModule with the string
|
| 72 | "spam" as its first argument. By convention, it lives in a file
|
| 73 | called "spam.c" or "spammodule.c". The output file should be called
|
| 74 | "spam.dll" or "spam.pyd" (the latter is supported to avoid confusion
|
| 75 | with a system library "spam.dll" to which your module could be a
|
| 76 | Python interface).
|
| 77 |
|
| 78 | Now your options are:
|
| 79 |
|
| 80 | 1) Clone example.mak. Start by copying example_nt\example.mak to
|
| 81 | spam\spam.mak. Do a global edit on spam.mak, replacing all
|
| 82 | occurrences of the string "example" by "spam", and all occurrences of
|
| 83 | "DEP_CPP_EXAMP" by something like "DEP_CPP_SPAM". You can now use
|
| 84 | this makefile to create a project file by opening it as a workspace
|
Guido van Rossum | 55b8b03 | 1997-12-11 04:01:25 +0000 | [diff] [blame^] | 85 | (you have to change the pattern to *.mak first). (When using VC++
|
| 86 | 5.x, you can clone example.dsp and example.dsw in a similar way.)
|
Guido van Rossum | 29168ce | 1997-05-16 16:17:20 +0000 | [diff] [blame] | 87 |
|
| 88 | 2) Create a brand new project; instructions are below.
|
| 89 |
|
| 90 | In both cases, copy example_nt\example.def to spam\spam.def, and edit
|
| 91 | spam\spam.def so its second line contains the string "initspam". If
|
| 92 | you created a new project yourself, add the file spam.def to the
|
Guido van Rossum | 55b8b03 | 1997-12-11 04:01:25 +0000 | [diff] [blame^] | 93 | project now. (This is an annoying little file with only two lines.
|
| 94 | An alternative approach is to forget about the .def file, and add the
|
| 95 | option "/export:initspam" somewhere to the Link settings, by manually
|
| 96 | editing the "Project Options" box).
|
Guido van Rossum | 29168ce | 1997-05-16 16:17:20 +0000 | [diff] [blame] | 97 |
|
| 98 | You are now all set to build your extension, unless it requires other
|
| 99 | external libraries, include files, etc. See Python's Extending and
|
| 100 | Embedding manual for instructions on how to write an extension.
|
| 101 |
|
| 102 |
|
| 103 | Creating a brand new project
|
| 104 | ----------------------------
|
| 105 |
|
Guido van Rossum | 55b8b03 | 1997-12-11 04:01:25 +0000 | [diff] [blame^] | 106 | If you don't feel comfortable with editing Makefiles or project and
|
| 107 | workspace files, you can create a brand new project from scratch
|
| 108 | easily.
|
Guido van Rossum | 29168ce | 1997-05-16 16:17:20 +0000 | [diff] [blame] | 109 |
|
| 110 | Use the "File->New..." dialog to create a new Project Workspace.
|
| 111 | Select Dynamic-Link Library, enter the name ("spam"), and make sure
|
| 112 | the "Location" is set to the spam directory you have created (which
|
| 113 | should be a direct subdirectory of the Python build tree). Select
|
| 114 | Win32 as the platform (in my version, this is the only choice). Click
|
| 115 | "Create".
|
| 116 |
|
| 117 | Now open the "Build->Settings..." dialog. (Impressive, isn't it? :-)
|
| 118 | You only need to change a few settings. Make sure you have both the
|
| 119 | Debug and the Release configuration selected when you make the first
|
| 120 | change. Select the "C/C++" tab. Choose the "Preprocessor" category
|
| 121 | in the popup menu at the top. Type the following text in the entry
|
| 122 | box labeled "Addditional include directories:"
|
| 123 |
|
| 124 | ..\Include,..\PC
|
| 125 |
|
Guido van Rossum | 55b8b03 | 1997-12-11 04:01:25 +0000 | [diff] [blame^] | 126 | Next, for both configurations, select the "Link" tab, choose the
|
| 127 | "General" category, and add "python15.lib" to the end of the
|
| 128 | "Object/library modules" box.
|
| 129 |
|
| 130 | Then, separately for the Release and Debug configurations, choose the
|
| 131 | "Input" category in the Link tab, and enter "..\PCbuild\Release" or
|
| 132 | "..\PCbuild\Debug", respectively, in the "Additional library path"
|
| 133 | box.
|
| 134 |
|
| 135 | Finally, you must change the run-time library. This must also be done
|
Guido van Rossum | 29168ce | 1997-05-16 16:17:20 +0000 | [diff] [blame] | 136 | separately for the Release and Debug configurations. Choose the "Code
|
| 137 | Generation" category in the C/C++ tab. In the box labeled "Use
|
| 138 | run-time library", choose "Multithreaded DLL" for the Release
|
| 139 | configuration, and "Debug Multithreaded DLL" for the Debug
|
| 140 | configuration. That's all.
|
| 141 |
|
| 142 | You should now first create the file spam.def as instructed in the
|
| 143 | previous section.
|
| 144 |
|
| 145 | Now chose the "Insert->Files into Project..." dialog. Set the pattern
|
| 146 | to *.* and select both spam.c and spam.def and click OK. (Inserting
|
Guido van Rossum | 55b8b03 | 1997-12-11 04:01:25 +0000 | [diff] [blame^] | 147 | them one by one is fine too.)
|
| 148 |
|