PC/example_nt/readme.txt

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