Split "Extending & Embedding" into separate files, one per chapter.

Doc/ext/unix.tex

@@ -0,0 +1,189 @@
+\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.