diff --git a/Doc/extending/building.rst b/Doc/extending/building.rst index 69dffbd56a..0f37078cdc 100644 --- a/Doc/extending/building.rst +++ b/Doc/extending/building.rst @@ -11,7 +11,7 @@ A C extension for CPython is a shared library (e.g. a ``.so`` file on Linux, To be importable, the shared library must be available on :envvar:`PYTHONPATH`, and must be named after the module name, with an appropriate extension. -When using distutils, the correct filename is generated automatically. +When using setuptools, the correct filename is generated automatically. The initialization function has the signature: @@ -45,21 +45,21 @@ See the *"Multiple modules in one library"* section in :pep:`489` for details. .. highlight:: c -Building C and C++ Extensions with distutils -============================================ +Building C and C++ Extensions with setuptools +============================================= .. sectionauthor:: Martin v. Löwis -Extension modules can be built using distutils, which is included in Python. -Since distutils also supports creation of binary packages, users don't -necessarily need a compiler and distutils to install the extension. +Extension modules can be built using setuptools, which is silently installed by pip +behind the scenes. Since setuptools also supports creation of binary packages, users don't +necessarily need a compiler and setuptools to install the extension. -A distutils package contains a driver script, :file:`setup.py`. This is a plain +A setuptools package contains a driver script, :file:`setup.py`. This is a plain Python file, which, in the most simple case, could look like this: .. code-block:: python3 - from distutils.core import setup, Extension + from setuptools import setup, Extension module1 = Extension('demo', sources = ['demo.c']) @@ -84,15 +84,13 @@ function. This takes a variable number of keyword arguments, of which the example above uses only a subset. Specifically, the example specifies meta-information to build packages, and it specifies the contents of the package. Normally, a package will contain additional modules, like Python -source modules, documentation, subpackages, etc. Please refer to the distutils -documentation in :ref:`distutils-index` to learn more about the features of -distutils; this section explains building extension modules only. +source modules, documentation, subpackages, etc. It is common to pre-compute arguments to :func:`setup`, to better structure the driver script. In the example above, the ``ext_modules`` argument to -:func:`~distutils.core.setup` is a list of extension modules, each of which is +:func:`setup` is a list of extension modules, each of which is an instance of -the :class:`~distutils.extension.Extension`. In the example, the instance +the :class:`Extension`. In the example, the instance defines an extension named ``demo`` which is build by compiling a single source file, :file:`demo.c`. @@ -102,7 +100,7 @@ example below. .. code-block:: python3 - from distutils.core import setup, Extension + from setuptools import setup, Extension module1 = Extension('demo', define_macros = [('MAJOR_VERSION', '1'), @@ -124,21 +122,12 @@ example below. ext_modules = [module1]) -In this example, :func:`~distutils.core.setup` is called with additional +In this example, :func:`setup` is called with additional meta-information, which is recommended when distribution packages have to be built. For the extension itself, it specifies preprocessor defines, include directories, library -directories, and libraries. Depending on the compiler, distutils passes this -information in different ways to the compiler. For example, on Unix, this may -result in the compilation commands :: - - gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o - - gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so - -These lines are for demonstration purposes only; distutils users should trust -that distutils gets the invocations right. - +directories, and libraries. Depending on the compiler, setuptools passes this +information in different ways to the compiler. .. _distributing: diff --git a/Doc/extending/windows.rst b/Doc/extending/windows.rst index c7b92c6ea2..3337224c29 100644 --- a/Doc/extending/windows.rst +++ b/Doc/extending/windows.rst @@ -14,7 +14,7 @@ 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 +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++. @@ -34,12 +34,11 @@ A Cookbook Approach =================== There are two approaches to building extension modules on Windows, just as there -are on Unix: use the :mod:`distutils` package to control the build process, or -do things manually. The distutils approach works well for most extensions; -documentation on using :mod:`distutils` to build and package extension modules -is available in :ref:`distutils-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. +are on Unix: use the ``setuptools`` package to control the build process, or +do things manually. The ``setuptools`` approach works well for most extensions. +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: @@ -106,15 +105,18 @@ Using DLLs in Practice 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. +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 + cl /LD -I/pathtopython/include spam.c pathtopython/libs/pythonXY.lib + cl /LD -I/pathtopython/include ni.c spam.lib pathtopython/libs/pythonXY.lib + +.. note:: + + The above commands only work for Python 32-bit versions. 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 @@ -130,8 +132,9 @@ 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. +Create Python Extensions in Visual Studio +========================================= + +For creating Python extensions in Visual Studio, please refer to +https://docs.microsoft.com/en-us/visualstudio/python/working-with-c-cpp-python-in-visual-studio.