From 6688430646633be1053a350eead4d6c70e4985cd Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 16 Aug 2023 16:00:43 +0100 Subject: [PATCH 1/6] Redirect to Setuptools' guidance on extension modules --- Doc/extending/windows.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/extending/windows.rst b/Doc/extending/windows.rst index cd81b443603d17..7e5ed4af40bfcb 100644 --- a/Doc/extending/windows.rst +++ b/Doc/extending/windows.rst @@ -14,11 +14,13 @@ 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 +Module authors are encouraged to use the ``setuptools`` 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++. +.. _building extension modules: https://setuptools.pypa.io/en/latest/userguide/ext_modules.html + .. note:: This chapter mentions a number of filenames that include an encoded Python From 8d392bf12bf309ed8ac811332012026c78157264 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 16 Aug 2023 16:18:24 +0100 Subject: [PATCH 2/6] Remove "Building C and C++ Extensions on Windows" --- Doc/extending/building.rst | 1 + Doc/extending/windows.rst | 163 ------------------------------------- Doc/using/windows.rst | 2 - 3 files changed, 1 insertion(+), 165 deletions(-) delete mode 100644 Doc/extending/windows.rst diff --git a/Doc/extending/building.rst b/Doc/extending/building.rst index 098dde39ea597e..48e553cba9c988 100644 --- a/Doc/extending/building.rst +++ b/Doc/extending/building.rst @@ -14,6 +14,7 @@ See :ref:`extension-modules` for details. .. highlight:: c +.. _building-on-windows: .. _install-index: .. _setuptools-index: diff --git a/Doc/extending/windows.rst b/Doc/extending/windows.rst deleted file mode 100644 index 7e5ed4af40bfcb..00000000000000 --- a/Doc/extending/windows.rst +++ /dev/null @@ -1,163 +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 ``setuptools`` 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++. - -.. _building extension modules: https://setuptools.pypa.io/en/latest/userguide/ext_modules.html - -.. 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 -==================================== - -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. - -.. c:macro:: Py_NO_LINK_LIB - - Turn off the implicit, ``#pragma``-based linkage with the Python - library, performed inside CPython header files. - - .. versionadded:: 3.14 - - -.. _win-dlls: - -Using DLLs in Practice -====================== - -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 can use the CPython library in two ways: - -1. By default, inclusion of :file:`PC/pyconfig.h` directly or via - :file:`Python.h` triggers an implicit, configure-aware link with the - library. The header file chooses :file:`pythonXY_d.lib` for Debug, - :file:`pythonXY.lib` for Release, and :file:`pythonX.lib` for Release with - the :ref:`Limited API ` enabled. - - 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 - cl /LD /I/python/include ni.c spam.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 the implicitly linked :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. - -2. Manually by defining :c:macro:`Py_NO_LINK_LIB` macro before including - :file:`Python.h`. 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 /DPy_NO_LINK_LIB /I/python/include spam.c ../libs/pythonXY.lib - cl /LD /DPy_NO_LINK_LIB /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:`msvcrt{xx}.lib` to the list of libraries. diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index a8350980767a44..163466478dc6a3 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -1544,5 +1544,3 @@ Visual Studio, which is the compiler used to build the official Python 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`. From 373746f35c1824bb44effd6f92652bb127eee5e0 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 16 Aug 2023 22:33:08 +0100 Subject: [PATCH 3/6] Add note to building.rst --- Doc/extending/building.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Doc/extending/building.rst b/Doc/extending/building.rst index 48e553cba9c988..7228f90506a1a2 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: From 25952c04309ee427c3a5c1a3c31ebfc3dce2388f Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 16 Aug 2023 22:36:34 +0100 Subject: [PATCH 4/6] Remove extending/windows from toctree --- Doc/extending/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/extending/index.rst b/Doc/extending/index.rst index 0f0686ea40e75b..0099dcdc4a8fa4 100644 --- a/Doc/extending/index.rst +++ b/Doc/extending/index.rst @@ -92,7 +92,6 @@ C extensions. * :ref:`defining-new-types` * :ref:`new-types-topics` * :ref:`building` -* :ref:`building-on-windows` Embedding the CPython runtime in a larger application ===================================================== From 98cc4f13f6e25d3dd8658e47d851e3fad4192a88 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 16 Aug 2023 22:40:30 +0100 Subject: [PATCH 5/6] Update link in pyport.h --- Include/exports.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Include/exports.h b/Include/exports.h index 18692283005e59..8121e905b96a37 100644 --- a/Include/exports.h +++ b/Include/exports.h @@ -75,7 +75,7 @@ /* 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__ */ From 00143b506c75f01f4125e218ee735a7b4258efe2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Langa?= Date: Wed, 21 Oct 2026 03:23:14 +0200 Subject: [PATCH 6/6] Fix CI: drop deleted windows.rst from toctree, keep Py_NO_LINK_LIB documented (gh-108030) Co-authored-by: Muse Code (Meta Muse Spark) --- Doc/extending/building.rst | 8 ++++++++ Doc/extending/index.rst | 1 - 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/Doc/extending/building.rst b/Doc/extending/building.rst index 7228f90506a1a2..b295cf774ddffa 100644 --- a/Doc/extending/building.rst +++ b/Doc/extending/building.rst @@ -37,3 +37,11 @@ https://setuptools.pypa.io/en/latest/setuptools.html. The :mod:`distutils` module, which was included in the standard library until Python 3.12, is now maintained as part of Setuptools. + + +.. c:macro:: Py_NO_LINK_LIB + + Turn off the implicit, ``#pragma``-based linkage with the Python + library, performed inside CPython header files. + + .. versionadded:: 3.14 diff --git a/Doc/extending/index.rst b/Doc/extending/index.rst index 0099dcdc4a8fa4..a11e795377c537 100644 --- a/Doc/extending/index.rst +++ b/Doc/extending/index.rst @@ -51,7 +51,6 @@ source file by including the header ``"Python.h"``. newtypes_tutorial.rst newtypes.rst building.rst - windows.rst embedding.rst