From a09262e860cfa9a6807b2daa711d4710967896dc Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Thu, 1 Mar 2001 18:35:43 +0000 Subject: [PATCH] Comment out section titles for sections that have not been written yet; there is no need to clutter a reader's life with those useless things. Make the snippets of Python code conform to the standard style. Suppress the "Contents" page for HTML; it is not needed for small documents in the online environment since LaTeX2HTML generates lots of tables of links anyway. Various markup consistency nits. --- Doc/dist/dist.tex | 206 +++++++++++++++++++++++++++++++--------------- 1 file changed, 141 insertions(+), 65 deletions(-) diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex index 884a0ee4f6b..38911a1752f 100644 --- a/Doc/dist/dist.tex +++ b/Doc/dist/dist.tex @@ -22,7 +22,13 @@ build/release/install mechanics. \end{abstract} +% The ugly "%begin{latexonly}" pseudo-environment supresses the table +% of contents for HTML generation. +% +%begin{latexonly} \tableofcontents +%end{latexonly} + \section{Introduction} \label{intro} @@ -88,11 +94,12 @@ it.\footnote{But be careful about putting arbitrarily expensive all you want to do is distribute a module called \module{foo}, contained in a file \file{foo.py}, then your setup script can be as little as this: + \begin{verbatim} from distutils.core import setup -setup (name = "foo", - version = "1.0", - py_modules = ["foo"]) +setup(name="foo", + version="1.0", + py_modules=["foo"]) \end{verbatim} Some observations: @@ -111,9 +118,11 @@ Some observations: To create a source distribution for this module, you would create a setup script, \file{setup.py}, containing the above code, and run: + \begin{verbatim} python setup.py sdist \end{verbatim} + which will create an archive file (e.g., tarball on \UNIX, ZIP file on Windows) containing your setup script, \file{setup.py}, and your module, \file{foo.py}. The archive file will be named \file{Foo-1.0.tar.gz} (or @@ -122,9 +131,11 @@ Windows) containing your setup script, \file{setup.py}, and your module, If an end-user wishes to install your \module{foo} module, all she has to do is download \file{Foo-1.0.tar.gz} (or \file{.zip}), unpack it, and---from the \file{Foo-1.0} directory---run + \begin{verbatim} python setup.py install \end{verbatim} + which will ultimately copy \file{foo.py} to the appropriate directory for third-party modules in their Python installation. @@ -142,9 +153,11 @@ running on a Windows machine, and want to make things easy for other Windows users, you can create an executable installer (the most appropriate type of built distribution for this platform) with the \command{bdist\_wininst} command. For example: + \begin{verbatim} python setup.py bdist_wininst \end{verbatim} + will create an executable installer, \file{Foo-1.0.win32.exe}, in the current directory. @@ -152,14 +165,17 @@ 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}: + \begin{verbatim} python setup.py bdist_rpm \end{verbatim} + (This uses the \command{rpm} command, so has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or Mandrake Linux.) You can find out what distribution formats are available at any time by running + \begin{verbatim} python setup.py bdist --help-formats \end{verbatim} @@ -249,16 +265,16 @@ shown here, is used to install the package into Python 1.5.2.) from distutils.core import setup -setup (name = "Distutils", - version = "1.0", - description = "Python Distribution Utilities", - author = "Greg Ward", - author_email = "gward@python.net", - url = "http://www.python.org/sigs/distutils-sig/", - - packages = ['distutils', 'distutils.command'], - ) +setup(name="Distutils", + version="1.0", + description="Python Distribution Utilities", + author="Greg Ward", + author_email="gward@python.net", + url="http://www.python.org/sigs/distutils-sig/", + packages=['distutils', 'distutils.command'], + ) \end{verbatim} + There are only two differences between this and the trivial one-file distribution presented in section~\ref{simple-example}: more meta-data, and the specification of pure Python modules by package, @@ -282,6 +298,7 @@ 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')) @@ -311,9 +328,11 @@ you keep all Python source under \file{lib}, so that modules in the ``root package'' (i.e., not in any package at all) are right in \file{lib}, modules in the \module{foo} package are in \file{lib/foo}, and so forth. Then you would put + \begin{verbatim} package_dir = {'': 'lib'} \end{verbatim} + in your setup script. (The keys to this dictionary are package names, and an empty package name stands for the root package. The values are directory names relative to your distribution root.) In this case, when @@ -323,9 +342,11 @@ you say \code{packages = ['foo']}, you are promising that the file Another possible convention is to put the \module{foo} package right in \file{lib}, the \module{foo.bar} package in \file{lib/bar}, etc. This would be written in the setup script as + \begin{verbatim} package_dir = {'foo': 'lib'} \end{verbatim} + A \code{\var{package}: \var{dir}} entry in the \option{package\_dir} dictionary implicitly applies to all packages below \var{package}, so the \module{foo.bar} case is automatically handled here. In this @@ -346,9 +367,11 @@ rather than listing packages---especially the case of a single module that goes in the ``root package'' (i.e., no package at all). This simplest case was shown in section~\ref{simple-example}; here is a slightly more involved example: + \begin{verbatim} py_modules = ['mod1', 'pkg.mod2'] \end{verbatim} + 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 @@ -375,17 +398,20 @@ 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", - ext_modules = [Extension("foo", ["foo.c"])]) +setup(name="foo", version="1.0", + ext_modules=[Extension("foo", ["foo.c"])]) \end{verbatim} The \class{Extension} class (actually, the underlying extension-building @@ -398,13 +424,17 @@ explained in the following sections. 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 @@ -413,13 +443,15 @@ 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", - ext_modules = [Extension("foo", ["foo.c"]), - Extension("subpkg.bar", ["bar.c"])] + ext_package="pkg", + ext_modules=[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}. @@ -458,6 +490,7 @@ define/undefine: \code{include\_dirs}, \code{define\_macros}, and 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} @@ -465,9 +498,11 @@ Extension("foo", ["foo.c"], include_dirs=["include"]) 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{}. @@ -485,12 +520,14 @@ extensions, the best approach is to include (e.g.) \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. @@ -506,13 +543,16 @@ macro \code{FOO} to \code{None} is the equivalent of a bare 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 @@ -532,6 +572,7 @@ 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"]) @@ -539,11 +580,13 @@ Extension(..., 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.) @@ -584,12 +627,14 @@ 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']), @@ -625,9 +670,6 @@ then you need the Distutils ``auto-configuration'' facility. This started to appear in Distutils 0.9 but, as of this writing, isn't mature or stable enough yet for real-world use.) -\XXX{should reference description of distutils config files in - ``Installing'' manual here} - The setup configuration file is a useful middle-ground between the setup script---which, ideally, would be opaque to installers\footnote{This ideal probably won't be achieved until auto-configuration is fully @@ -647,11 +689,13 @@ several useful consequences: \end{itemize} The basic syntax of the configuration file is simple: + \begin{verbatim} [command] option=value ... \end{verbatim} + where \var{command} is one of the Distutils commands (e.g. \command{build\_py}, \command{install}), and \var{option} is one of the options that command supports. Any number of options can be supplied @@ -662,6 +706,7 @@ split across multiple lines simply by indenting the continuation lines. You can find out the list of options supported by a particular command with the universal \longprogramopt{help} option, e.g. + \begin{verbatim} > python setup.py --help build_ext [...] @@ -675,6 +720,7 @@ Options for 'build_ext' command: --undef (-U) C preprocessor macros to undefine [...] \end{verbatim} + Or consult section \ref{reference} of this document (the command reference). @@ -687,17 +733,21 @@ want the compiled extension file (\file{ext.so} on \UNIX, say) to be put in the same source directory as your pure Python modules \module{pkg.mod1} and \module{pkg.mod2}. You can always use the \longprogramopt{inplace} option on the command-line to ensure this: + \begin{verbatim} python setup.py build_ext --inplace \end{verbatim} + But this requires that you always specify the \command{build\_ext} command explicitly, and remember to provide \longprogramopt{inplace}. An easier way is to ``set and forget'' this option, by encoding it in \file{setup.cfg}, the configuration file for this distribution: + \begin{verbatim} [build_ext] inplace=1 \end{verbatim} + This will affect all builds of this module distribution, whether or not you explcitly specify \command{build\_ext}. If you include \file{setup.cfg} in your source distribution, it will also affect @@ -717,6 +767,7 @@ files installed). But some of it has to be supplied as options to \command{bdist\_rpm}, which would be very tedious to do on the command-line for every run. Hence, here is a snippet from the Distutils' own \file{setup.cfg}: + \begin{verbatim} [bdist_rpm] release = 1 @@ -727,19 +778,29 @@ doc_files = CHANGES.txt doc/ examples/ \end{verbatim} + Note that the \option{doc\_files} option is simply a whitespace-separated string split across multiple lines for readability. +\begin{seealso} + \seetitle[../inst/config-syntax.html]{Installing Python + Modules}{More information on the configuration files is + available in the manual for system administrators.} +\end{seealso} + + \section{Creating a Source Distribution} \label{source-dist} As shown in section~\ref{simple-example}, you use the \command{sdist} command to create a source distribution. In the simplest case, + \begin{verbatim} python setup.py sdist \end{verbatim} + (assuming you haven't specified any \command{sdist} options in the setup script or config file), \command{sdist} creates the archive of the default format for the current platform. The default format is gzip'ed @@ -748,9 +809,11 @@ tar file (\file{.tar.gz}) on \UNIX, and ZIP file on Windows. You can specify as many formats as you like using the \longprogramopt{formats} option, for example: + \begin{verbatim} python setup.py sdist --formats=gztar,zip \end{verbatim} + to create a gzipped tarball and a zip file. The available formats are: \begin{tableiii}{l|l|c}{code}% {Format}{Description}{Notes} @@ -810,11 +873,13 @@ The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an example, again we turn to the Distutils' own manifest template: + \begin{verbatim} include *.txt recursive-include examples *.txt *.py prune examples/sample?/build \end{verbatim} + The meanings should be fairly clear: include all files in the distribution root matching \code{*.txt}, all files anywhere under the \file{examples} directory matching \code{*.txt} or \code{*.py}, and @@ -905,15 +970,18 @@ Second, you might want to force the manifest to be regenerated---for example, if you have added or removed files or directories that match an existing pattern in the manifest template, you should regenerate the manifest: + \begin{verbatim} python setup.py sdist --force-manifest \end{verbatim} Or, you might just want to (re)generate the manifest, but not create a source distribution: + \begin{verbatim} python setup.py sdist --manifest-only \end{verbatim} + \longprogramopt{manifest-only} implies \longprogramopt{force-manifest}. \programopt{-o} is a shortcut for \longprogramopt{manifest-only}, and \programopt{-f} for \longprogramopt{force-manifest}. @@ -953,9 +1021,11 @@ distributions. As a simple example, if I run the following command in the Distutils source tree: + \begin{verbatim} python setup.py bdist \end{verbatim} + then the Distutils builds my module distribution (the Distutils itself in this case), does a ``fake'' installation (also in the \file{build} directory), and creates the default type of built distribution for my @@ -983,9 +1053,11 @@ win for users even if your distribution doesn't include any extensions. The \command{bdist} command has a \longprogramopt{formats} option, similar to the \command{sdist} command, which you can use to select the types of built distribution to generate: for example, + \begin{verbatim} python setup.py bdist --format=zip \end{verbatim} + would, when run on a \UNIX{} system, create \file{Distutils-0.8.\filevar{plat}.zip}---again, this archive would be unpacked from the root directory to install the Distutils. @@ -1054,17 +1126,22 @@ work on different RPM-based distributions. The usual way to create an RPM of your module distribution is to run the \command{bdist\_rpm} command: + \begin{verbatim} python setup.py bdist_rpm \end{verbatim} + or the \command{bdist} command with the \longprogramopt{format} option: + \begin{verbatim} python setup.py bdist --formats=rpm \end{verbatim} + The former allows you to specify RPM-specific options; the latter allows you to easily specify multiple formats in one run. If you need to do both, you can explicitly specify multiple \command{bdist\_*} commands and their options: + \begin{verbatim} python setup.py bdist_rpm --packager="John Doe " \ bdist_wininst --target_version="2.0" @@ -1143,11 +1220,13 @@ 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} > python setup.py bdist_rpm --spec-only # ...edit dist/FooBar-1.0.spec > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec \end{verbatim} + (Although a better way to do this is probably to override the standard \command{bdist\_rpm} command with one that writes whatever else you want to the \file{.spec} file; see section~\ref{extending} for information on @@ -1165,10 +1244,13 @@ from the meta-dada in the setup script, let the user select a few 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} @@ -1190,42 +1272,42 @@ 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} +%\section{Examples} +%\label{examples} -\subsection{Pure Python distribution (by module)} -\label{pure-mod} +%\subsection{Pure Python distribution (by module)} +%\label{pure-mod} -\subsection{Pure Python distribution (by package)} -\label{pure-pkg} +%\subsection{Pure Python distribution (by package)} +%\label{pure-pkg} -\subsection{Single extension module} -\label{single-ext} +%\subsection{Single extension module} +%\label{single-ext} -\subsection{Multiple extension modules} -\label{multiple-ext} +%\subsection{Multiple extension modules} +%\label{multiple-ext} -\subsection{Putting it all together} +%\subsection{Putting it all together} -\section{Extending the Distutils} -\label{extending} +%\section{Extending the Distutils} +%\label{extending} -\subsection{Extending existing commands} -\label{extend-existing} +%\subsection{Extending existing commands} +%\label{extend-existing} -\subsection{Writing new commands} -\label{new-commands} +%\subsection{Writing new commands} +%\label{new-commands} -\XXX{Would an uninstall command be a good example here?} +%\XXX{Would an uninstall command be a good example here?} @@ -1233,20 +1315,20 @@ the \longprogramopt{no-target-optimize} option. \label{reference} -\subsection{Building modules: the \protect\command{build} command family} -\label{build-cmds} +%\subsection{Building modules: the \protect\command{build} command family} +%\label{build-cmds} -\subsubsection{\protect\command{build}} -\label{build-cmd} +%\subsubsection{\protect\command{build}} +%\label{build-cmd} -\subsubsection{\protect\command{build\_py}} -\label{build-py-cmd} +%\subsubsection{\protect\command{build\_py}} +%\label{build-py-cmd} -\subsubsection{\protect\command{build\_ext}} -\label{build-ext-cmd} +%\subsubsection{\protect\command{build\_ext}} +%\label{build-ext-cmd} -\subsubsection{\protect\command{build\_clib}} -\label{build-clib-cmd} +%\subsubsection{\protect\command{build\_clib}} +%\label{build-clib-cmd} \subsection{Installing modules: the \protect\command{install} command family} @@ -1257,8 +1339,8 @@ runs the subcommands \command{install\_lib}, \command{install\_data} and \command{install\_scripts}. -\subsubsection{\protect\command{install\_lib}} -\label{install-lib-cmd} +%\subsubsection{\protect\command{install\_lib}} +%\label{install-lib-cmd} \subsubsection{\protect\command{install\_data}} \label{install-data-cmd} @@ -1269,8 +1351,8 @@ This command installs all data files provided with the distribution. This command installs all (Python) scripts in the distribution. -\subsection{Cleaning up: the \protect\command{clean} command} -\label{clean-cmd} +%\subsection{Cleaning up: the \protect\command{clean} command} +%\label{clean-cmd} \subsection{Creating a source distribution: the @@ -1310,24 +1392,18 @@ anything except backslash or colon; on MacOS anything except colon. \XXX{Windows and MacOS support not there yet} -\subsection{Creating a ``built'' distribution: the - \protect\command{bdist} command family} -\label{bdist-cmds} - - -\subsubsection{\protect\command{blib}} - -\subsubsection{\protect\command{blib\_dumb}} - -\subsubsection{\protect\command{blib\_rpm}} - -\subsubsection{\protect\command{blib\_wise}} - +%\subsection{Creating a built distribution: the +% \protect\command{bdist} command family} +%\label{bdist-cmds} +%\subsubsection{\protect\command{blib}} +%\subsubsection{\protect\command{blib\_dumb}} +%\subsubsection{\protect\command{blib\_rpm}} +%\subsubsection{\protect\command{blib\_wise}} \end{document}