/Doc/distutils/examples.rst

  1.. _examples:
  2
  3********
  4Examples
  5********
  6
  7This chapter provides a number of basic examples to help get started with
  8distutils.  Additional information about using distutils can be found in the
  9Distutils Cookbook.
 10
 11
 12.. seealso::
 13
 14   `Distutils Cookbook <http://wiki.python.org/moin/Distutils/Cookbook>`_
 15      Collection of recipes showing how to achieve more control over distutils.
 16
 17
 18.. _pure-mod:
 19
 20Pure Python distribution (by module)
 21====================================
 22
 23If you're just distributing a couple of modules, especially if they don't live
 24in a particular package, you can specify them individually using the
 25:option:`py_modules` option in the setup script.
 26
 27In the simplest case, you'll have two files to worry about: a setup script and
 28the single module you're distributing, :file:`foo.py` in this example::
 29
 30   <root>/
 31           setup.py
 32           foo.py
 33
 34(In all diagrams in this section, *<root>* will refer to the distribution root
 35directory.)  A minimal setup script to describe this situation would be::
 36
 37   from distutils.core import setup
 38   setup(name='foo',
 39         version='1.0',
 40         py_modules=['foo'],
 41         )
 42
 43Note 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
 45the name of the sole module in the distribution (although that's probably a good
 46convention to follow).  However, the distribution name is used to generate
 47filenames, so you should stick to letters, digits, underscores, and hyphens.
 48
 49Since :option:`py_modules` is a list, you can of course specify multiple
 50modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your
 51setup might look like this::
 52
 53   <root>/
 54           setup.py
 55           foo.py
 56           bar.py
 57
 58and the setup script might be  ::
 59
 60   from distutils.core import setup
 61   setup(name='foobar',
 62         version='1.0',
 63         py_modules=['foo', 'bar'],
 64         )
 65
 66You can put module source files into another directory, but if you have enough
 67modules to do that, it's probably easier to specify modules by package rather
 68than listing them individually.
 69
 70
 71.. _pure-pkg:
 72
 73Pure Python distribution (by package)
 74=====================================
 75
 76If you have more than a couple of modules to distribute, especially if they are
 77in multiple packages, it's probably easier to specify whole packages rather than
 78individual modules.  This works even if your modules are not in a package; you
 79can just tell the Distutils to process modules from the root package, and that
 80works the same as any other package (except that you don't have to have an
 81:file:`__init__.py` file).
 82
 83The setup script from the last example could also be written as  ::
 84
 85   from distutils.core import setup
 86   setup(name='foobar',
 87         version='1.0',
 88         packages=[''],
 89         )
 90
 91(The empty string stands for the root package.)
 92
 93If those two files are moved into a subdirectory, but remain in the root
 94package, e.g.::
 95
 96   <root>/
 97           setup.py
 98           src/      foo.py
 99                     bar.py
100
101then you would still specify the root package, but you have to tell the
102Distutils where source files in the root package live::
103
104   from distutils.core import setup
105   setup(name='foobar',
106         version='1.0',
107         package_dir={'': 'src'},
108         packages=[''],
109         )
110
111More typically, though, you will want to distribute multiple modules in the same
112package (or in sub-packages).  For example, if the :mod:`foo`  and :mod:`bar`
113modules belong in package :mod:`foobar`, one way to layout your source tree is
114::
115
116   <root>/
117           setup.py
118           foobar/
119                    __init__.py
120                    foo.py
121                    bar.py
122
123This is in fact the default layout expected by the Distutils, and the one that
124requires the least work to describe in your setup script::
125
126   from distutils.core import setup
127   setup(name='foobar',
128         version='1.0',
129         packages=['foobar'],
130         )
131
132If you want to put modules in directories not named for their package, then you
133need to use the :option:`package_dir` option again.  For example, if the
134:file:`src` directory holds modules in the :mod:`foobar` package::
135
136   <root>/
137           setup.py
138           src/
139                    __init__.py
140                    foo.py
141                    bar.py
142
143an appropriate setup script would be  ::
144
145   from distutils.core import setup
146   setup(name='foobar',
147         version='1.0',
148         package_dir={'foobar': 'src'},
149         packages=['foobar'],
150         )
151
152Or, you might put modules from your main package right in the distribution
153root::
154
155   <root>/
156           setup.py
157           __init__.py
158           foo.py
159           bar.py
160
161in which case your setup script would be  ::
162
163   from distutils.core import setup
164   setup(name='foobar',
165         version='1.0',
166         package_dir={'foobar': ''},
167         packages=['foobar'],
168         )
169
170(The empty string also stands for the current directory.)
171
172If you have sub-packages, they must be explicitly listed in :option:`packages`,
173but 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
175figure out which directories correspond to Python packages by looking for
176:file:`__init__.py` files.)  Thus, if the default layout grows a sub-package::
177
178   <root>/
179           setup.py
180           foobar/
181                    __init__.py
182                    foo.py
183                    bar.py
184                    subfoo/
185                              __init__.py
186                              blah.py
187
188then the corresponding setup script would be  ::
189
190   from distutils.core import setup
191   setup(name='foobar',
192         version='1.0',
193         packages=['foobar', 'foobar.subfoo'],
194         )
195
196(Again, the empty string in :option:`package_dir` stands for the current
197directory.)
198
199
200.. _single-ext:
201
202Single extension module
203=======================
204
205Extension modules are specified using the :option:`ext_modules` option.
206:option:`package_dir` has no effect on where extension source files are found;
207it only affects the source for pure Python modules.  The simplest  case, a
208single extension module in a single C source file, is::
209
210   <root>/
211           setup.py
212           foo.c
213
214If the :mod:`foo` extension belongs in the root package, the setup script for
215this could be  ::
216
217   from distutils.core import setup
218   from distutils.extension import Extension
219   setup(name='foobar',
220         version='1.0',
221         ext_modules=[Extension('foo', ['foo.c'])],
222         )
223
224If the extension actually belongs in a package, say :mod:`foopkg`, then
225
226With 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::
228
229   from distutils.core import setup
230   from distutils.extension import Extension
231   setup(name='foobar',
232         version='1.0',
233         ext_modules=[Extension('foopkg.foo', ['foo.c'])],
234         )
235
236.. % \section{Multiple extension modules}
237.. % \label{multiple-ext}
238
239.. % \section{Putting it all together}
240
241