This is /home/pdm/install/Python-2.1/Doc/ext/python-ext.info, produced by makeinfo version 4.0 from ext.texi. April 15, 2001 2.1  File: python-ext.info, Node: A Cookbook Approach, Next: Differences Between UNIX and Windows, Prev: Building C and C++ Extensions on Windows, Up: Building C and C++ Extensions on Windows A Cookbook Approach =================== This section was written by Neil Schemenauer . This section provides a recipe for building a Python extension on Windows. Grab the binary installer from and install Python. The binary installer has all of the required header files except for `config.h'. Get the source distribution and extract it into a convenient location. Copy the `config.h' from the `PC/' directory into the `include/' directory created by the installer. Create a `Setup' file for your extension module, as described in chapter *Note Building C and C++ Extensions on UNIX::. Get David Ascher's `compile.py' script from . Run the script to create Microsoft Visual C++ project files. Open the DSW file in Visual C++ and select *Build*. If your module creates a new type, you may have trouble with this line: PyObject_HEAD_INIT(&PyType_Type) Change it to: PyObject_HEAD_INIT(NULL) and add the following to the module initialization function: MyObject_Type.ob_type = &PyType_Type; Refer to section 3 of the for details on why you must do this.  File: python-ext.info, Node: Differences Between UNIX and Windows, Next: Using DLLs in Practice, Prev: A Cookbook Approach, Up: Building C and C++ Extensions on Windows Differences Between UNIX and Windows ==================================== This section was written by Chris Phoenix . UNIX and Windows use completely different paradigms for run-time loading of code. Before you try to build a module that can be dynamically loaded, be aware of how your system works. In UNIX, a shared object (`.so') file contains code to be used by the program, and also the names of functions and data that it expects to find in the program. When the file is joined to the program, all references to those functions and data in the file's code are changed to point to the actual locations in the program where the functions and data are placed in memory. This is basically a link operation. In Windows, a dynamic-link library (`.dll') file has no dangling references. Instead, an access to functions or data goes through a lookup table. So the DLL code does not have to be fixed up at runtime to refer to the program's memory; instead, the code already uses the DLL's lookup table, and the lookup table is modified at runtime to point to the functions and data. In UNIX, there is only one type of library file (`.a') which contains code from several object files (`.o'). During the link step to create a shared object file (`.so'), the linker may find that it doesn't know where an identifier is defined. The linker will look for it in the object files in the libraries; if it finds it, it will include all the code from that object file. In Windows, there are two types of library, a static library and an import library (both called `.lib'). A static library is like a UNIX `.a' file; it contains code to be included as necessary. An import library is basically used only to reassure the linker that a certain identifier is legal, and will be present in the program when the DLL is loaded. So the linker uses the information from the import library to build the lookup table for using identifiers that are not included in the DLL. When an application or a DLL is linked, an import library may be generated, which will need to be used for all future DLLs that depend on the symbols in the application or DLL. Suppose you are building two dynamic-load modules, B and C, which should share another block of code A. On UNIX, you would _not_ pass `A.a' to the linker for `B.so' and `C.so'; that would cause it to be included twice, so that B and C would each have their own copy. In Windows, building `A.dll' will also build `A.lib'. You _do_ pass `A.lib' to the linker for B and C. `A.lib' does not contain code; it just contains information which will be used at runtime to access A's code. In Windows, using an import library is sort of like using `import spam'; it gives you access to spam's names, but does not create a separate copy. On UNIX, linking with a library is more like `from spam import *'; it does create a separate copy.  File: python-ext.info, Node: Using DLLs in Practice, Prev: Differences Between UNIX and Windows, Up: Building C and C++ Extensions on Windows Using DLLs in Practice ====================== This section was written by Chris Phoenix . Windows Python is built in Microsoft Visual C++; using other compilers may or may not work (though Borland seems to). The rest of this section is MSVC++ specific. When creating DLLs in Windows, you must pass `python15.lib' to the linker. To build two DLLs, spam and ni (which uses C functions found in spam), you could use these commands: cl /LD /I/python/include spam.c ../libs/python15.lib cl /LD /I/python/include ni.c spam.lib ../libs/python15.lib The first command created three files: `spam.obj', `spam.dll' and `spam.lib'. `Spam.dll' does not contain any Python functions (such as `PyArg_ParseTuple()'), but it does know how to find the Python code thanks to `python15.lib'. The second command created `ni.dll' (and `.obj' and `.lib'), which knows how to find the necessary functions from spam, and also from the Python executable. Not every identifier is exported to the lookup table. If you want any other modules (including Python) to be able to see your identifiers, you have to say `_declspec(dllexport)', as in `void _declspec(dllexport) initspam(void)' or `PyObject _declspec(dllexport) *NiGetSpamData(void)'. Developer Studio will throw in a lot of import libraries that you do not really need, adding about 100K to your executable. To get rid of them, use the Project Settings dialog, Link tab, to specify _ignore default libraries_. Add the correct `msvcrtXX.lib' to the list of libraries.  File: python-ext.info, Node: Embedding Python in Another Application, Next: Reporting Bugs, Prev: Building C and C++ Extensions on Windows, Up: Top Embedding Python in Another Application *************************************** Embedding Python is similar to extending it, but not quite. The difference is that when you extend Python, the main program of the application is still the Python interpreter, while if you embed Python, the main program may have nothing to do with Python -- instead, some parts of the application occasionally call the Python interpreter to run some Python code. So if you are embedding Python, you are providing your own main program. One of the things this main program has to do is initialize the Python interpreter. At the very least, you have to call the function `Py_Initialize()' (on MacOS, call `PyMac_Initialize()' instead). There are optional calls to pass command line arguments to Python. Then later you can call the interpreter from any part of the application. There are several different ways to call the interpreter: you can pass a string containing Python statements to `PyRun_SimpleString()', or you can pass a stdio file pointer and a file name (for identification in error messages only) to `PyRun_SimpleFile()'. You can also call the lower-level operations described in the previous chapters to construct and use Python objects. A simple demo of embedding Python can be found in the directory `Demo/embed/' of the source distribution. * Menu: * Embedding Python in C++:: * Linking Requirements::  File: python-ext.info, Node: Embedding Python in C++, Next: Linking Requirements, Prev: Embedding Python in Another Application, Up: Embedding Python in Another Application Embedding Python in C++ ======================= It is also possible to embed Python in a C++ program; precisely how this is done will depend on the details of the C++ system used; in general you will need to write the main program in C++, and use the C++ compiler to compile and link your program. There is no need to recompile Python itself using C++.  File: python-ext.info, Node: Linking Requirements, Prev: Embedding Python in C++, Up: Embedding Python in Another Application Linking Requirements ==================== While the `configure' script shipped with the Python sources will correctly build Python to export the symbols needed by dynamically linked extensions, this is not automatically inherited by applications which embed the Python library statically, at least on UNIX. This is an issue when the application is linked to the static runtime library (`libpython.a') and needs to load dynamic extensions (implemented as `.so' files). The problem is that some entry points are defined by the Python runtime solely for extension modules to use. If the embedding application does not use any of these entry points, some linkers will not include those entries in the symbol table of the finished executable. Some additional options are needed to inform the linker not to remove these symbols. Determining the right options to use for any given platform can be quite difficult, but fortunately the Python configuration already has those values. To retrieve them from an installed Python interpreter, start an interactive interpreter and have a short session like this: >>> import distutils.sysconfig >>> distutils.sysconfig.get_config_var('LINKFORSHARED') '-Xlinker -export-dynamic' The contents of the string presented will be the options that should be used. If the string is empty, there's no need to add any additional options. The `LINKFORSHARED' definition corresponds to the variable of the same name in Python's top-level `Makefile'.  File: python-ext.info, Node: Reporting Bugs, Next: Module Index, Prev: Embedding Python in Another Application, Up: Top Reporting Bugs ************** Python is a mature programming language which has established a reputation for stability. In order to maintain this reputation, the developers would like to know of any deficiencies you find in Python or its documentation. All bug reports should be submitted via the Python Bug Tracker on SourceForge (). The bug tracker offers a Web form which allows pertinent information to be entered and submitted to the developers. Before submitting a report, please log into SourceForge if you are a member; this will make it possible for the developers to contact you for additional information if needed. If you are not a SourceForge member but would not mind the developers contacting you, you may include your email address in your bug description. In this case, please realize that the information is publically available and cannot be protected. The first step in filing a report is to determine whether the problem has already been reported. The advantage in doing so, aside from saving the developers time, is that you learn what has been done to fix it; it may be that the problem has already been fixed for the next release, or additional information is needed (in which case you are welcome to provide it if you can!). To do this, search the bug database using the search box near the bottom of the page. If the problem you're reporting is not already in the bug tracker, go back to the Python Bug Tracker (). Select the "Submit a Bug" link at the top of the page to open the bug reporting form. The submission form has a number of fields. The only fields that are required are the "Summary" and "Details" fields. For the summary, enter a _very_ short description of the problem; less than ten words is good. In the Details field, describe the problem in detail, including what you expected to happen and what did happen. Be sure to include the version of Python you used, whether any extension modules were involved, and what hardware and software platform you were using (including version information as appropriate). The only other field that you may want to set is the "Category" field, which allows you to place the bug report into a broad category (such as "Documentation" or "Library"). Each bug report will be assigned to a developer who will determine what needs to be done to correct the problem. If you have a SourceForge account and logged in to report the problem, you will receive an update each time action is taken on the bug. See also: `How to Report Bugs Effectively'{Article which goes into some detail about how to create a useful bug report. This describes what kind of information is useful and why it is useful.} `Bug Writing Guidelines'{Information about writing a good bug report. Some of this is specific to the Mozilla project, but describes general good practices.}  File: python-ext.info, Node: Module Index, Next: Miscellaneous Index, Prev: Reporting Bugs, Up: Top Module Index ************ * Menu: * distutils: Distributing your extension modules. * distutils.sysconfig: Linking Requirements.  File: python-ext.info, Node: Miscellaneous Index, Prev: Module Index, Up: Top Miscellaneous Index ******************* * Menu: * Philbrick, Geoff: Keyword Parameters for Extension Functions.