Doc/distutils/examples.rst

   1 .. _examples:
   2
   3 ********
   4 Examples
   5 ********
   6
   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
   9 Distutils 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
  20 Pure Python distribution (by module)
  21 ====================================
  22
  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.
  26
  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::
  29
  30    <root>/
  31            setup.py
  32            foo.py
  33
  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::
  36
  37    from distutils.core import setup
  38    setup(name='foo',
  39          version='1.0',
  40          py_modules=['foo'],
  41          )
  42
  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.
  48
  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::
  52
  53    <root>/
  54            setup.py
  55            foo.py
  56            bar.py
  57
  58 and 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
  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.
  69
  70
  71 .. _pure-pkg:
  72
  73 Pure Python distribution (by package)
  74 =====================================
  75
  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).
  82
  83 The 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
  93 If those two files are moved into a subdirectory, but remain in the root
  94 package, e.g.::
  95
  96    <root>/
  97            setup.py
  98            src/      foo.py
  99                      bar.py
 100
 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::
 103
 104    from distutils.core import setup
 105    setup(name='foobar',
 106          version='1.0',
 107          package_dir={'': 'src'},
 108          packages=[''],
 109          )
 110
 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
 114 ::
 115
 116    <root>/
 117            setup.py
 118            foobar/
 119                     __init__.py
 120                     foo.py
 121                     bar.py
 122
 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::
 125
 126    from distutils.core import setup
 127    setup(name='foobar',
 128          version='1.0',
 129          packages=['foobar'],
 130          )
 131
 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::
 135
 136    <root>/
 137            setup.py
 138            src/
 139                     __init__.py
 140                     foo.py
 141                     bar.py
 142
 143 an 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
 152 Or, you might put modules from your main package right in the distribution
 153 root::
 154
 155    <root>/
 156            setup.py
 157            __init__.py
 158            foo.py
 159            bar.py
 160
 161 in 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
 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::
 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
 188 then 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
 197 directory.)
 198
 199
 200 .. _single-ext:
 201
 202 Single extension module
 203 =======================
 204
 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::
 209
 210    <root>/
 211            setup.py
 212            foo.c
 213
 214 If the :mod:`foo` extension belongs in the root package, the setup script for
 215 this 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
 224 If the extension actually belongs in a package, say :mod:`foopkg`, then
 225
 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::
 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 Checking a package
 237 ==================
 238
 239 The ``check`` command allows you to verify if your package meta-data
 240 meet the minimum requirements to build a distribution.
 241
 242 To run it, just call it using your :file:`setup.py` script. If something is
 243 missing, ``check`` will display a warning.
 244
 245 Let's take an example with a simple script::
 246
 247     from distutils.core import setup
 248
 249     setup(name='foobar')
 250
 251 Running the ``check`` command will display some warnings::
 252
 253     $ python setup.py check
 254     running check
 255     warning: check: missing required meta-data: version, url
 256     warning: check: missing meta-data: either (author and author_email) or
 257              (maintainer and maintainer_email) must be supplied
 258
 259
 260 If you use the reStructuredText syntax in the `long_description` field and
 261 `docutils <http://docutils.sourceforge.net/>`_ is installed you can check if
 262 the syntax is fine with the ``check`` command, using the `restructuredtext`
 263 option.
 264
 265 For example, if the :file:`setup.py` script is changed like this::
 266
 267     from distutils.core import setup
 268
 269     desc = """\
 270     My description
 271     =============
 272
 273     This is the description of the ``foobar`` package.
 274     """
 275
 276     setup(name='foobar', version='1', author='tarek',
 277         author_email='tarek@ziade.org',
 278         url='http://example.com', long_description=desc)
 279
 280 Where the long description is broken, ``check`` will be able to detect it
 281 by using the `docutils` parser::
 282
 283     $ pythontrunk setup.py check --restructuredtext
 284     running check
 285     warning: check: Title underline too short. (line 2)
 286     warning: check: Could not finish the parsing.
 287
 288 .. % \section{Multiple extension modules}
 289 .. % \label{multiple-ext}
 290
 291 .. % \section{Putting it all together}
 292
 293