/PC/example_nt/readme.txt

  1Example Python extension for Windows NT
  2=======================================
  3
  4This directory contains everything needed (except for the Python
  5distribution!) to build a Python extension module using Microsoft VC++.
  6Notice that you need to use the same compiler version that was used to build 
  7Python itself.
  8
  9The 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
 14after everything builds and installs, you can test it:
 15
 16  % python -c "import example; example.foo()"
 17  Hello, world
 18
 19See setup.py for more details.  alternatively, see below for instructions on 
 20how to build inside the Visual Studio environment.
 21
 22Visual Studio Build Instructions
 23================================
 24
 25These are instructions how to build an extension using Visual C++.  The
 26instructions and project files have not been updated to the latest VC
 27version.  In general, it is recommended you use the 'setup.py' instructions
 28above.
 29
 30It has been tested with VC++ 7.1 on Python 2.4.  You can also use earlier 
 31versions 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
 34COPY THIS DIRECTORY!
 35--------------------
 36This "example_nt" directory is a subdirectory of the PC directory, in order
 37to keep all the PC-specific files under the same directory.  However, the
 38example_nt directory can't actually be used from this location.  You first
 39need to copy or move it up one level, so that example_nt is a direct
 40sibling of the PC\ and Include\ directories.  Do all your work from within
 41this new location -- sorry, but you'll be sorry if you don't.
 42
 43OPEN THE PROJECT
 44----------------
 45From VC 7.1, use the
 46    File -> Open Solution...
 47dialog (*not* the "File -> Open..." dialog!).  Navigate to and select the
 48file "example.sln", in the *copy* of the example_nt directory you made
 49above.
 50Click Open.
 51
 52BUILD THE EXAMPLE DLL
 53---------------------
 54In order to check that everything is set up right, try building:
 55
 561. 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
 612. 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
 67TESTING THE DEBUG-MODE DLL
 68--------------------------
 69Once the Debug build has succeeded, bring up a DOS box, and cd to
 70example_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
 72debug 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
 86TESTING THE RELEASE-MODE DLL
 87----------------------------
 88Once the Release build has succeeded, bring up a DOS box, and cd to
 89example_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
100Congratulations!  You've successfully built your first Python extension
101module.
102
103CREATING YOUR OWN PROJECT
104-------------------------
105Choose a name ("spam" is always a winner :-) and create a directory for
106it.  Copy your C sources into it.  Note that the module source file name
107does not necessarily have to match the module name, but the "init" function
108name 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
110Py_InitModule with the string "spam" as its first argument (use the minimal
111example.c in this directory as a guide).  By convention, it lives in a file
112called "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
114system library "spam.dll" to which your module could be a Python interface)
115in Release mode, or spam_d.dll or spam_d.pyd in Debug mode.
116
117Now your options are:
118
1191) Copy example.sln and example.vcproj, rename them to spam.*, and edit them
120by hand.
121
122or
123
1242) Create a brand new project; instructions are below.
125
126In either case, copy example_nt\example.def to spam\spam.def, and edit the
127new spam.def so its second line contains the string "initspam".  If you
128created 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
130approach 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" 
133box).
134
135You are now all set to build your extension, unless it requires other
136external libraries, include files, etc.  See Python's Extending and
137Embedding manual for instructions on how to write an extension.
138
139
140CREATING A BRAND NEW PROJECT
141----------------------------
142Use the
143    File -> New -> Project...
144dialog to create a new Project Workspace.  Select "Visual C++ Projects/Win32/
145Win32 Project", enter the name ("spam"), and make sure the "Location" is 
146set to parent of the spam directory you have created (which should be a direct 
147subdirectory of the Python build tree, a sibling of Include and PC).  
148In "Application Settings", select "DLL", and "Empty Project".  Click OK.
149
150You should now create the file spam.def as instructed in the previous
151section. Add the source files (including the .def file) to the project, 
152using "Project", "Add Existing Item".
153
154Now open the
155    Project -> spam properties...
156dialog.  (Impressive, isn't it? :-) You only need to change a few
157settings.  Make sure "All Configurations" is selected from the "Settings
158for:" dropdown list.  Select the "C/C++" tab.  Choose the "General"
159category in the popup menu at the top.  Type the following text in the
160entry box labeled "Addditional Include Directories:"
161
162    ..\Include,..\PC
163
164Then, choose the "General" category in the "Linker" tab, and enter
165    ..\PCbuild
166in the "Additional library Directories" box.
167
168Now you need to add some mode-specific settings (select "Accept"
169when asked to confirm your changes):
170
171Select "Release" in the "Configuration" dropdown list.  Click the
172"Link" tab, choose the "Input" Category, and append "python24.lib" to the
173list in the "Additional Dependencies" box.
174
175Select "Debug" in the "Settings for:" dropdown list, and append
176"python24_d.lib" to the list in the Additional Dependencies" box.  Then
177click on the C/C++ tab, select "Code Generation", and select 
178"Multi-threaded Debug DLL" from the "Runtime library" dropdown list.
179
180Select "Release" again from the "Settings for:" dropdown list.
181Select "Multi-threaded DLL" from the "Use run-time library:" dropdown list.
182
183That's all <wink>.