From 2afffd42fa09b0560d0585029979a79e8bf85192 Mon Sep 17 00:00:00 2001 From: Greg Ward Date: Sun, 6 Aug 2000 20:37:24 +0000 Subject: [PATCH] Wrote the "Describing extension modules" section. --- Doc/dist/dist.tex | 197 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 193 insertions(+), 4 deletions(-) diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex index e7d9f449eb7..02cce0e4317 100644 --- a/Doc/dist/dist.tex +++ b/Doc/dist/dist.tex @@ -274,8 +274,8 @@ mind that the \emph{absence} of a leading slash indicates a relative path, the opposite of the Mac OS convention with colons). -\subsection{Package directories} -\label{package-dirs} +\subsection{Listing whole packages} +\label{listing-packages} The \option{packages} option tells the Distutils to process (build, distribute, install, etc.) all pure Python modules found in each package @@ -340,13 +340,202 @@ This describes two modules, one of them in the ``root'' package, the other in the \module{pkg} package. Again, the default package/directory layout implies that these two modules can be found in \file{mod1.py} and \file{pkg/mod2.py}, and that \file{pkg/\_\_init\_\_.py} exists as well. -And again, you can override the package/directory layout using the -\option{package\_dir} option. +And again, you can override the package/directory correspondence using +the \option{package\_dir} option. \subsection{Describing extension modules} \label{sec:describing-extensions} +Just as writing Python extension modules is a bit more complicated than +writing pure Python modules, describing them to the Distutils is a bit +more complicated. Unlike pure modules, it's not enough just to list +modules or packages and expect the Distutils to go out and find the +right files; you have to specify the extension name, source file(s), and +any compile/link requirements (include directories, libraries to link +with, etc.). + +All of this is done through another keyword argument to +\function{setup()}, the \option{extensions} option. \option{extensions} +is just a list of \class{Extension} instances, each of which describes a +single extension module. Suppose your distribution includes a single +extension, called \module{foo} and implemented by \file{foo.c}. If no +additional instructions to the compiler/linker are needed, describing +this extension is quite simple: +\begin{verbatim} +Extension("foo", ["foo.c"]) +\end{verbatim} +The \class{Extension} class can be imported from +\module{distutils.core}, along with \function{setup()}. Thus, the setup +script for a module distribution that contains only this one extension +and nothing else might be: +\begin{verbatim} +from distutils.core import setup, Extension +setup(name = "foo", version = "1.0", + extensions = [Extension("foo", ["foo.c"])]) +\end{verbatim} + +The \class{Extension} class (actually, the underlying extension-building +machinery implemented by the \command{built\_ext} command) supports a +great deal of flexibility in describing Python extensions, which is +explained in the following sections. + + +\subsubsection{Extension names and packages} + +The first argument to the \class{Extension} constructor is always the +name of the extension, including any package names. For example, +\begin{verbatim} +Extension("foo", ["src/foo1.c", "src/foo2.c"]) +\end{verbatim} +describes an extension that lives in the root package, while +\begin{verbatim} +Extension("pkg.foo", ["src/foo1.c", "src/foo2.c"]) +\end{verbatim} +describes the same extension in the \module{pkg} package. The source +files and resulting object code are identical in both cases; the only +difference is where in the filesystem (and therefore where in Python's +namespace hierarchy) the resulting extension lives. + +If you have a number of extensions all in the same package (or all under +the same base package), use the \option{ext\_package} keyword argument +to \function{setup()}. For example, +\begin{verbatim} +setup(... + ext_package = "pkg", + extensions = [Extension("foo", ["foo.c"]), + Extension("subpkg.bar", ["bar.c"])] + ) +\end{verbatim} +will compile \file{foo.c} to the extension \module{pkg.foo}, and +\file{bar.c} to \module{pkg.subpkg.bar}. + + +\subsubsection{Extension source files} + +The second argument to the \class{Extension} constructor is a list of +source files. Since the Distutils currently only support C/C++ +extensions, these are normally C/C++ source files. (Be sure to use +appropriate extensions to distinguish C++ source files: \file{.cc} and +\file{.cpp} seem to be recognized by both Unix and Windows compilers.) + +However, you can also include SWIG interface (\file{.i}) files in the +list; the \command{build\_ext} command knows how to deal with SWIG +extensions: it will run SWIG on the interface file and compile the +resulting C/C++ file into your extension. + +\XXX{SWIG support is rough around the edges and largely untested; + especially SWIG support of C++ extensions! Explain in more detail + here when the interface firms up.} + +On some platforms, you can include non-source files that are processed +by the compiler and included in your extension. Currently, this just +means Windows resource files for Visual C++. \XXX{get more detail on + this feature from Thomas Heller!} + + +\subsubsection{Preprocessor options} + +Three optional arguments to \class{Extension} will help if you need to +specify include directories to search or preprocessor macros to +define/undefine: \code{include\_dirs}, \code{define\_macros}, and +\code{undef\_macros}. + +For example, if your extension requires header files in the +\file{include} directory under your distribution root, use the +\code{include\_dirs} option: +\begin{verbatim} +Extension("foo", ["foo.c"], include_dirs=["include"]) +\end{verbatim} + +You can specify absolute directories there; if you know that your +extension will only be built on Unix systems with X11R6 installed to +\file{/usr}, you can get away with +\begin{verbatim} +Extension("foo", ["foo.c"], include_dirs=["/usr/include/X11"]) +\end{verbatim} +You should avoid this sort of non-portable usage if you plan to +distribute your code: it's probably better to write your code to include +(e.g.) \code{}. + +If you need to include header files from some other Python extension, +you can take advantage of the fact that the Distutils install extension +header files in a consistent way. For example, the Numerical Python +header files are installed (on a standard Unix installation) to +\file{/usr/local/include/python1.5/Numerical}. (The exact location will +differ according to your platform and Python installation.) Since the +Python include directory---\file{/usr/local/include/python1.5} in this +case---is always included in the search path when building Python +extensions, the best approach is to include (e.g.) +\code{}. If you insist on putting the +\file{Numerical} include directory right into your header search path, +though, you can find that directory using the Distutils +\module{sysconfig} module: +\begin{verbatim} +from distutils.sysconfig import get_python_inc +incdir = os.path.join(get_python_inc(plat_specific=1), "Numerical") +setup(..., + Extension(..., include_dirs=[incdir])) +\end{verbatim} +Even though this is quite portable---it will work on any Python +installation, regardless of platform---it's probably easier to just +write your C code in the sensible way. + +You can define and undefine pre-processor macros with the +\code{define\_macros} and \code{undef\_macros} options. +\code{define\_macros} takes a list of \code{(name, value)} tuples, where +\code{name} is the name of the macro to define (a string) and +\code{value} is its value: either a string or \code{None}. (Defining a +macro \code{FOO} to \code{None} is the equivalent of a bare +\code{\#define FOO} in your C source: with most compilers, this sets +\code{FOO} to the string \code{1}.) \code{undef\_macros} is just +a list of macros to undefine. + +For example: +\begin{verbatim} +Extension(..., + define_macros=[('NDEBUG', '1')], + ('HAVE_STRFTIME', None), + undef_macros=['HAVE_FOO', 'HAVE_BAR']) +\end{verbatim} +is the equivalent of having this at the top of every C source file: +\begin{verbatim} +#define NDEBUG 1 +#define HAVE_STRFTIME +#undef HAVE_FOO +#undef HAVE_BAR +\end{verbatim} + + +\subsubsection{Library options} + +You can also specify the libraries to link against when building your +extension, and the directories to search for those libraries. The +\code{libraries} option is a list of libraries to link against, +\code{library\_dirs} is a list of directories to search for libraries at +link-time, and \code{runtime\_library\_dirs} is a list of directories to +search for shared (dynamically loaded) libraries at run-time. + +For example, if you need to link against libraries known to be in the +standard library search path on target systems +\begin{verbatim} +Extension(..., + libraries=["gdbm", "readline"]) +\end{verbatim} + +If you need to link with libraries in a non-standard location, you'll +have to include the location in \code{library\_dirs}: +\begin{verbatim} +Extension(..., + library_dirs=["/usr/X11R6/lib"], + libraries=["X11", "Xt"]) +\end{verbatim} +(Again, this sort of non-portable construct should be avoided if you +intend to distribute your code.) + +\XXX{still undocumented: extra\_objects, extra\_compile\_args, + extra\_link\_args, export\_symbols---none of which are frequently + needed, some of which might be completely unnecessary!} \section{Writing the Setup Configuration File}