Doc/ext/unix.tex

   1 \chapter{Building C and \Cpp{} Extensions on \UNIX{}
   2      \label{building-on-unix}}
   3
   4 \sectionauthor{Jim Fulton}{jim@zope.com}
   5
   6
   7 %The make file make file, building C extensions on Unix
   8
   9
  10 Starting in Python 1.4, Python provides a special make file for
  11 building make files for building dynamically-linked extensions and
  12 custom interpreters.  The make file make file builds a make file
  13 that reflects various system variables determined by configure when
  14 the Python interpreter was built, so people building module's don't
  15 have to resupply these settings.  This vastly simplifies the process
  16 of building extensions and custom interpreters on \UNIX{} systems.
  17
  18 The make file make file is distributed as the file
  19 \file{Misc/Makefile.pre.in} in the Python source distribution.  The
  20 first step in building extensions or custom interpreters is to copy
  21 this make file to a development directory containing extension module
  22 source.
  23
  24 The make file make file, \file{Makefile.pre.in} uses metadata
  25 provided in a file named \file{Setup}.  The format of the \file{Setup}
  26 file is the same as the \file{Setup} (or \file{Setup.dist}) file
  27 provided in the \file{Modules/} directory of the Python source
  28 distribution.  The \file{Setup} file contains variable definitions:
  29
  30 \begin{verbatim}
  31 EC=/projects/ExtensionClass
  32 \end{verbatim}
  33
  34 and module description lines.  It can also contain blank lines and
  35 comment lines that start with \character{\#}.
  36
  37 A module description line includes a module name, source files,
  38 options, variable references, and other input files, such
  39 as libraries or object files.  Consider a simple example:
  40
  41 \begin{verbatim}
  42 ExtensionClass ExtensionClass.c
  43 \end{verbatim}
  44
  45 This is the simplest form of a module definition line.  It defines a
  46 module, \module{ExtensionClass}, which has a single source file,
  47 \file{ExtensionClass.c}.
  48
  49 This slightly more complex example uses an \strong{-I} option to
  50 specify an include directory:
  51
  52 \begin{verbatim}
  53 EC=/projects/ExtensionClass
  54 cPersistence cPersistence.c -I$(EC)
  55 \end{verbatim} % $ <-- bow to font lock
  56
  57 This example also illustrates the format for variable references.
  58
  59 For systems that support dynamic linking, the \file{Setup} file should
  60 begin:
  61
  62 \begin{verbatim}
  63 *shared*
  64 \end{verbatim}
  65
  66 to indicate that the modules defined in \file{Setup} are to be built
  67 as dynamically linked modules.  A line containing only \samp{*static*}
  68 can be used to indicate the subsequently listed modules should be
  69 statically linked.
  70
  71 Here is a complete \file{Setup} file for building a
  72 \module{cPersistent} module:
  73
  74 \begin{verbatim}
  75 # Set-up file to build the cPersistence module.
  76 # Note that the text should begin in the first column.
  77 *shared*
  78
  79 # We need the path to the directory containing the ExtensionClass
  80 # include file.
  81 EC=/projects/ExtensionClass
  82 cPersistence cPersistence.c -I$(EC)
  83 \end{verbatim} % $ <-- bow to font lock
  84
  85 After the \file{Setup} file has been created, \file{Makefile.pre.in}
  86 is run with the \samp{boot} target to create a make file:
  87
  88 \begin{verbatim}
  89 make -f Makefile.pre.in boot
  90 \end{verbatim}
  91
  92 This creates the file, Makefile.  To build the extensions, simply
  93 run the created make file:
  94
  95 \begin{verbatim}
  96 make
  97 \end{verbatim}
  98
  99 It's not necessary to re-run \file{Makefile.pre.in} if the
 100 \file{Setup} file is changed.  The make file automatically rebuilds
 101 itself if the \file{Setup} file changes.
 102
 103
 104 \section{Building Custom Interpreters \label{custom-interps}}
 105
 106 The make file built by \file{Makefile.pre.in} can be run with the
 107 \samp{static} target to build an interpreter:
 108
 109 \begin{verbatim}
 110 make static
 111 \end{verbatim}
 112
 113 Any modules defined in the \file{Setup} file before the
 114 \samp{*shared*} line will be statically linked into the interpreter.
 115 Typically, a \samp{*shared*} line is omitted from the
 116 \file{Setup} file when a custom interpreter is desired.
 117
 118
 119 \section{Module Definition Options \label{module-defn-options}}
 120
 121 Several compiler options are supported:
 122
 123 \begin{tableii}{l|l}{programopt}{Option}{Meaning}
 124   \lineii{-C}{Tell the C pre-processor not to discard comments}
 125   \lineii{-D\var{name}=\var{value}}{Define a macro}
 126   \lineii{-I\var{dir}}{Specify an include directory, \var{dir}}
 127   \lineii{-L\var{dir}}{Specify a link-time library directory, \var{dir}}
 128   \lineii{-R\var{dir}}{Specify a run-time library directory, \var{dir}}
 129   \lineii{-l\var{lib}}{Link a library, \var{lib}}
 130   \lineii{-U\var{name}}{Undefine a macro}
 131 \end{tableii}
 132
 133 Other compiler options can be included (snuck in) by putting them
 134 in variables.
 135
 136 Source files can include files with \file{.c}, \file{.C}, \file{.cc},
 137 \file{.cpp}, \file{.cxx}, and \file{.c++} extensions.
 138
 139 Other input files include files with \file{.a}, \file{.o}, \file{.sl},
 140 and \file{.so} extensions.
 141
 142
 143 \section{Example \label{module-defn-example}}
 144
 145 Here is a more complicated example from \file{Modules/Setup.dist}:
 146
 147 \begin{verbatim}
 148 GMP=/ufs/guido/src/gmp
 149 mpz mpzmodule.c -I$(GMP) $(GMP)/libgmp.a
 150 \end{verbatim}
 151
 152 which could also be written as:
 153
 154 \begin{verbatim}
 155 mpz mpzmodule.c -I$(GMP) -L$(GMP) -lgmp
 156 \end{verbatim}
 157
 158
 159 \section{Distributing your extension modules
 160      \label{distributing}}
 161
 162 There are two ways to distribute extension modules for others to use.
 163 The way that allows the easiest cross-platform support is to use the
 164 \module{distutils}\refstmodindex{distutils} package.  The manual
 165 \citetitle[../dist/dist.html]{Distributing Python Modules} contains
 166 information on this approach.  It is recommended that all new
 167 extensions be distributed using this approach to allow easy building
 168 and installation across platforms.  Older extensions should migrate to
 169 this approach as well.
 170
 171 What follows describes the older approach; there are still many
 172 extensions which use this.
 173
 174 When distributing your extension modules in source form, make sure to
 175 include a \file{Setup} file.  The \file{Setup} file should be named
 176 \file{Setup.in} in the distribution.  The make file make file,
 177 \file{Makefile.pre.in}, will copy \file{Setup.in} to \file{Setup} if
 178 the person installing the extension doesn't do so manually.
 179 Distributing a \file{Setup.in} file makes it easy for people to
 180 customize the \file{Setup} file while keeping the original in
 181 \file{Setup.in}.
 182
 183 It is a good idea to include a copy of \file{Makefile.pre.in} for
 184 people who do not have a source distribution of Python.
 185
 186 Do not distribute a make file.  People building your modules
 187 should use \file{Makefile.pre.in} to build their own make file.  A
 188 \file{README} file included in the package should provide simple
 189 instructions to perform the build.