[Python-checkins] distutils/doc/dist dist.tex,1.40,1.41
gward@sourceforge.net
gward@sourceforge.net
Fri, 10 May 2002 07:46:01 -0700
Update of /cvsroot/python/distutils/doc/dist
In directory usw-pr-cvs1:/tmp/cvs-serv27347
Modified Files:
dist.tex
Log Message:
[from Oct 2000]
Start fleshing out the "Examples" section.
Index: dist.tex
===================================================================
RCS file: /cvsroot/python/distutils/doc/dist/dist.tex,v
retrieving revision 1.40
retrieving revision 1.41
diff -C2 -d -r1.40 -r1.41
*** dist.tex 10 May 2002 14:42:10 -0000 1.40
--- dist.tex 10 May 2002 14:45:59 -0000 1.41
***************
*** 1292,1309 ****
the \longprogramopt{no-target-optimize} option.
! %\section{Examples}
! %\label{examples}
! %\subsection{Pure Python distribution (by module)}
! %\label{pure-mod}
! %\subsection{Pure Python distribution (by package)}
! %\label{pure-pkg}
! %\subsection{Single extension module}
! %\label{single-ext}
--- 1292,1503 ----
the \longprogramopt{no-target-optimize} option.
! \section{Examples}
! \label{examples}
! \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}
! <root>/
! setup.py
! foo.py
! \end{verbatim}
! (In all diagrams in this section, \verb|<root>| 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}
+ <root>/
+ 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}
!
! 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.)
!
! If those two files are moved into a subdirectory, but remain in the root
! package, e.g.:
! \begin{verbatim}
! <root>/
! 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}
! <root>/
! 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}
! <root>/
! 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}
! <root>/
! 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}
! <root>/
! 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}
! <root>/
! 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}
***************
*** 1313,1317 ****
%\subsection{Putting it all together}
-
--- 1507,1510 ----