Doc/extending/building.rst

   1 .. highlightlang:: c
   2
   3
   4 .. _building:
   5
   6 ********************************************
   7 Building C and C++ Extensions with distutils
   8 ********************************************
   9
  10 .. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
  11
  12
  13 Starting in Python 1.4, Python provides, on Unix, a special make file for
  14 building make files for building dynamically-linked extensions and custom
  15 interpreters.  Starting with Python 2.0, this mechanism (known as related to
  16 Makefile.pre.in, and Setup files) is no longer supported. Building custom
  17 interpreters was rarely used, and extension modules can be built using
  18 distutils.
  19
  20 Building an extension module using distutils requires that distutils is
  21 installed on the build machine, which is included in Python 2.x and available
  22 separately for Python 1.5. Since distutils also supports creation of binary
  23 packages, users don't necessarily need a compiler and distutils to install the
  24 extension.
  25
  26 A distutils package contains a driver script, :file:`setup.py`. This is a plain
  27 Python file, which, in the most simple case, could look like this::
  28
  29    from distutils.core import setup, Extension
  30
  31    module1 = Extension('demo',
  32                        sources = ['demo.c'])
  33
  34    setup (name = 'PackageName',
  35           version = '1.0',
  36           description = 'This is a demo package',
  37           ext_modules = [module1])
  38
  39
  40 With this :file:`setup.py`, and a file :file:`demo.c`, running ::
  41
  42    python setup.py build
  43
  44 will compile :file:`demo.c`, and produce an extension module named ``demo`` in
  45 the :file:`build` directory. Depending on the system, the module file will end
  46 up in a subdirectory :file:`build/lib.system`, and may have a name like
  47 :file:`demo.so` or :file:`demo.pyd`.
  48
  49 In the :file:`setup.py`, all execution is performed by calling the ``setup``
  50 function. This takes a variable number of keyword arguments, of which the
  51 example above uses only a subset. Specifically, the example specifies
  52 meta-information to build packages, and it specifies the contents of the
  53 package.  Normally, a package will contain of addition modules, like Python
  54 source modules, documentation, subpackages, etc. Please refer to the distutils
  55 documentation in :ref:`distutils-index` to learn more about the features of
  56 distutils; this section explains building extension modules only.
  57
  58 It is common to pre-compute arguments to :func:`setup`, to better structure the
  59 driver script. In the example above, the\ ``ext_modules`` argument to
  60 :func:`setup` is a list of extension modules, each of which is an instance of
  61 the :class:`Extension`. In the example, the instance defines an extension named
  62 ``demo`` which is build by compiling a single source file, :file:`demo.c`.
  63
  64 In many cases, building an extension is more complex, since additional
  65 preprocessor defines and libraries may be needed. This is demonstrated in the
  66 example below. ::
  67
  68    from distutils.core import setup, Extension
  69
  70    module1 = Extension('demo',
  71                        define_macros = [('MAJOR_VERSION', '1'),
  72                                         ('MINOR_VERSION', '0')],
  73                        include_dirs = ['/usr/local/include'],
  74                        libraries = ['tcl83'],
  75                        library_dirs = ['/usr/local/lib'],
  76                        sources = ['demo.c'])
  77
  78    setup (name = 'PackageName',
  79           version = '1.0',
  80           description = 'This is a demo package',
  81           author = 'Martin v. Loewis',
  82           author_email = 'martin@v.loewis.de',
  83           url = 'http://docs.python.org/extending/building',
  84           long_description = '''
  85    This is really just a demo package.
  86    ''',
  87           ext_modules = [module1])
  88
  89
  90 In this example, :func:`setup` is called with additional meta-information, which
  91 is recommended when distribution packages have to be built. For the extension
  92 itself, it specifies preprocessor defines, include directories, library
  93 directories, and libraries. Depending on the compiler, distutils passes this
  94 information in different ways to the compiler. For example, on Unix, this may
  95 result in the compilation commands ::
  96
  97    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
  98
  99    gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so
 100
 101 These lines are for demonstration purposes only; distutils users should trust
 102 that distutils gets the invocations right.
 103
 104
 105 .. _distributing:
 106
 107 Distributing your extension modules
 108 ===================================
 109
 110 When an extension has been successfully build, there are three ways to use it.
 111
 112 End-users will typically want to install the module, they do so by running ::
 113
 114    python setup.py install
 115
 116 Module maintainers should produce source packages; to do so, they run ::
 117
 118    python setup.py sdist
 119
 120 In some cases, additional files need to be included in a source distribution;
 121 this is done through a :file:`MANIFEST.in` file; see the distutils documentation
 122 for details.
 123
 124 If the source distribution has been build successfully, maintainers can also
 125 create binary distributions. Depending on the platform, one of the following
 126 commands can be used to do so. ::
 127
 128    python setup.py bdist_wininst
 129    python setup.py bdist_rpm
 130    python setup.py bdist_dumb
 131