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/DistutilsCookbook>`_

    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 .. % \section{Multiple extension modules}

   237 .. % \label{multiple-ext}

   238 

   239 .. % \section{Putting it all together}

   240 

   241