diff --git a/Doc/extending/building.rst b/Doc/extending/building.rst --- a/Doc/extending/building.rst +++ b/Doc/extending/building.rst @@ -1,131 +1,117 @@ -.. highlightlang:: c - - .. _building: ******************************************** Building C and C++ Extensions with distutils ******************************************** .. sectionauthor:: Martin v. Löwis -Starting in Python 1.4, Python provides, on Unix, a special make file for -building make files for building dynamically-linked extensions and custom -interpreters. Starting with Python 2.0, this mechanism (known as related to -Makefile.pre.in, and Setup files) is no longer supported. Building custom -interpreters was rarely used, and extension modules can be built using -distutils. +.. note:: -Building an extension module using distutils requires that distutils is -installed on the build machine, which is included in Python 2.x and available -separately for Python 1.5. Since distutils also supports creation of binary -packages, users don't necessarily need a compiler and distutils to install the -extension. + Since distutils supports creation of binary packages, users don't + necessarily need a compiler and distutils to install the extension. -A distutils package contains a driver script, :file:`setup.py`. This is a plain -Python file, which, in the most simple case, could look like this:: +A :mod:`distutils` package contains a driver script, ``setup.py``. This +is a plain Python file, which, in the most simple case, could look like +this:: from distutils.core import setup, Extension - module1 = Extension('demo', - sources = ['demo.c']) + spammodule = Extension('spam', + sources=['_spammodule.c']) - setup (name = 'PackageName', - version = '1.0', - description = 'This is a demo package', - ext_modules = [module1]) + setup(name='Spam', + version='1.0', + description='This is a demo package', + ext_modules=[spammodule]) -With this :file:`setup.py`, and a file :file:`demo.c`, running :: +With this ``setup.py``, and a file ``_spammodule.c``, running - python setup.py build +.. code-block:: bash -will compile :file:`demo.c`, and produce an extension module named ``demo`` in -the :file:`build` directory. Depending on the system, the module file will end -up in a subdirectory :file:`build/lib.system`, and may have a name like -:file:`demo.so` or :file:`demo.pyd`. + $ python setup.py build -In the :file:`setup.py`, all execution is performed by calling the ``setup`` -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 of addition 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. +will compile ``_spammodule``, and produce an extension module named +``spam`` in the ``build`` directory. Depending on the system, the module +file will end up in a subdirectory ``build/lib.system``, and may have a +name like ``_spammodule.so`` or ``_spammodule.pyd``. -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:`setup` is a list of extension modules, each of which is an instance of -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`. +In the ``setup.py``, all execution is performed by calling the +:func:`~distutils.core.setup` 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 of addition +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. + +It is common to pre-compute arguments to :func:`~distutils.core.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 an instance of the :class:`~distutils.core.Extension`. In the +example, the instance defines an extension named ``spammodule`` which is build +by compiling a single source file, ``_spammodule.c``. In many cases, building an extension is more complex, since additional preprocessor defines and libraries may be needed. This is demonstrated in the -example below. :: +example below:: from distutils.core import setup, Extension - module1 = Extension('demo', - define_macros = [('MAJOR_VERSION', '1'), - ('MINOR_VERSION', '0')], - include_dirs = ['/usr/local/include'], - libraries = ['tcl83'], - library_dirs = ['/usr/local/lib'], - sources = ['demo.c']) + spammodule = Extension('spam', + define_macros=[('MAJOR_VERSION', '1'), + ('MINOR_VERSION', '0')], + include_dirs=['/usr/local/include'], + libraries=['tcl83'], + library_dirs=['/usr/local/lib'], + sources=['_spammodule.c']) - setup (name = 'PackageName', - version = '1.0', - description = 'This is a demo package', - author = 'Martin v. Loewis', - author_email = 'martin@v.loewis.de', - url = 'http://docs.python.org/extending/building', - long_description = ''' + setup(name='Spam', + version='1.0', + description='This is a demo package', + author='Martin v. Loewis', + author_email='martin@v.loewis.de', + url='http://docs.python.org/extending/building', + long_description=""" This is really just a demo package. - ''', - ext_modules = [module1]) + """, + ext_modules=[spammodule]) -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. - +In this example, :func:`~distutils.core.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. .. _distributing: Distributing your extension modules =================================== +.. highlight:: bash + When an extension has been successfully build, there are three ways to use it. End-users will typically want to install the module, they do so by running :: - python setup.py install + $ python setup.py install Module maintainers should produce source packages; to do so, they run :: - python setup.py sdist + $ python setup.py sdist In some cases, additional files need to be included in a source distribution; -this is done through a :file:`MANIFEST.in` file; see the distutils documentation -for details. +this is done through a :file:`MANIFEST.in` file; see the :ref:`manifest` +documentation for details. If the source distribution has been build successfully, maintainers can also create binary distributions. Depending on the platform, one of the following commands can be used to do so. :: - python setup.py bdist_wininst - python setup.py bdist_rpm - python setup.py bdist_dumb - + $ python setup.py bdist_wininst + $ python setup.py bdist_rpm + $ python setup.py bdist_dumb