PC/example_nt/readme.txt

   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>.