From 007c04a9d34abf4d78031e5d02eb9b485786601f Mon Sep 17 00:00:00 2001 From: Greg Ward Date: Fri, 10 May 2002 14:45:59 +0000 Subject: [from Oct 2000] Start fleshing out the "Examples" section. --- Doc/dist/dist.tex | 211 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 202 insertions(+), 9 deletions(-) diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex index 305f320..c6acc04 100644 --- a/Doc/dist/dist.tex +++ b/Doc/dist/dist.tex @@ -1291,20 +1291,214 @@ 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} +If you're just distributing a couple of modules, especially if they +don't live in a particular package, you can specify them individually +using the \option{py\_modules} option in the setup script. + +In the simplest case, you'll have two files to worry about: a setup +script and the single module you're distributing, \file{foo.py} in this +example: +\begin{verbatim} +/ + setup.py + foo.py +\end{verbatim} +(In all diagrams in this section, \verb|| will refer to the +distribution root directory.) A minimal setup script to describe this +situation would be: +\begin{verbatim} +from distutils.core import setup +setup(name = "foo", version = "1.0", + py_modules = ["foo"]) +\end{verbatim} +Note that the name of the distribution is specified independently with +the \option{name} option, and there's no rule that says it has to be the +same as the name of the sole module in the distribution (although that's +probably a good convention to follow). However, the distribution name +is used to generate filenames, so you should stick to letters, digits, +underscores, and hyphens. + +Since \option{py\_modules} is a list, you can of course specify multiple +modules, eg. if you're distributing modules \module{foo} and +\module{bar}, your setup might look like this: +\begin{verbatim} +/ + setup.py + foo.py + bar.py +\end{verbatim} +and the setup script might be +\begin{verbatim} +from distutils.core import setup +setup(name = "foobar", version = "1.0", + py_modules = ["foo", "bar"]) +\end{verbatim} + +You can put module source files into another directory, but if you have +enough modules to do that, it's probably easier to specify modules by +package rather than listing them individually. -%\subsection{Pure Python distribution (by package)} -%\label{pure-pkg} +\subsection{Pure Python distribution (by package)} +\label{pure-pkg} + +If you have more than a couple of modules to distribute, especially if +they are in multiple packages, it's probably easier to specify whole +packages rather than individual modules. This works even if your +modules are not in a package; you can just tell the Distutils to process +modules from the root package, and that works the same as any other +package (except that you don't have to have an \file{\_\_init\_\_.py} +file). + +The setup script from the last example could also be written as +\begin{verbatim} +from distutils.core import setup +setup(name = "foobar", version = "1.0", + packages = [""]) +\end{verbatim} +(The empty string stands for the root package.) -%\subsection{Single extension module} -%\label{single-ext} +If those two files are moved into a subdirectory, but remain in the root +package, e.g.: +\begin{verbatim} +/ + setup.py + src/ foo.py + bar.py +\end{verbatim} +then you would still specify the root package, but you have to tell the +Distutils where source files in the root package live: +\begin{verbatim} +from distutils.core import setup +setup(name = "foobar", version = "1.0", + package_dir = {"": "src"}, + packages = [""]) +\end{verbatim} + +More typically, though, you will want to distribute multiple modules in +the same package (or in sub-packages). For example, if the \module{foo} +and \module{bar} modules belong in package \module{foobar}, one way to +layout your source tree is +\begin{verbatim} +/ + setup.py + foobar/ + __init__.py + foo.py + bar.py +\end{verbatim} +This is in fact the default layout expected by the Distutils, and the +one that requires the least work to describe in your setup script: +\begin{verbatim} +from distutils.core import setup +setup(name = "foobar", version = "1.0", + packages = ["foobar"]) +\end{verbatim} + +If you want to put modules in directories not named for their package, +then you need to use the \option{package\_dir} option again. For +example, if the \file{src} directory holds modules in the +\module{foobar} package: +\begin{verbatim} +/ + setup.py + src/ + __init__.py + foo.py + bar.py +\end{verbatim} +an appropriate setup script would be +\begin{verbatim} +from distutils.core import setup +setup(name = "foobar", version = "1.0", + package_dir = {"foobar" : "src"}, + packages = ["foobar"]) +\end{verbatim} + +Or, you might put modules from your main package right in the +distribution root: +\begin{verbatim} +/ + setup.py + __init__.py + foo.py + bar.py +\end{verbatim} +in which case your setup script would be +\begin{verbatim} +from distutils.core import setup +setup(name = "foobar", version = "1.0", + package_dir = {"foobar" : ""}, + packages = ["foobar"]) +\end{verbatim} +(The empty string also stands for the current directory.) + +If you have sub-packages, they must be explicitly listed in +\option{packages}, but any entries in \option{package\_dir} +automatically extend to sub-packages. (In other words, the Distutils +does \emph{not} scan your source tree, trying to figure out which +directories correspond to Python packages by looking for +\file{\_\_init\_\_.py} files.) Thus, if the default layout grows a +sub-package: +\begin{verbatim} +/ + setup.py + foobar/ + __init__.py + foo.py + bar.py + subfoo/ + __init__.py + blah.py +\end{verbatim} +then the corresponding setup script would be +\begin{verbatim} +from distutils.core import setup +setup(name = "foobar", version = "1.0", + packages = ["foobar", "foobar.subfoo"]) +\end{verbatim} +(Again, the empty string in \option{package\_dir} stands for the current +directory.) + + +\subsection{Single extension module} +\label{single-ext} + +Extension modules are specified using the \option{ext\_modules} option. +\option{package\_dir} has no effect on where extension source files are +found; it only affects the source for pure Python modules. The simplest +case, a single extension module in a single C source file, is: +\begin{verbatim} +/ + setup.py + foo.c +\end{verbatim} +If the \module{foo} extension belongs in the root package, the setup +script for this could be +\begin{verbatim} +from distutils.core import setup +setup(name = "foobar", version = "1.0", + ext_modules = [Extension("foo", ["foo.c"])]) +\end{verbatim} + +If the extension actually belongs in a package, say \module{foopkg}, +then + +With exactly the same source tree layout, this extension can be put in +the \module{foopkg} package simply by changing the name of the +extension: +\begin{verbatim} +from distutils.core import setup +setup(name = "foobar", version = "1.0", + ext_modules = [Extension("foopkg.foo", ["foo.c"])]) +\end{verbatim} %\subsection{Multiple extension modules} @@ -1314,7 +1508,6 @@ the \longprogramopt{no-target-optimize} option. %\subsection{Putting it all together} - %\section{Extending the Distutils} %\label{extending} -- cgit v0.12