diff --git a/Doc/extending/building.rst b/Doc/extending/building.rst index ddde567f6f3efa..67671cf2d4114b 100644 --- a/Doc/extending/building.rst +++ b/Doc/extending/building.rst @@ -1,3 +1,11 @@ +.. + The guides to building C and C++ extensions are fairly out of date + and would benefit from re-writing in terms of a simple primer, + with specific reference to sysconfig, and how a modules can be build + 'by hand', rather than via setuptools, CMake, meson, etc. + If you're reading this and would like to have a go, please do! + See https://github.com/python/cpython/issues/108064 for discussion. + .. highlight:: c .. _building: @@ -45,6 +53,7 @@ See the *"Multiple modules in one library"* section in :pep:`489` for details. .. highlight:: c +.. _building-on-windows: .. _install-index: .. _setuptools-index: @@ -52,6 +61,7 @@ Building C and C++ Extensions with setuptools ============================================= Python 3.12 and newer no longer come with distutils. Please refer to the -``setuptools`` documentation at -https://setuptools.readthedocs.io/en/latest/setuptools.html +``setuptools`` documentation for `building extension modules`_ to learn more about how build and distribute C/C++ extensions with setuptools. + +.. _building extension modules: https://setuptools.pypa.io/en/latest/userguide/ext_modules.html diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index f58b4f28113e8c..52ccda5464a802 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -458,10 +458,9 @@ Compilation and Linkage There are two more things to do before you can use your new extension: compiling and linking it with the Python system. If you use dynamic loading, the details -may depend on the style of dynamic loading your system uses; see the chapters -about building extension modules (chapter :ref:`building`) and additional -information that pertains only to building on Windows (chapter -:ref:`building-on-windows`) for more information about this. +may depend on the style of dynamic loading your system uses; see the chapter +about building extension modules (chapter :ref:`building`) +for more information about this. If you can't use dynamic loading, or if you want to make your module a permanent part of the Python interpreter, you will have to change the configuration setup diff --git a/Doc/extending/index.rst b/Doc/extending/index.rst index 01b4df6d44acff..7d206aa7aca958 100644 --- a/Doc/extending/index.rst +++ b/Doc/extending/index.rst @@ -57,7 +57,6 @@ C extensions. newtypes_tutorial.rst newtypes.rst building.rst - windows.rst Embedding the CPython runtime in a larger application ===================================================== diff --git a/Doc/extending/windows.rst b/Doc/extending/windows.rst deleted file mode 100644 index 1129b0968bc4e6..00000000000000 --- a/Doc/extending/windows.rst +++ /dev/null @@ -1,135 +0,0 @@ -.. highlight:: c - - -.. _building-on-windows: - -**************************************** -Building C and C++ Extensions on Windows -**************************************** - -This chapter briefly explains how to create a Windows extension module for -Python using Microsoft Visual C++, and follows with more detailed background -information on how it works. The explanatory material is useful for both the -Windows programmer learning to build Python extensions and the Unix programmer -interested in producing software which can be successfully built on both Unix -and Windows. - -Module authors are encouraged to use the distutils approach for building -extension modules, instead of the one described in this section. You will still -need the C compiler that was used to build Python; typically Microsoft Visual -C++. - -.. note:: - - This chapter mentions a number of filenames that include an encoded Python - version number. These filenames are represented with the version number shown - as ``XY``; in practice, ``'X'`` will be the major version number and ``'Y'`` - will be the minor version number of the Python release you're working with. For - example, if you are using Python 2.2.1, ``XY`` will actually be ``22``. - - -.. _win-cookbook: - -A Cookbook Approach -=================== - -There are two approaches to building extension modules on Windows, just as there -are on Unix: use the ``setuptools`` package to control the build process, or -do things manually. The setuptools approach works well for most extensions; -documentation on using ``setuptools`` to build and package extension modules -is available in :ref:`setuptools-index`. If you find you really need to do -things manually, it may be instructive to study the project file for the -:source:`winsound ` standard library module. - - -.. _dynamic-linking: - -Differences Between Unix and Windows -==================================== - -.. sectionauthor:: 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 (:file:`.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 (:file:`.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 (:file:`.a`) which contains code -from several object files (:file:`.o`). During the link step to create a shared -object file (: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 :file:`.lib`). A static library is like a Unix :file:`.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 :file:`A.a` to the -linker for :file:`B.so` and :file:`C.so`; that would cause it to be included -twice, so that B and C would each have their own copy. In Windows, building -:file:`A.dll` will also build :file:`A.lib`. You *do* pass :file:`A.lib` to the -linker for B and C. :file:`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. - - -.. _win-dlls: - -Using DLLs in Practice -====================== - -.. sectionauthor:: Chris Phoenix - - -Windows Python is built in Microsoft Visual C++; using other compilers may or -may not work. The rest of this section is MSVC++ specific. - -When creating DLLs in Windows, you must pass :file:`pythonXY.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/pythonXY.lib - cl /LD /I/python/include ni.c spam.lib ../libs/pythonXY.lib - -The first command created three files: :file:`spam.obj`, :file:`spam.dll` and -:file:`spam.lib`. :file:`Spam.dll` does not contain any Python functions (such -as :c:func:`PyArg_ParseTuple`), but it does know how to find the Python code -thanks to :file:`pythonXY.lib`. - -The second command created :file:`ni.dll` (and :file:`.obj` and :file:`.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 :file:`msvcrtxx.lib` to the list of libraries. diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index ca79c9d3a9d3a8..7fabb543ccd435 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -1266,8 +1266,6 @@ releases. These files are in the :file:`PCbuild` directory. Check :file:`PCbuild/readme.txt` for general information on the build process. -For extension modules, consult :ref:`building-on-windows`. - Other Platforms =============== diff --git a/Include/pyport.h b/Include/pyport.h index d7c6ae64f2bf2f..fdceb29dc17ff9 100644 --- a/Include/pyport.h +++ b/Include/pyport.h @@ -528,7 +528,7 @@ extern char * _getpty(int *, int, mode_t, int); /* public Python functions and data are imported */ /* Under Cygwin, auto-import functions to prevent compilation */ /* failures similar to those described at the bottom of 4.1: */ - /* http://docs.python.org/extending/windows.html#a-cookbook-approach */ + /* https://docs.python.org/3.2/extending/windows.html#a-cookbook-approach */ # if !defined(__CYGWIN__) # define PyAPI_FUNC(RTYPE) Py_IMPORTED_SYMBOL RTYPE # endif /* !__CYGWIN__ */