diff options
| -rw-r--r-- | Doc/inst/inst.tex | 454 |
1 files changed, 227 insertions, 227 deletions
diff --git a/Doc/inst/inst.tex b/Doc/inst/inst.tex index 9b02316..63f5111 100644 --- a/Doc/inst/inst.tex +++ b/Doc/inst/inst.tex @@ -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} |