Doc/ext/unix.tex

\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.