+++ /dev/null
-\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.
projects / thirdparty / Python / cpython.git / commitdiff
