7 This chapter provides a number of basic examples to help get started with
8 distutils. Additional information about using distutils can be found in the
14 `Distutils Cookbook <http://www.python.org/cgi-bin/moinmoin/DistutilsCookbook>`_
15 Collection of recipes showing how to achieve more control over distutils.
20 Pure Python distribution (by module)
21 ====================================
23 If you're just distributing a couple of modules, especially if they don't live
24 in a particular package, you can specify them individually using the
25 :option:`py_modules` option in the setup script.
27 In the simplest case, you'll have two files to worry about: a setup script and
28 the single module you're distributing, :file:`foo.py` in this example::
34 (In all diagrams in this section, *<root>* will refer to the distribution root
35 directory.) A minimal setup script to describe this situation would be::
37 from distutils.core import setup
43 Note that the name of the distribution is specified independently with the
44 :option:`name` option, and there's no rule that says it has to be the same as
45 the name of the sole module in the distribution (although that's probably a good
46 convention to follow). However, the distribution name is used to generate
47 filenames, so you should stick to letters, digits, underscores, and hyphens.
49 Since :option:`py_modules` is a list, you can of course specify multiple
50 modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your
51 setup might look like this::
58 and the setup script might be ::
60 from distutils.core import setup
63 py_modules=['foo', 'bar'],
66 You can put module source files into another directory, but if you have enough
67 modules to do that, it's probably easier to specify modules by package rather
68 than listing them individually.
73 Pure Python distribution (by package)
74 =====================================
76 If you have more than a couple of modules to distribute, especially if they are
77 in multiple packages, it's probably easier to specify whole packages rather than
78 individual modules. This works even if your modules are not in a package; you
79 can just tell the Distutils to process modules from the root package, and that
80 works the same as any other package (except that you don't have to have an
81 :file:`__init__.py` file).
83 The setup script from the last example could also be written as ::
85 from distutils.core import setup
91 (The empty string stands for the root package.)
93 If those two files are moved into a subdirectory, but remain in the root
101 then you would still specify the root package, but you have to tell the
102 Distutils where source files in the root package live::
104 from distutils.core import setup
107 package_dir={'': 'src'},
111 More typically, though, you will want to distribute multiple modules in the same
112 package (or in sub-packages). For example, if the :mod:`foo` and :mod:`bar`
113 modules belong in package :mod:`foobar`, one way to layout your source tree is
123 This is in fact the default layout expected by the Distutils, and the one that
124 requires the least work to describe in your setup script::
126 from distutils.core import setup
132 If you want to put modules in directories not named for their package, then you
133 need to use the :option:`package_dir` option again. For example, if the
134 :file:`src` directory holds modules in the :mod:`foobar` package::
143 an appropriate setup script would be ::
145 from distutils.core import setup
148 package_dir={'foobar': 'src'},
152 Or, you might put modules from your main package right in the distribution
161 in which case your setup script would be ::
163 from distutils.core import setup
166 package_dir={'foobar': ''},
170 (The empty string also stands for the current directory.)
172 If you have sub-packages, they must be explicitly listed in :option:`packages`,
173 but any entries in :option:`package_dir` automatically extend to sub-packages.
174 (In other words, the Distutils does *not* scan your source tree, trying to
175 figure out which directories correspond to Python packages by looking for
176 :file:`__init__.py` files.) Thus, if the default layout grows a sub-package::
188 then the corresponding setup script would be ::
190 from distutils.core import setup
193 packages=['foobar', 'foobar.subfoo'],
196 (Again, the empty string in :option:`package_dir` stands for the current
202 Single extension module
203 =======================
205 Extension modules are specified using the :option:`ext_modules` option.
206 :option:`package_dir` has no effect on where extension source files are found;
207 it only affects the source for pure Python modules. The simplest case, a
208 single extension module in a single C source file, is::
214 If the :mod:`foo` extension belongs in the root package, the setup script for
217 from distutils.core import setup
218 from distutils.extension import Extension
221 ext_modules=[Extension('foo', ['foo.c'])],
224 If the extension actually belongs in a package, say :mod:`foopkg`, then
226 With exactly the same source tree layout, this extension can be put in the
227 :mod:`foopkg` package simply by changing the name of the extension::
229 from distutils.core import setup
230 from distutils.extension import Extension
233 ext_modules=[Extension('foopkg.foo', ['foo.c'])],
236 .. % \section{Multiple extension modules}
237 .. % \label{multiple-ext}
239 .. % \section{Putting it all together}