traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Move 'Tips and Tricks' to be the last section

This commit is contained in:
Andrew M. Kuchling 2002-05-07 21:03:45 +00:00
parent 3b98dc16e9
commit 1624bc051f
1 changed files with 227 additions and 227 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

454
Doc/inst/inst.tex
View File

@ -2,7 +2,6 @@
\usepackage{distutils}
% TODO:
% Move 'Tips and Tricks' to be the last section
% Fill in XXX comments
\title{Installing Python Modules}
@ -373,232 +372,6 @@ section~\ref{custom-install} on custom installations.
\end{tableiii}}
\section{Building Extensions: Tips and Tricks}
\label{building-ext}
Whenever possible, the Distutils try to use the configuration
information made available by the Python interpreter used to run the
\file{setup.py} script. For example, the same compiler and linker
flags used to compile Python will also be used for compiling
extensions. Usually this will work well, but in complicated
situations this might be inappropriate. This section discusses how to
override the usual Distutils behaviour.
\subsection{Tweaking compiler/linker flags}
\label{tweak-flags}
Compiling a Python extension written in C or \Cpp will sometimes
require specifying custom flags for the compiler and linker in order
to use a particular library or produce a special kind of object code.
This is especially true if the extension hasn't been tested on your
platform, or if you're trying to cross-compile Python.
In the most general case, the extension author might have foreseen
that compiling the extensions would be complicated, and provided a
\file{Setup} file for you to edit. This will likely only be done if
the module distribution contains many separate extension modules, or
if they often require elaborate sets of compiler flags in order to work.
A \file{Setup} file, if present, is parsed in order to get a list of
extensions to build. Each line in a \file{Setup} describes a single
module. Lines have the following structure:
\begin{verbatim}
<module> ... [<sourcefile> ...] [<cpparg> ...] [<library> ...]
\end{verbatim}
Let's examine each of the fields in turn.
\begin{itemize}
\item \var{module} is the name of the extension module to be built,
and should be a valid Python identifier. You can't just change this
in order to rename a module (edits to the source code would also be
needed), so this should be left alone.
\item \var{sourcefile} is anything that's likely to be a source code
file, at least judging by the filename. Filenames ending in .c are
assumed to be written in C, filenames ending in .C, .cc, .c++ are
assumed to be \Cpp, and filenames ending in .m or .mm are assumed to
be in Objective C.
\item \var{cpparg} is an argument for the C preprocessor,
and is anything starting with -I, -D, -U or -C .
\item <library> is anything ending in .a or beginning with -l or -L.
\end{itemize}
If a particular platform requires a special library on your platform,
you can add it by editing the \file{Setup} file and running
\code{python setup.py build}. For example, if the module defined by the line
\begin{verbatim}
foo foomodule.c
\end{verbatim}
must be linked with the math library \file{libm.a} on your platform,
simply add \samp{-lm} to the line:
\begin{verbatim}
foo foomodule.c -lm
\end{verbatim}
Arbitrary switches intended for the compiler or the linker can be
supplied with the \code{-Xcompiler \var{arg}} and \code{-Xlinker
\var{arg}} options:
\begin{verbatim}
foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
\end{verbatim}
The next option after \code{-Xcompiler} and \code{-Xlinker} will be
appended to the proper command line, so in the above example the
compiler will be passed the \samp{-o32} option, and the linker will be
passed \samp{-shared}. If a compiler option requires an argument,
you'll have to supply multiple \code{-Xcompiler} options; for example,
to pass \code{-x c++} the \file{Setup} file would have to contain
\code{-Xcompiler -x -Xcompiler c++}.
Compiler flags can also be supplied through setting the
\envvar{CFLAGS} environment variable. If set, the contents of
\envvar{CFLAGS} will be added to the compiler flags specified in the
\file{Setup} file.
\subsection{Using non-Microsoft compilers on Windows \label{non-ms-compilers}}
\sectionauthor{Rene Liebscher}{R.Liebscher@gmx.de}
\subsubsection{Borland C++}
This subsection describes the necessary steps to use Distutils with the
Borland \Cpp{} compiler version 5.5.
%Should we mention that users have to create cfg-files for the compiler?
%see also http://community.borland.com/article/0,1410,21205,00.html
First you have to know that Borland's object file format (OMF) is
different from the format used by the Python version you can download
from the Python or ActiveState Web site. (Python is built with
Microsoft Visual \Cpp, which uses COFF as the object file format.)
For this reason you have to convert Python's library
\file{python20.lib} into the Borland format. You can do this as
follows:
\begin{verbatim}
coff2omf python20.lib python20_bcpp.lib
\end{verbatim}
The \file{coff2omf} program comes with the Borland compiler. The file
\file{python20.lib} is in the \file{Libs} directory of your Python
installation. If your extension uses other libraries (zlib,...) you
have to convert them too.
The converted files have to reside in the same directories as the
normal libraries.
How does Distutils manage to use these libraries with their changed
names? If the extension needs a library (eg. \file{foo}) Distutils
checks first if it finds a library with suffix \file{_bcpp}
(eg. \file{foo_bcpp.lib}) and then uses this library. In the case it
doesn't find such a special library it uses the default name
(\file{foo.lib}.)\footnote{This also means you could replace all
existing COFF-libraries with OMF-libraries of the same name.}
To let Distutils compile your extension with Borland \Cpp{} you now have
to type:
\begin{verbatim}
python setup.py build --compiler=bcpp
\end{verbatim}
If you want to use the Borland \Cpp{} compiler as the default, you
could specify this in your personal or system-wide configuration file
for Distutils (see section~\ref{config-files}.)
\begin{seealso}
\seetitle[http://www.borland.com/bcppbuilder/freecompiler/]
{\Cpp{}Builder Compiler}
{Information about the free \Cpp{} compiler from Borland,
including links to the download pages.}
\seetitle[http://www.cyberus.ca/~g_will/pyExtenDL.shtml]
{Creating Python Extensions Using Borland's Free Compiler}
{Document describing how to use Borland's free command-line C++
compiler to build Python.}
\end{seealso}
\subsubsection{GNU C / Cygwin / MinGW32}
This section describes the necessary steps to use Distutils with the
GNU C/\Cpp{} compilers in their Cygwin and MinGW32
distributions.\footnote{Check
\url{http://sources.redhat.com/cygwin/} and
\url{http://www.mingw.org/} for more information}
\XXX{For a Python which was built with Cygwin, all should work without
any of these following steps.}
These compilers also require some special libraries.
This task is more complex than for Borland's \Cpp, because there is no
program to convert the library.
% I don't understand what the next line means. --amk
% (inclusive the references on data structures.)
First you have to create a list of symbols which the Python DLL exports.
(You can find a good program for this task at
\url{http://starship.python.net/crew/kernr/mingw32/Notes.html}, see at
PExports 0.42h there.)
\begin{verbatim}
pexports python20.dll >python20.def
\end{verbatim}
Then you can create from these information an import library for gcc.
\begin{verbatim}
dlltool --dllname python20.dll --def python20.def --output-lib libpython20.a
\end{verbatim}
The resulting library has to be placed in the same directory as
\file{python20.lib}. (Should be the \file{libs} directory under your
Python installation directory.)
If your extension uses other libraries (zlib,...) you might
have to convert them too.
The converted files have to reside in the same directories as the normal
libraries do.
To let Distutils compile your extension with Cygwin you now have to type
\begin{verbatim}
python setup.py build --compiler=cygwin
\end{verbatim}
and for Cygwin in no-cygwin mode\footnote{Then you have no
\POSIX{} emulation available, but you also don't need
\file{cygwin1.dll}.} or for MinGW32 type:
\begin{verbatim}
python setup.py build --compiler=mingw32
\end{verbatim}
If you want to use any of these options/compilers as default, you should
consider to write it in your personal or system-wide configuration file
for Distutils (see section~\ref{config-files}.)
\begin{seealso}
\seetitle[http://www.zope.org/Members/als/tips/win32_mingw_modules]
{Building Python modules on MS Windows platform with MinGW32}
{Information about building the required libraries for the MinGW32
environment.}
\seeurl{http://pyopengl.sourceforge.net/ftp/win32-stuff/}
{Converted import libraries in Cygwin/MinGW32 and Borland format,
and a script to create the registry entries needed for Distutils
to locate the built Python.}
\end{seealso}
\section{Alternate Installation}
\label{alt-install}
@ -1059,4 +832,231 @@ python setup.py --help
See also the ``Reference'' section of the ``Distributing Python
Modules'' manual.
\section{Building Extensions: Tips and Tricks}
\label{building-ext}
Whenever possible, the Distutils try to use the configuration
information made available by the Python interpreter used to run the
\file{setup.py} script. For example, the same compiler and linker
flags used to compile Python will also be used for compiling
extensions. Usually this will work well, but in complicated
situations this might be inappropriate. This section discusses how to
override the usual Distutils behaviour.
\subsection{Tweaking compiler/linker flags}
\label{tweak-flags}
Compiling a Python extension written in C or \Cpp will sometimes
require specifying custom flags for the compiler and linker in order
to use a particular library or produce a special kind of object code.
This is especially true if the extension hasn't been tested on your
platform, or if you're trying to cross-compile Python.
In the most general case, the extension author might have foreseen
that compiling the extensions would be complicated, and provided a
\file{Setup} file for you to edit. This will likely only be done if
the module distribution contains many separate extension modules, or
if they often require elaborate sets of compiler flags in order to work.
A \file{Setup} file, if present, is parsed in order to get a list of
extensions to build. Each line in a \file{Setup} describes a single
module. Lines have the following structure:
\begin{verbatim}
<module> ... [<sourcefile> ...] [<cpparg> ...] [<library> ...]
\end{verbatim}
Let's examine each of the fields in turn.
\begin{itemize}
\item \var{module} is the name of the extension module to be built,
and should be a valid Python identifier. You can't just change this
in order to rename a module (edits to the source code would also be
needed), so this should be left alone.
\item \var{sourcefile} is anything that's likely to be a source code
file, at least judging by the filename. Filenames ending in .c are
assumed to be written in C, filenames ending in .C, .cc, .c++ are
assumed to be \Cpp, and filenames ending in .m or .mm are assumed to
be in Objective C.
\item \var{cpparg} is an argument for the C preprocessor,
and is anything starting with -I, -D, -U or -C .
\item <library> is anything ending in .a or beginning with -l or -L.
\end{itemize}
If a particular platform requires a special library on your platform,
you can add it by editing the \file{Setup} file and running
\code{python setup.py build}. For example, if the module defined by the line
\begin{verbatim}
foo foomodule.c
\end{verbatim}
must be linked with the math library \file{libm.a} on your platform,
simply add \samp{-lm} to the line:
\begin{verbatim}
foo foomodule.c -lm
\end{verbatim}
Arbitrary switches intended for the compiler or the linker can be
supplied with the \code{-Xcompiler \var{arg}} and \code{-Xlinker
\var{arg}} options:
\begin{verbatim}
foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
\end{verbatim}
The next option after \code{-Xcompiler} and \code{-Xlinker} will be
appended to the proper command line, so in the above example the
compiler will be passed the \samp{-o32} option, and the linker will be
passed \samp{-shared}. If a compiler option requires an argument,
you'll have to supply multiple \code{-Xcompiler} options; for example,
to pass \code{-x c++} the \file{Setup} file would have to contain
\code{-Xcompiler -x -Xcompiler c++}.
Compiler flags can also be supplied through setting the
\envvar{CFLAGS} environment variable. If set, the contents of
\envvar{CFLAGS} will be added to the compiler flags specified in the
\file{Setup} file.
\subsection{Using non-Microsoft compilers on Windows \label{non-ms-compilers}}
\sectionauthor{Rene Liebscher}{R.Liebscher@gmx.de}
\subsubsection{Borland C++}
This subsection describes the necessary steps to use Distutils with the
Borland \Cpp{} compiler version 5.5.
%Should we mention that users have to create cfg-files for the compiler?
%see also http://community.borland.com/article/0,1410,21205,00.html
First you have to know that Borland's object file format (OMF) is
different from the format used by the Python version you can download
from the Python or ActiveState Web site. (Python is built with
Microsoft Visual \Cpp, which uses COFF as the object file format.)
For this reason you have to convert Python's library
\file{python20.lib} into the Borland format. You can do this as
follows:
\begin{verbatim}
coff2omf python20.lib python20_bcpp.lib
\end{verbatim}
The \file{coff2omf} program comes with the Borland compiler. The file
\file{python20.lib} is in the \file{Libs} directory of your Python
installation. If your extension uses other libraries (zlib,...) you
have to convert them too.
The converted files have to reside in the same directories as the
normal libraries.
How does Distutils manage to use these libraries with their changed
names? If the extension needs a library (eg. \file{foo}) Distutils
checks first if it finds a library with suffix \file{_bcpp}
(eg. \file{foo_bcpp.lib}) and then uses this library. In the case it
doesn't find such a special library it uses the default name
(\file{foo.lib}.)\footnote{This also means you could replace all
existing COFF-libraries with OMF-libraries of the same name.}
To let Distutils compile your extension with Borland \Cpp{} you now have
to type:
\begin{verbatim}
python setup.py build --compiler=bcpp
\end{verbatim}
If you want to use the Borland \Cpp{} compiler as the default, you
could specify this in your personal or system-wide configuration file
for Distutils (see section~\ref{config-files}.)
\begin{seealso}
\seetitle[http://www.borland.com/bcppbuilder/freecompiler/]
{\Cpp{}Builder Compiler}
{Information about the free \Cpp{} compiler from Borland,
including links to the download pages.}
\seetitle[http://www.cyberus.ca/~g_will/pyExtenDL.shtml]
{Creating Python Extensions Using Borland's Free Compiler}
{Document describing how to use Borland's free command-line C++
compiler to build Python.}
\end{seealso}
\subsubsection{GNU C / Cygwin / MinGW32}
This section describes the necessary steps to use Distutils with the
GNU C/\Cpp{} compilers in their Cygwin and MinGW32
distributions.\footnote{Check
\url{http://sources.redhat.com/cygwin/} and
\url{http://www.mingw.org/} for more information}
\XXX{For a Python which was built with Cygwin, all should work without
any of these following steps.}
These compilers also require some special libraries.
This task is more complex than for Borland's \Cpp, because there is no
program to convert the library.
% I don't understand what the next line means. --amk
% (inclusive the references on data structures.)
First you have to create a list of symbols which the Python DLL exports.
(You can find a good program for this task at
\url{http://starship.python.net/crew/kernr/mingw32/Notes.html}, see at
PExports 0.42h there.)
\begin{verbatim}
pexports python20.dll >python20.def
\end{verbatim}
Then you can create from these information an import library for gcc.
\begin{verbatim}
dlltool --dllname python20.dll --def python20.def --output-lib libpython20.a
\end{verbatim}
The resulting library has to be placed in the same directory as
\file{python20.lib}. (Should be the \file{libs} directory under your
Python installation directory.)
If your extension uses other libraries (zlib,...) you might
have to convert them too.
The converted files have to reside in the same directories as the normal
libraries do.
To let Distutils compile your extension with Cygwin you now have to type
\begin{verbatim}
python setup.py build --compiler=cygwin
\end{verbatim}
and for Cygwin in no-cygwin mode\footnote{Then you have no
\POSIX{} emulation available, but you also don't need
\file{cygwin1.dll}.} or for MinGW32 type:
\begin{verbatim}
python setup.py build --compiler=mingw32
\end{verbatim}
If you want to use any of these options/compilers as default, you should
consider to write it in your personal or system-wide configuration file
for Distutils (see section~\ref{config-files}.)
\begin{seealso}
\seetitle[http://www.zope.org/Members/als/tips/win32_mingw_modules]
{Building Python modules on MS Windows platform with MinGW32}
{Information about building the required libraries for the MinGW32
environment.}
\seeurl{http://pyopengl.sourceforge.net/ftp/win32-stuff/}
{Converted import libraries in Cygwin/MinGW32 and Borland format,
and a script to create the registry entries needed for Distutils
to locate the built Python.}
\end{seealso}
\end{document}