| \chapter{Building C and \Cpp{} Extensions on \UNIX{} |
| \label{building-on-unix}} |
| |
| \sectionauthor{Jim Fulton}{jim@zope.com} |
| |
| |
| %The make file make file, building C extensions on Unix |
| |
| |
| Starting in Python 1.4, Python provides a special make file for |
| building make files for building dynamically-linked extensions and |
| custom interpreters. The make file make file builds a make file |
| that reflects various system variables determined by configure when |
| the Python interpreter was built, so people building module's don't |
| have to resupply these settings. This vastly simplifies the process |
| of building extensions and custom interpreters on \UNIX{} systems. |
| |
| The make file make file is distributed as the file |
| \file{Misc/Makefile.pre.in} in the Python source distribution. The |
| first step in building extensions or custom interpreters is to copy |
| this make file to a development directory containing extension module |
| source. |
| |
| The make file make file, \file{Makefile.pre.in} uses metadata |
| provided in a file named \file{Setup}. The format of the \file{Setup} |
| file is the same as the \file{Setup} (or \file{Setup.dist}) file |
| provided in the \file{Modules/} directory of the Python source |
| distribution. The \file{Setup} file contains variable definitions: |
| |
| \begin{verbatim} |
| EC=/projects/ExtensionClass |
| \end{verbatim} |
| |
| and module description lines. It can also contain blank lines and |
| comment lines that start with \character{\#}. |
| |
| A module description line includes a module name, source files, |
| options, variable references, and other input files, such |
| as libraries or object files. Consider a simple example: |
| |
| \begin{verbatim} |
| ExtensionClass ExtensionClass.c |
| \end{verbatim} |
| |
| This is the simplest form of a module definition line. It defines a |
| module, \module{ExtensionClass}, which has a single source file, |
| \file{ExtensionClass.c}. |
| |
| This slightly more complex example uses an \strong{-I} option to |
| specify an include directory: |
| |
| \begin{verbatim} |
| EC=/projects/ExtensionClass |
| cPersistence cPersistence.c -I$(EC) |
| \end{verbatim} % $ <-- bow to font lock |
| |
| This example also illustrates the format for variable references. |
| |
| For systems that support dynamic linking, the \file{Setup} file should |
| begin: |
| |
| \begin{verbatim} |
| *shared* |
| \end{verbatim} |
| |
| to indicate that the modules defined in \file{Setup} are to be built |
| as dynamically linked modules. A line containing only \samp{*static*} |
| can be used to indicate the subsequently listed modules should be |
| statically linked. |
| |
| Here is a complete \file{Setup} file for building a |
| \module{cPersistent} module: |
| |
| \begin{verbatim} |
| # Set-up file to build the cPersistence module. |
| # Note that the text should begin in the first column. |
| *shared* |
| |
| # We need the path to the directory containing the ExtensionClass |
| # include file. |
| EC=/projects/ExtensionClass |
| cPersistence cPersistence.c -I$(EC) |
| \end{verbatim} % $ <-- bow to font lock |
| |
| After the \file{Setup} file has been created, \file{Makefile.pre.in} |
| is run with the \samp{boot} target to create a make file: |
| |
| \begin{verbatim} |
| make -f Makefile.pre.in boot |
| \end{verbatim} |
| |
| This creates the file, Makefile. To build the extensions, simply |
| run the created make file: |
| |
| \begin{verbatim} |
| make |
| \end{verbatim} |
| |
| It's not necessary to re-run \file{Makefile.pre.in} if the |
| \file{Setup} file is changed. The make file automatically rebuilds |
| itself if the \file{Setup} file changes. |
| |
| |
| \section{Building Custom Interpreters \label{custom-interps}} |
| |
| The make file built by \file{Makefile.pre.in} can be run with the |
| \samp{static} target to build an interpreter: |
| |
| \begin{verbatim} |
| make static |
| \end{verbatim} |
| |
| Any modules defined in the \file{Setup} file before the |
| \samp{*shared*} line will be statically linked into the interpreter. |
| Typically, a \samp{*shared*} line is omitted from the |
| \file{Setup} file when a custom interpreter is desired. |
| |
| |
| \section{Module Definition Options \label{module-defn-options}} |
| |
| Several compiler options are supported: |
| |
| \begin{tableii}{l|l}{programopt}{Option}{Meaning} |
| \lineii{-C}{Tell the C pre-processor not to discard comments} |
| \lineii{-D\var{name}=\var{value}}{Define a macro} |
| \lineii{-I\var{dir}}{Specify an include directory, \var{dir}} |
| \lineii{-L\var{dir}}{Specify a link-time library directory, \var{dir}} |
| \lineii{-R\var{dir}}{Specify a run-time library directory, \var{dir}} |
| \lineii{-l\var{lib}}{Link a library, \var{lib}} |
| \lineii{-U\var{name}}{Undefine a macro} |
| \end{tableii} |
| |
| Other compiler options can be included (snuck in) by putting them |
| in variables. |
| |
| Source files can include files with \file{.c}, \file{.C}, \file{.cc}, |
| \file{.cpp}, \file{.cxx}, and \file{.c++} extensions. |
| |
| Other input files include files with \file{.a}, \file{.o}, \file{.sl}, |
| and \file{.so} extensions. |
| |
| |
| \section{Example \label{module-defn-example}} |
| |
| Here is a more complicated example from \file{Modules/Setup.dist}: |
| |
| \begin{verbatim} |
| GMP=/ufs/guido/src/gmp |
| mpz mpzmodule.c -I$(GMP) $(GMP)/libgmp.a |
| \end{verbatim} |
| |
| which could also be written as: |
| |
| \begin{verbatim} |
| mpz mpzmodule.c -I$(GMP) -L$(GMP) -lgmp |
| \end{verbatim} |
| |
| |
| \section{Distributing your extension modules |
| \label{distributing}} |
| |
| There are two ways to distribute extension modules for others to use. |
| The way that allows the easiest cross-platform support is to use the |
| \module{distutils}\refstmodindex{distutils} package. The manual |
| \citetitle[../dist/dist.html]{Distributing Python Modules} contains |
| information on this approach. It is recommended that all new |
| extensions be distributed using this approach to allow easy building |
| and installation across platforms. Older extensions should migrate to |
| this approach as well. |
| |
| What follows describes the older approach; there are still many |
| extensions which use this. |
| |
| When distributing your extension modules in source form, make sure to |
| include a \file{Setup} file. The \file{Setup} file should be named |
| \file{Setup.in} in the distribution. The make file make file, |
| \file{Makefile.pre.in}, will copy \file{Setup.in} to \file{Setup} if |
| the person installing the extension doesn't do so manually. |
| Distributing a \file{Setup.in} file makes it easy for people to |
| customize the \file{Setup} file while keeping the original in |
| \file{Setup.in}. |
| |
| It is a good idea to include a copy of \file{Makefile.pre.in} for |
| people who do not have a source distribution of Python. |
| |
| Do not distribute a make file. People building your modules |
| should use \file{Makefile.pre.in} to build their own make file. A |
| \file{README} file included in the package should provide simple |
| instructions to perform the build. |