Doc/ext/building.tex

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