diff options
| -rw-r--r-- | Doc/ext/building.tex | 143 | ||||
| -rw-r--r-- | Doc/ext/ext.tex | 2 | ||||
| -rw-r--r-- | Doc/ext/unix.tex | 189 | ||||
| -rw-r--r-- | Doc/ext/windows.tex | 4 |
4 files changed, 148 insertions, 190 deletions
diff --git a/Doc/ext/building.tex b/Doc/ext/building.tex new file mode 100644 index 0000000..9eadca3 --- /dev/null +++ b/Doc/ext/building.tex @@ -0,0 +1,143 @@ +\chapter{Building C and \Cpp{} Extensions with distutils + \label{building}} + +\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de} + +Starting in Python 1.4, Python provides, on \UNIX{}, a special make +file for building make files for building dynamically-linked +extensions and custom interpreters. Starting with Python 2.0, this +mechanism (known as related to Makefile.pre.in, and Setup files) is no +longer supported. Building custom interpreters was rarely used, and +extensions modules can be build using distutils. + +Building an extension module using distutils requires that distutils +is installed on the build machine, which is included in Python 2.x and +available separately for Python 1.5. Since distutils also supports +creation of binary packages, users don't necessarily need a compiler +and distutils to install the extension. + +A distutils package contains a driver script, \file{setup.py}. This is +a plain Python file, which, in the most simple case, could look like +this: + +\begin{verbatim} +from distutils.core import setup, Extension + +module1 = Extension('demo', + sources = ['demo.c']) + +setup (name = 'PackageName', + version = '1.0', + description = 'This is a demo package', + ext_modules = [module1]) + +\end{verbatim} + +With this \file{setup.py}, and a file \file{demo.c}, running + +\begin{verbatim} +python setup.py build +\end{verbatim} + +will compile \file{demo.c}, and produce an extension module named +\samp{demo} in the \file{build} directory. Depending on the system, +the module file will end up in a subdirectory \file{build/lib.system}, +and may have a name like \file{demo.so} or \file{demo.pyd}. + +In the \file{setup.py}, all execution is performed by calling the +\samp{setup} function. This takes a variable number of keyword +arguments, of which the example above uses only a +subset. Specifically, the example specifies meta-information to build +packages, and it specifies the contents of the package. Normally, a +package will contain of addition modules, like Python source modules, +documentation, subpackages, etc. Please refer to the distutils +documentation in \citetitle[../dist/dist.html]{Distributing Python +Modules} to learn more about the features of distutils; this section +explains building extension modules only. + +It is common to pre-compute arguments to \function{setup}, to better +structure the driver script. In the example above, +the\samp{ext_modules} argument to \function{setup} is a list of +extension modules, each of which is an instance of the +\class{Extension}. In the example, the instance defines an extension +named \samp{demo} which is build by compiling a single source file, +\file{demo.c}. + +In many cases, building an extension is more complex, since additional +preprocessor defines and libraries may be needed. This is demonstrated +in the example below. + +\begin{verbatim} +from distutils.core import setup, Extension + +module1 = Extension('demo', + define_macros = [('MAJOR_VERSION', '1'), + ('MINOR_VERSION', '0')], + include_dirs = ['/usr/local/include'], + libraries = ['tcl83'], + library_dirs = ['/usr/local/lib'], + sources = ['demo.c']) + +setup (name = 'PackageName', + version = '1.0', + description = 'This is a demo package', + author = 'Martin v. Loewis', + author_email = 'martin@v.loewis.de', + url = 'http://www.python.org/doc/current/ext/building.html', + long_description = ''' +This is really just a demo package. +''', + ext_modules = [module1]) + +\end{verbatim} + +In this example, \function{setup} is called with additional +meta-information, which is recommended when distribution packages have +to be built. For the extension itself, it specifies preprocessor +defines, include directories, library directories, and libraries. +Depending on the compiler, distutils passes this information in +different ways to the compiler. For example, on \UNIX{}, this may +result in the compilation commands + +\begin{verbatim} +gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o + +gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so +\end{verbatim} + +These lines are for demonstration purposes only; distutils users +should trust that distutils gets the invocations right. + +\section{Distributing your extension modules + \label{distributing}} + +When an extension has been successfully build, there are three ways to +use it. + +End-users will typically want to install the module, they do so by +running + +\begin{verbatim} +python setup.py install +\end{verbatim} + +Module maintainers should produce source packages; to do so, they run + +\begin{verbatim} +python setup.py sdist +\end{verbatim} + +In some cases, additional files need to be included in a source +distribution; this is done through a \file{MANIFEST.in} file; see the +distutils documentation for details. + +If the source distribution has been build successfully, maintainers +can also create binary distributions. Depending on the platform, one +of the following commands can be used to do so. + +\begin{verbatim} +python setup.py bdist_wininst +python setup.py bdist_rpm +python setup.py bdist_dumb +\end{verbatim} + diff --git a/Doc/ext/ext.tex b/Doc/ext/ext.tex index 9ad6523..b4130d1 100644 --- a/Doc/ext/ext.tex +++ b/Doc/ext/ext.tex @@ -52,7 +52,7 @@ For a detailed description of the whole Python/C API, see the separate \input{extending} \input{newtypes} -\input{unix} +\input{building} \input{windows} \input{embedding} diff --git a/Doc/ext/unix.tex b/Doc/ext/unix.tex deleted file mode 100644 index 396909e..0000000 --- a/Doc/ext/unix.tex +++ /dev/null @@ -1,189 +0,0 @@ -\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. diff --git a/Doc/ext/windows.tex b/Doc/ext/windows.tex index 9623eab..caac646 100644 --- a/Doc/ext/windows.tex +++ b/Doc/ext/windows.tex @@ -9,6 +9,10 @@ material is useful for both the Windows programmer learning to build Python extensions and the \UNIX{} programmer interested in producing software which can be successfully built on both \UNIX{} and Windows. +Module authors are encouraged to use the distutils approach for +building extension modules, instead of the one described in this +section. You will still need the C compiler that was used to build +Python; typically Microsoft Visual \Cpp. \section{A Cookbook Approach \label{win-cookbook}} |