[Distutils] Documentation
Thomas Heller
thomas.heller@ion-tof.com
Mon Feb 19 08:16:01 2001
Here is what I've hacked together over some spare time
at the weekend. I would appreciate feedback, as I've told
before I'm neither a great author, nor native english speaker,
nor anything else.
Mostly I've completed (and written) docs for bdist_wininst
(where I'm an expertert for), also I've started some stuff
for the data_files and scripts option.
Should I continue in this way? Would others like to jump in?
Thomas
Index: dist.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/dist/dist.tex,v
retrieving revision 1.29
diff -c -r1.29 dist.tex
*** dist.tex 2000/11/22 16:06:16 1.29
--- dist.tex 2001/02/19 13:07:06
***************
*** 53,59 ****
Using the Distutils is quite simple, both for module developers and for
users/administrators installing third-party modules. As a developer,
! your responsibilites (apart from writing solid, well-documented and
well-tested code, of course!) are:
\begin{itemize}
\item write a setup script (\file{setup.py} by convention)
--- 53,59 ----
Using the Distutils is quite simple, both for module developers and for
users/administrators installing third-party modules. As a developer,
! your responsibilities (apart from writing solid, well-documented and
well-tested code, of course!) are:
\begin{itemize}
\item write a setup script (\file{setup.py} by convention)
***************
*** 148,166 ****
will create an executable installer, \file{Foo-1.0.win32.exe}, in the
current directory.
! \XXX{not implemented yet}
! (Another way to create executable installers for Windows is with the
! \command{bdist\_wise} command, which uses Wise---the commercial
! installer-generator used to create Python's own installer---to create
! the installer. Wise-based installers are more appropriate for large,
! industrial-strength applications that need the full capabilities of a
! ``real'' installer. \command{bdist\_wininst} creates a self-extracting
! zip file with a minimal user interface, which is enough for small- to
! medium-sized module collections. You'll need to have version XXX of
! Wise installed on your system for the \command{bdist\_wise} command to
! work; it's available from \url{http://foo/bar/baz}.)
!
! Currently (Distutils 0.9.2), the are only other useful built
distribution format is RPM, implemented by the \command{bdist\_rpm}
command. For example, the following command will create an RPM file
called \file{Foo-1.0.noarch.rpm}:
--- 148,154 ----
will create an executable installer, \file{Foo-1.0.win32.exe}, in the
current directory.
! Currently (Distutils 0.9.2), the only other useful built
distribution format is RPM, implemented by the \command{bdist\_rpm}
command. For example, the following command will create an RPM file
called \file{Foo-1.0.noarch.rpm}:
***************
*** 192,198 ****
single \file{.py} file (and possibly associated \file{.pyc} and/or
\file{.pyo} files). Sometimes referred to as a ``pure module.''
\item[extension module] a module written in the low-level language of
! the Python implemention: C/C++ for Python, Java for JPython.
Typically contained in a single dynamically loadable pre-compiled
file, e.g. a shared object (\file{.so}) file for Python extensions on
\UNIX, a DLL (given the \file{.pyd} extension) for Python extensions
--- 180,186 ----
single \file{.py} file (and possibly associated \file{.pyc} and/or
\file{.pyo} files). Sometimes referred to as a ``pure module.''
\item[extension module] a module written in the low-level language of
! the Python implementation: C/C++ for Python, Java for JPython.
Typically contained in a single dynamically loadable pre-compiled
file, e.g. a shared object (\file{.so}) file for Python extensions on
\UNIX, a DLL (given the \file{.pyd} extension) for Python extensions
***************
*** 240,246 ****
\section{Writing the Setup Script}
\label{setup-script}
! The setup script is the centre of all activity in building,
distributing, and installing modules using the Distutils. The main
purpose of the setup script is to describe your module distribution to
the Distutils, so that the various commands that operate on your modules
--- 228,234 ----
\section{Writing the Setup Script}
\label{setup-script}
! The setup script is the center of all activity in building,
distributing, and installing modules using the Distutils. The main
purpose of the setup script is to describe your module distribution to
the Distutils, so that the various commands that operate on your modules
***************
*** 290,295 ****
--- 278,291 ----
mind that the \emph{absence} of a leading slash indicates a relative
path, the opposite of the MacOS convention with colons).
+ This, of course, only applies to pathnames given to Distutils functions.
+ If you, for example, use standard python functions such as glob.glob
+ or os.listdir to specify files, you should be careful to write portable
+ code instead of hardcoding path separators:
+ \begin{verbatim}
+ glob.glob(os.path.join('mydir', 'subdir', '*.html'))
+ os.listdir(os.path.join('mydir', 'subdir'))
+ \end{verbatim}
\subsection{Listing whole packages}
\label{listing-packages}
***************
*** 447,454 ****
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}
--- 443,451 ----
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 message text (\file{.mc}) files and resource definition
! (\file{.rc}) files for Visual C++. These will be compiled to binary resource
! (\file{.res}) files and linked into the executable.
\subsubsection{Preprocessor options}
***************
*** 549,560 ****
\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}
\label{setup-config}
--- 546,611 ----
\end{verbatim}
(Again, this sort of non-portable construct should be avoided if you
intend to distribute your code.)
+
+ \XXX{THe Should mention clib libraries here or somewhere else!}
+
+ \subsubsection{Other options}
+
+ There are still some other options which can be used to handle special
+ cases.
+
+ The \option{extra\_objects} option is a list of object files to be passed
+ to the linker. These files must not have extensions, the default extension
+ for the compiler is used.
! \option{extra\_compile\_args} and \option{extra\_link\_args} can be used
! to specify additional command line options for the compiler resp.
! the linker command line.
+ \option{export\_symbols} is only useful on windows, it can contain a list
+ of symbols (funtions or variables) to be exported. This option
+ is not needed when building compiled extensions: the \code{initmodule}
+ function will automatically be added to the exported symbols list
+ by Distutils.
+ \subsection{Listing scripts}
+ So far we have been dealing with pure and non-pure Python modules,
+ which are usually not run by themselves but imported by scripts.
+
+ Scripts are files containing Python source code, indended to be started
+ from the command line.
+ Distutils doesn't provide much functionality for the scripts: the only
+ support Distutils gives is to adjust the first line of the script
+ if it starts with \code{#!} and contains the word ``python'' to refer
+ to the current interpreter location.
+
+ The \option{scripts} option simply is a list of files to be handled
+ in this way.
+
+
+ \subsection{Listing additional files}
+ The \option{data\_files} option can be used to specify additional
+ files needed by the module distribution: configuration files,
+ data files, anything which does not fit in the previous categories.
+
+ \option{data\_files} specify a sequence of \code{(directory, files)}
+ pairs in the following way:
+ \begin{verbatim}
+ setup(...
+ data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
+ ('config', ['cfg/data.cfg'])])
+ \end{verbatim}
+
+ Note that you can specify the directory names where the data files
+ will be installed, but you cannot rename the data files themselves.
+
+ You can specify the \option{data\_files} options as a simple sequence
+ of files without specifying a target directory, but this is not recommended,
+ and the \command{install} command will print a warning in this case.
+ To install data files directly in the target directory, an empty
+ string should be given as the directory.
+
+
\section{Writing the Setup Configuration File}
\label{setup-config}
***************
*** 948,955 ****
\lineiii{zip}{zip file (\file{.zip})}{(4)}
\lineiii{rpm}{RPM}{(5)}
\lineiii{srpm}{source RPM}{(5) \XXX{to do!}}
! \lineiii{wininst}{self-extracting ZIP file for Windows}{(2),(6)}
! %\lineiii{wise}{Wise installer for Windows}{(3)}
\end{tableiii}
\noindent Notes:
--- 999,1005 ----
\lineiii{zip}{zip file (\file{.zip})}{(4)}
\lineiii{rpm}{RPM}{(5)}
\lineiii{srpm}{source RPM}{(5) \XXX{to do!}}
! \lineiii{wininst}{self-extracting ZIP file for Windows}{(2),(4)}
\end{tableiii}
\noindent Notes:
***************
*** 962,969 ****
\module{zipfile} module (not part of the standard Python library)
\item[(5)] requires external \program{rpm} utility, version 3.0.4 or
better (use \code{rpm --version} to find out which version you have)
- \item[(6)] \XXX{requirements for \command{bdist\_wininst}?}
- %\item[(3)] not implemented yet
\end{description}
You don't have to use the \command{bdist} command with the
--- 1012,1017 ----
***************
*** 980,986 ****
\lineii{bdist\_dumb}{tar, ztar, gztar, zip}
\lineii{bdist\_rpm}{rpm, srpm}
\lineii{bdist\_wininst}{wininst}
- %\lineii{bdist\_wise}{wise}
\end{tableii}
The following sections give details on the individual \command{bdist\_*}
--- 1028,1033 ----
***************
*** 1093,1099 ****
\XXX{this isn't implemented yet---is it needed?!}
You can also specify a custom \file{.spec} file with the
! \longprogramopt{spec-file} option; used in conjunctin with
\longprogramopt{spec-only}, this gives you an opportunity to customize
the \file{.spec} file manually:
\begin{verbatim}
--- 1140,1146 ----
\XXX{this isn't implemented yet---is it needed?!}
You can also specify a custom \file{.spec} file with the
! \longprogramopt{spec-file} option; used in conjunction with
\longprogramopt{spec-only}, this gives you an opportunity to customize
the \file{.spec} file manually:
\begin{verbatim}
***************
*** 1110,1116 ****
--- 1157,1194 ----
\subsection{Creating Windows installers}
\label{creating-wininst}
+ Executable Windows installers are the natural format for binary
+ distributions on Windows. They display a nice GUI interface, display
+ some information of the module distribution to be installed, taken
+ from the meta-dada in the setup script, let the user select a few
+ (currently maybe too few) options, and start or cancel the installation.
+ Since the meta-data is taken from the setup script, creating
+ Windows installers is usually as easy as running:
+ \begin{verbatim}
+ python setup.py bdist_wininst
+ \end{verbatim}
+ or the \command{bdist} command with the \longprogramopt{format} option:
+ \begin{verbatim}
+ python setup.py bdist --formats=wininst
+ \end{verbatim}
+
+ If you have a pure module distribution (only containing pure
+ Python modules and packages), the resulting installer will be
+ version independent and have a name like \file{Foo-1.0.win32.exe}.
+ These installers can even be created on \UNIX{} or MacOS platforms.
+
+ If you have a non-pure distribution, the extensions can only be
+ created on a Windows platform, and will be Python version dependend.
+ The installer filename will reflect this and now has the form
+ \file{Foo-1.0.win32-py2.0.exe}. You have to create a separate installer
+ for every Python version you want to support.
+
+ The installer will try to compile pure modules into bytecode after
+ installation on the target system in normal and optimizing mode.
+ If you don't want this to happen for some reason, you can run
+ the bdist_wininst command with the \longprogramopt{no-target-compile} and/or
+ the \longprogramopt{no-target-optimize} option.
\section{Examples}
\label{examples}
***************
*** 1146,1151 ****
--- 1224,1231 ----
\subsection{Writing new commands}
\label{new-commands}
+
+ \XXX{Would an uninstall command be a good example here?}