Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | .. _setup-script: |
| 2 | |
| 3 | ************************ |
| 4 | Writing the Setup Script |
| 5 | ************************ |
| 6 | |
| 7 | The setup script is the centre of all activity in building, distributing, and |
| 8 | installing modules using the Distutils. The main purpose of the setup script is |
| 9 | to describe your module distribution to the Distutils, so that the various |
| 10 | commands that operate on your modules do the right thing. As we saw in section |
| 11 | :ref:`distutils-simple-example` above, the setup script consists mainly of a call to |
| 12 | :func:`setup`, and most information supplied to the Distutils by the module |
| 13 | developer is supplied as keyword arguments to :func:`setup`. |
| 14 | |
| 15 | Here's a slightly more involved example, which we'll follow for the next couple |
| 16 | of sections: the Distutils' own setup script. (Keep in mind that although the |
| 17 | Distutils are included with Python 1.6 and later, they also have an independent |
| 18 | existence so that Python 1.5.2 users can use them to install other module |
| 19 | distributions. The Distutils' own setup script, shown here, is used to install |
| 20 | the package into Python 1.5.2.) :: |
| 21 | |
| 22 | #!/usr/bin/env python |
| 23 | |
| 24 | from distutils.core import setup |
| 25 | |
| 26 | setup(name='Distutils', |
| 27 | version='1.0', |
| 28 | description='Python Distribution Utilities', |
| 29 | author='Greg Ward', |
| 30 | author_email='gward@python.net', |
| 31 | url='http://www.python.org/sigs/distutils-sig/', |
| 32 | packages=['distutils', 'distutils.command'], |
| 33 | ) |
| 34 | |
| 35 | There are only two differences between this and the trivial one-file |
| 36 | distribution presented in section :ref:`distutils-simple-example`: more metadata, and the |
| 37 | specification of pure Python modules by package, rather than by module. This is |
| 38 | important since the Distutils consist of a couple of dozen modules split into |
| 39 | (so far) two packages; an explicit list of every module would be tedious to |
| 40 | generate and difficult to maintain. For more information on the additional |
| 41 | meta-data, see section :ref:`meta-data`. |
| 42 | |
| 43 | Note that any pathnames (files or directories) supplied in the setup script |
| 44 | should be written using the Unix convention, i.e. slash-separated. The |
| 45 | Distutils will take care of converting this platform-neutral representation into |
| 46 | whatever is appropriate on your current platform before actually using the |
| 47 | pathname. This makes your setup script portable across operating systems, which |
| 48 | of course is one of the major goals of the Distutils. In this spirit, all |
| 49 | pathnames in this document are slash-separated. (Mac OS 9 programmers should |
| 50 | keep in mind that the *absence* of a leading slash indicates a relative path, |
| 51 | the opposite of the Mac OS convention with colons.) |
| 52 | |
| 53 | This, of course, only applies to pathnames given to Distutils functions. If |
| 54 | you, for example, use standard Python functions such as :func:`glob.glob` or |
| 55 | :func:`os.listdir` to specify files, you should be careful to write portable |
| 56 | code instead of hardcoding path separators:: |
| 57 | |
| 58 | glob.glob(os.path.join('mydir', 'subdir', '*.html')) |
| 59 | os.listdir(os.path.join('mydir', 'subdir')) |
| 60 | |
| 61 | |
| 62 | .. _listing-packages: |
| 63 | |
| 64 | Listing whole packages |
| 65 | ====================== |
| 66 | |
| 67 | The :option:`packages` option tells the Distutils to process (build, distribute, |
| 68 | install, etc.) all pure Python modules found in each package mentioned in the |
| 69 | :option:`packages` list. In order to do this, of course, there has to be a |
| 70 | correspondence between package names and directories in the filesystem. The |
| 71 | default correspondence is the most obvious one, i.e. package :mod:`distutils` is |
| 72 | found in the directory :file:`distutils` relative to the distribution root. |
| 73 | Thus, when you say ``packages = ['foo']`` in your setup script, you are |
| 74 | promising that the Distutils will find a file :file:`foo/__init__.py` (which |
| 75 | might be spelled differently on your system, but you get the idea) relative to |
| 76 | the directory where your setup script lives. If you break this promise, the |
| 77 | Distutils will issue a warning but still process the broken package anyways. |
| 78 | |
| 79 | If you use a different convention to lay out your source directory, that's no |
| 80 | problem: you just have to supply the :option:`package_dir` option to tell the |
| 81 | Distutils about your convention. For example, say you keep all Python source |
| 82 | under :file:`lib`, so that modules in the "root package" (i.e., not in any |
| 83 | package at all) are in :file:`lib`, modules in the :mod:`foo` package are in |
| 84 | :file:`lib/foo`, and so forth. Then you would put :: |
| 85 | |
| 86 | package_dir = {'': 'lib'} |
| 87 | |
| 88 | in your setup script. The keys to this dictionary are package names, and an |
| 89 | empty package name stands for the root package. The values are directory names |
| 90 | relative to your distribution root. In this case, when you say ``packages = |
| 91 | ['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists. |
| 92 | |
| 93 | Another possible convention is to put the :mod:`foo` package right in |
| 94 | :file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be |
| 95 | written in the setup script as :: |
| 96 | |
| 97 | package_dir = {'foo': 'lib'} |
| 98 | |
| 99 | A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly |
| 100 | applies to all packages below *package*, so the :mod:`foo.bar` case is |
| 101 | automatically handled here. In this example, having ``packages = ['foo', |
| 102 | 'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and |
| 103 | :file:`lib/bar/__init__.py`. (Keep in mind that although :option:`package_dir` |
| 104 | applies recursively, you must explicitly list all packages in |
| 105 | :option:`packages`: the Distutils will *not* recursively scan your source tree |
| 106 | looking for any directory with an :file:`__init__.py` file.) |
| 107 | |
| 108 | |
| 109 | .. _listing-modules: |
| 110 | |
| 111 | Listing individual modules |
| 112 | ========================== |
| 113 | |
| 114 | For a small module distribution, you might prefer to list all modules rather |
| 115 | than listing packages---especially the case of a single module that goes in the |
| 116 | "root package" (i.e., no package at all). This simplest case was shown in |
| 117 | section :ref:`distutils-simple-example`; here is a slightly more involved example:: |
| 118 | |
| 119 | py_modules = ['mod1', 'pkg.mod2'] |
| 120 | |
| 121 | This describes two modules, one of them in the "root" package, the other in the |
| 122 | :mod:`pkg` package. Again, the default package/directory layout implies that |
| 123 | these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and |
| 124 | that :file:`pkg/__init__.py` exists as well. And again, you can override the |
| 125 | package/directory correspondence using the :option:`package_dir` option. |
| 126 | |
| 127 | |
| 128 | .. _describing-extensions: |
| 129 | |
| 130 | Describing extension modules |
| 131 | ============================ |
| 132 | |
| 133 | Just as writing Python extension modules is a bit more complicated than writing |
| 134 | pure Python modules, describing them to the Distutils is a bit more complicated. |
| 135 | Unlike pure modules, it's not enough just to list modules or packages and expect |
| 136 | the Distutils to go out and find the right files; you have to specify the |
| 137 | extension name, source file(s), and any compile/link requirements (include |
| 138 | directories, libraries to link with, etc.). |
| 139 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 140 | .. XXX read over this section |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | |
| 142 | All of this is done through another keyword argument to :func:`setup`, the |
| 143 | :option:`ext_modules` option. :option:`ext_modules` is just a list of |
| 144 | :class:`Extension` instances, each of which describes a single extension module. |
| 145 | Suppose your distribution includes a single extension, called :mod:`foo` and |
| 146 | implemented by :file:`foo.c`. If no additional instructions to the |
| 147 | compiler/linker are needed, describing this extension is quite simple:: |
| 148 | |
| 149 | Extension('foo', ['foo.c']) |
| 150 | |
| 151 | The :class:`Extension` class can be imported from :mod:`distutils.core` along |
| 152 | with :func:`setup`. Thus, the setup script for a module distribution that |
| 153 | contains only this one extension and nothing else might be:: |
| 154 | |
| 155 | from distutils.core import setup, Extension |
| 156 | setup(name='foo', |
| 157 | version='1.0', |
| 158 | ext_modules=[Extension('foo', ['foo.c'])], |
| 159 | ) |
| 160 | |
| 161 | The :class:`Extension` class (actually, the underlying extension-building |
| 162 | machinery implemented by the :command:`build_ext` command) supports a great deal |
| 163 | of flexibility in describing Python extensions, which is explained in the |
| 164 | following sections. |
| 165 | |
| 166 | |
| 167 | Extension names and packages |
| 168 | ---------------------------- |
| 169 | |
| 170 | The first argument to the :class:`Extension` constructor is always the name of |
| 171 | the extension, including any package names. For example, :: |
| 172 | |
| 173 | Extension('foo', ['src/foo1.c', 'src/foo2.c']) |
| 174 | |
| 175 | describes an extension that lives in the root package, while :: |
| 176 | |
| 177 | Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c']) |
| 178 | |
| 179 | describes the same extension in the :mod:`pkg` package. The source files and |
| 180 | resulting object code are identical in both cases; the only difference is where |
| 181 | in the filesystem (and therefore where in Python's namespace hierarchy) the |
| 182 | resulting extension lives. |
| 183 | |
| 184 | If you have a number of extensions all in the same package (or all under the |
| 185 | same base package), use the :option:`ext_package` keyword argument to |
| 186 | :func:`setup`. For example, :: |
| 187 | |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 188 | setup(..., |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 189 | ext_package='pkg', |
| 190 | ext_modules=[Extension('foo', ['foo.c']), |
| 191 | Extension('subpkg.bar', ['bar.c'])], |
| 192 | ) |
| 193 | |
| 194 | will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to |
| 195 | :mod:`pkg.subpkg.bar`. |
| 196 | |
| 197 | |
| 198 | Extension source files |
| 199 | ---------------------- |
| 200 | |
| 201 | The second argument to the :class:`Extension` constructor is a list of source |
| 202 | files. Since the Distutils currently only support C, C++, and Objective-C |
| 203 | extensions, these are normally C/C++/Objective-C source files. (Be sure to use |
| 204 | appropriate extensions to distinguish C++\ source files: :file:`.cc` and |
| 205 | :file:`.cpp` seem to be recognized by both Unix and Windows compilers.) |
| 206 | |
| 207 | However, you can also include SWIG interface (:file:`.i`) files in the list; the |
| 208 | :command:`build_ext` command knows how to deal with SWIG extensions: it will run |
| 209 | SWIG on the interface file and compile the resulting C/C++ file into your |
| 210 | extension. |
| 211 | |
| 212 | **\*\*** SWIG support is rough around the edges and largely untested! **\*\*** |
| 213 | |
| 214 | This warning notwithstanding, options to SWIG can be currently passed like |
| 215 | this:: |
| 216 | |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 217 | setup(..., |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 218 | ext_modules=[Extension('_foo', ['foo.i'], |
| 219 | swig_opts=['-modern', '-I../include'])], |
| 220 | py_modules=['foo'], |
| 221 | ) |
| 222 | |
| 223 | Or on the commandline like this:: |
| 224 | |
| 225 | > python setup.py build_ext --swig-opts="-modern -I../include" |
| 226 | |
| 227 | On some platforms, you can include non-source files that are processed by the |
| 228 | compiler and included in your extension. Currently, this just means Windows |
| 229 | message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for |
| 230 | Visual C++. These will be compiled to binary resource (:file:`.res`) files and |
| 231 | linked into the executable. |
| 232 | |
| 233 | |
| 234 | Preprocessor options |
| 235 | -------------------- |
| 236 | |
| 237 | Three optional arguments to :class:`Extension` will help if you need to specify |
| 238 | include directories to search or preprocessor macros to define/undefine: |
| 239 | ``include_dirs``, ``define_macros``, and ``undef_macros``. |
| 240 | |
| 241 | For example, if your extension requires header files in the :file:`include` |
| 242 | directory under your distribution root, use the ``include_dirs`` option:: |
| 243 | |
| 244 | Extension('foo', ['foo.c'], include_dirs=['include']) |
| 245 | |
| 246 | You can specify absolute directories there; if you know that your extension will |
| 247 | only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get |
| 248 | away with :: |
| 249 | |
| 250 | Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11']) |
| 251 | |
| 252 | You should avoid this sort of non-portable usage if you plan to distribute your |
| 253 | code: it's probably better to write C code like :: |
| 254 | |
| 255 | #include <X11/Xlib.h> |
| 256 | |
| 257 | If you need to include header files from some other Python extension, you can |
| 258 | take advantage of the fact that header files are installed in a consistent way |
| 259 | by the Distutils :command:`install_header` command. For example, the Numerical |
| 260 | Python header files are installed (on a standard Unix installation) to |
| 261 | :file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ |
| 262 | according to your platform and Python installation.) Since the Python include |
| 263 | directory---\ :file:`/usr/local/include/python1.5` in this case---is always |
| 264 | included in the search path when building Python extensions, the best approach |
| 265 | is to write C code like :: |
| 266 | |
| 267 | #include <Numerical/arrayobject.h> |
| 268 | |
| 269 | If you must put the :file:`Numerical` include directory right into your header |
| 270 | search path, though, you can find that directory using the Distutils |
| 271 | :mod:`distutils.sysconfig` module:: |
| 272 | |
| 273 | from distutils.sysconfig import get_python_inc |
| 274 | incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical') |
| 275 | setup(..., |
| 276 | Extension(..., include_dirs=[incdir]), |
| 277 | ) |
| 278 | |
| 279 | Even though this is quite portable---it will work on any Python installation, |
| 280 | regardless of platform---it's probably easier to just write your C code in the |
| 281 | sensible way. |
| 282 | |
| 283 | You can define and undefine pre-processor macros with the ``define_macros`` and |
| 284 | ``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)`` |
| 285 | tuples, where ``name`` is the name of the macro to define (a string) and |
| 286 | ``value`` is its value: either a string or ``None``. (Defining a macro ``FOO`` |
| 287 | to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with |
| 288 | most compilers, this sets ``FOO`` to the string ``1``.) ``undef_macros`` is |
| 289 | just a list of macros to undefine. |
| 290 | |
| 291 | For example:: |
| 292 | |
| 293 | Extension(..., |
| 294 | define_macros=[('NDEBUG', '1'), |
| 295 | ('HAVE_STRFTIME', None)], |
| 296 | undef_macros=['HAVE_FOO', 'HAVE_BAR']) |
| 297 | |
| 298 | is the equivalent of having this at the top of every C source file:: |
| 299 | |
| 300 | #define NDEBUG 1 |
| 301 | #define HAVE_STRFTIME |
| 302 | #undef HAVE_FOO |
| 303 | #undef HAVE_BAR |
| 304 | |
| 305 | |
| 306 | Library options |
| 307 | --------------- |
| 308 | |
| 309 | You can also specify the libraries to link against when building your extension, |
| 310 | and the directories to search for those libraries. The ``libraries`` option is |
| 311 | a list of libraries to link against, ``library_dirs`` is a list of directories |
| 312 | to search for libraries at link-time, and ``runtime_library_dirs`` is a list of |
| 313 | directories to search for shared (dynamically loaded) libraries at run-time. |
| 314 | |
| 315 | For example, if you need to link against libraries known to be in the standard |
| 316 | library search path on target systems :: |
| 317 | |
| 318 | Extension(..., |
Georg Brandl | 0a7ac7d | 2008-05-26 10:29:35 +0000 | [diff] [blame] | 319 | libraries=['_gdbm', 'readline']) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 320 | |
| 321 | If you need to link with libraries in a non-standard location, you'll have to |
| 322 | include the location in ``library_dirs``:: |
| 323 | |
| 324 | Extension(..., |
| 325 | library_dirs=['/usr/X11R6/lib'], |
| 326 | libraries=['X11', 'Xt']) |
| 327 | |
| 328 | (Again, this sort of non-portable construct should be avoided if you intend to |
| 329 | distribute your code.) |
| 330 | |
| 331 | **\*\*** Should mention clib libraries here or somewhere else! **\*\*** |
| 332 | |
| 333 | |
| 334 | Other options |
| 335 | ------------- |
| 336 | |
| 337 | There are still some other options which can be used to handle special cases. |
| 338 | |
| 339 | The :option:`extra_objects` option is a list of object files to be passed to the |
| 340 | linker. These files must not have extensions, as the default extension for the |
| 341 | compiler is used. |
| 342 | |
| 343 | :option:`extra_compile_args` and :option:`extra_link_args` can be used to |
| 344 | specify additional command line options for the respective compiler and linker |
| 345 | command lines. |
| 346 | |
| 347 | :option:`export_symbols` is only useful on Windows. It can contain a list of |
| 348 | symbols (functions or variables) to be exported. This option is not needed when |
| 349 | building compiled extensions: Distutils will automatically add ``initmodule`` |
| 350 | to the list of exported symbols. |
| 351 | |
| 352 | |
| 353 | Relationships between Distributions and Packages |
| 354 | ================================================ |
| 355 | |
| 356 | A distribution may relate to packages in three specific ways: |
| 357 | |
| 358 | #. It can require packages or modules. |
| 359 | |
| 360 | #. It can provide packages or modules. |
| 361 | |
| 362 | #. It can obsolete packages or modules. |
| 363 | |
| 364 | These relationships can be specified using keyword arguments to the |
| 365 | :func:`distutils.core.setup` function. |
| 366 | |
| 367 | Dependencies on other Python modules and packages can be specified by supplying |
| 368 | the *requires* keyword argument to :func:`setup`. The value must be a list of |
| 369 | strings. Each string specifies a package that is required, and optionally what |
| 370 | versions are sufficient. |
| 371 | |
| 372 | To specify that any version of a module or package is required, the string |
| 373 | should consist entirely of the module or package name. Examples include |
| 374 | ``'mymodule'`` and ``'xml.parsers.expat'``. |
| 375 | |
| 376 | If specific versions are required, a sequence of qualifiers can be supplied in |
| 377 | parentheses. Each qualifier may consist of a comparison operator and a version |
| 378 | number. The accepted comparison operators are:: |
| 379 | |
| 380 | < > == |
| 381 | <= >= != |
| 382 | |
| 383 | These can be combined by using multiple qualifiers separated by commas (and |
| 384 | optional whitespace). In this case, all of the qualifiers must be matched; a |
| 385 | logical AND is used to combine the evaluations. |
| 386 | |
| 387 | Let's look at a bunch of examples: |
| 388 | |
| 389 | +-------------------------+----------------------------------------------+ |
| 390 | | Requires Expression | Explanation | |
| 391 | +=========================+==============================================+ |
| 392 | | ``==1.0`` | Only version ``1.0`` is compatible | |
| 393 | +-------------------------+----------------------------------------------+ |
| 394 | | ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` | |
| 395 | | | is compatible, except ``1.5.1`` | |
| 396 | +-------------------------+----------------------------------------------+ |
| 397 | |
| 398 | Now that we can specify dependencies, we also need to be able to specify what we |
| 399 | provide that other distributions can require. This is done using the *provides* |
| 400 | keyword argument to :func:`setup`. The value for this keyword is a list of |
| 401 | strings, each of which names a Python module or package, and optionally |
| 402 | identifies the version. If the version is not specified, it is assumed to match |
| 403 | that of the distribution. |
| 404 | |
| 405 | Some examples: |
| 406 | |
| 407 | +---------------------+----------------------------------------------+ |
| 408 | | Provides Expression | Explanation | |
| 409 | +=====================+==============================================+ |
| 410 | | ``mypkg`` | Provide ``mypkg``, using the distribution | |
| 411 | | | version | |
| 412 | +---------------------+----------------------------------------------+ |
| 413 | | ``mypkg (1.1)`` | Provide ``mypkg`` version 1.1, regardless of | |
| 414 | | | the distribution version | |
| 415 | +---------------------+----------------------------------------------+ |
| 416 | |
| 417 | A package can declare that it obsoletes other packages using the *obsoletes* |
| 418 | keyword argument. The value for this is similar to that of the *requires* |
| 419 | keyword: a list of strings giving module or package specifiers. Each specifier |
| 420 | consists of a module or package name optionally followed by one or more version |
| 421 | qualifiers. Version qualifiers are given in parentheses after the module or |
| 422 | package name. |
| 423 | |
| 424 | The versions identified by the qualifiers are those that are obsoleted by the |
| 425 | distribution being described. If no qualifiers are given, all versions of the |
| 426 | named module or package are understood to be obsoleted. |
| 427 | |
| 428 | |
| 429 | Installing Scripts |
| 430 | ================== |
| 431 | |
| 432 | So far we have been dealing with pure and non-pure Python modules, which are |
| 433 | usually not run by themselves but imported by scripts. |
| 434 | |
| 435 | Scripts are files containing Python source code, intended to be started from the |
| 436 | command line. Scripts don't require Distutils to do anything very complicated. |
| 437 | The only clever feature is that if the first line of the script starts with |
| 438 | ``#!`` and contains the word "python", the Distutils will adjust the first line |
| 439 | to refer to the current interpreter location. By default, it is replaced with |
| 440 | the current interpreter location. The :option:`--executable` (or :option:`-e`) |
| 441 | option will allow the interpreter path to be explicitly overridden. |
| 442 | |
| 443 | The :option:`scripts` option simply is a list of files to be handled in this |
| 444 | way. From the PyXML setup script:: |
| 445 | |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 446 | setup(..., |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 447 | scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] |
| 448 | ) |
| 449 | |
| 450 | |
| 451 | Installing Package Data |
| 452 | ======================= |
| 453 | |
| 454 | Often, additional files need to be installed into a package. These files are |
| 455 | often data that's closely related to the package's implementation, or text files |
| 456 | containing documentation that might be of interest to programmers using the |
| 457 | package. These files are called :dfn:`package data`. |
| 458 | |
| 459 | Package data can be added to packages using the ``package_data`` keyword |
| 460 | argument to the :func:`setup` function. The value must be a mapping from |
| 461 | package name to a list of relative path names that should be copied into the |
| 462 | package. The paths are interpreted as relative to the directory containing the |
| 463 | package (information from the ``package_dir`` mapping is used if appropriate); |
| 464 | that is, the files are expected to be part of the package in the source |
| 465 | directories. They may contain glob patterns as well. |
| 466 | |
| 467 | The path names may contain directory portions; any necessary directories will be |
| 468 | created in the installation. |
| 469 | |
| 470 | For example, if a package should contain a subdirectory with several data files, |
| 471 | the files can be arranged like this in the source tree:: |
| 472 | |
| 473 | setup.py |
| 474 | src/ |
| 475 | mypkg/ |
| 476 | __init__.py |
| 477 | module.py |
| 478 | data/ |
| 479 | tables.dat |
| 480 | spoons.dat |
| 481 | forks.dat |
| 482 | |
| 483 | The corresponding call to :func:`setup` might be:: |
| 484 | |
| 485 | setup(..., |
| 486 | packages=['mypkg'], |
| 487 | package_dir={'mypkg': 'src/mypkg'}, |
| 488 | package_data={'mypkg': ['data/*.dat']}, |
| 489 | ) |
| 490 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 491 | |
| 492 | Installing Additional Files |
| 493 | =========================== |
| 494 | |
| 495 | The :option:`data_files` option can be used to specify additional files needed |
| 496 | by the module distribution: configuration files, message catalogs, data files, |
| 497 | anything which doesn't fit in the previous categories. |
| 498 | |
| 499 | :option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the |
| 500 | following way:: |
| 501 | |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 502 | setup(..., |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 503 | data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), |
| 504 | ('config', ['cfg/data.cfg']), |
| 505 | ('/etc/init.d', ['init-script'])] |
| 506 | ) |
| 507 | |
| 508 | Note that you can specify the directory names where the data files will be |
| 509 | installed, but you cannot rename the data files themselves. |
| 510 | |
| 511 | Each (*directory*, *files*) pair in the sequence specifies the installation |
| 512 | directory and the files to install there. If *directory* is a relative path, it |
| 513 | is interpreted relative to the installation prefix (Python's ``sys.prefix`` for |
| 514 | pure-Python packages, ``sys.exec_prefix`` for packages that contain extension |
| 515 | modules). Each file name in *files* is interpreted relative to the |
| 516 | :file:`setup.py` script at the top of the package source distribution. No |
| 517 | directory information from *files* is used to determine the final location of |
| 518 | the installed file; only the name of the file is used. |
| 519 | |
| 520 | You can specify the :option:`data_files` options as a simple sequence of files |
| 521 | without specifying a target directory, but this is not recommended, and the |
| 522 | :command:`install` command will print a warning in this case. To install data |
| 523 | files directly in the target directory, an empty string should be given as the |
| 524 | directory. |
| 525 | |
| 526 | |
| 527 | .. _meta-data: |
| 528 | |
| 529 | Additional meta-data |
| 530 | ==================== |
| 531 | |
| 532 | The setup script may include additional meta-data beyond the name and version. |
| 533 | This information includes: |
| 534 | |
| 535 | +----------------------+---------------------------+-----------------+--------+ |
| 536 | | Meta-Data | Description | Value | Notes | |
| 537 | +======================+===========================+=================+========+ |
| 538 | | ``name`` | name of the package | short string | \(1) | |
| 539 | +----------------------+---------------------------+-----------------+--------+ |
| 540 | | ``version`` | version of this release | short string | (1)(2) | |
| 541 | +----------------------+---------------------------+-----------------+--------+ |
| 542 | | ``author`` | package author's name | short string | \(3) | |
| 543 | +----------------------+---------------------------+-----------------+--------+ |
| 544 | | ``author_email`` | email address of the | email address | \(3) | |
| 545 | | | package author | | | |
| 546 | +----------------------+---------------------------+-----------------+--------+ |
| 547 | | ``maintainer`` | package maintainer's name | short string | \(3) | |
| 548 | +----------------------+---------------------------+-----------------+--------+ |
| 549 | | ``maintainer_email`` | email address of the | email address | \(3) | |
| 550 | | | package maintainer | | | |
| 551 | +----------------------+---------------------------+-----------------+--------+ |
| 552 | | ``url`` | home page for the package | URL | \(1) | |
| 553 | +----------------------+---------------------------+-----------------+--------+ |
| 554 | | ``description`` | short, summary | short string | | |
| 555 | | | description of the | | | |
| 556 | | | package | | | |
| 557 | +----------------------+---------------------------+-----------------+--------+ |
| 558 | | ``long_description`` | longer description of the | long string | | |
| 559 | | | package | | | |
| 560 | +----------------------+---------------------------+-----------------+--------+ |
| 561 | | ``download_url`` | location where the | URL | \(4) | |
| 562 | | | package may be downloaded | | | |
| 563 | +----------------------+---------------------------+-----------------+--------+ |
| 564 | | ``classifiers`` | a list of classifiers | list of strings | \(4) | |
| 565 | +----------------------+---------------------------+-----------------+--------+ |
| 566 | |
| 567 | Notes: |
| 568 | |
| 569 | (1) |
| 570 | These fields are required. |
| 571 | |
| 572 | (2) |
| 573 | It is recommended that versions take the form *major.minor[.patch[.sub]]*. |
| 574 | |
| 575 | (3) |
| 576 | Either the author or the maintainer must be identified. |
| 577 | |
| 578 | (4) |
| 579 | These fields should not be used if your package is to be compatible with Python |
| 580 | versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 581 | <http://pypi.python.org/pypi>`_. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 582 | |
| 583 | 'short string' |
| 584 | A single line of text, not more than 200 characters. |
| 585 | |
| 586 | 'long string' |
| 587 | Multiple lines of plain text in reStructuredText format (see |
| 588 | http://docutils.sf.net/). |
| 589 | |
| 590 | 'list of strings' |
| 591 | See below. |
| 592 | |
| 593 | None of the string values may be Unicode. |
| 594 | |
| 595 | Encoding the version information is an art in itself. Python packages generally |
| 596 | adhere to the version format *major.minor[.patch][sub]*. The major number is 0 |
| 597 | for initial, experimental releases of software. It is incremented for releases |
| 598 | that represent major milestones in a package. The minor number is incremented |
| 599 | when important new features are added to the package. The patch number |
| 600 | increments when bug-fix releases are made. Additional trailing version |
| 601 | information is sometimes used to indicate sub-releases. These are |
| 602 | "a1,a2,...,aN" (for alpha releases, where functionality and API may change), |
| 603 | "b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN" |
| 604 | (for final pre-release release testing). Some examples: |
| 605 | |
| 606 | 0.1.0 |
| 607 | the first, experimental release of a package |
| 608 | |
| 609 | 1.0.1a2 |
| 610 | the second alpha release of the first patch version of 1.0 |
| 611 | |
| 612 | :option:`classifiers` are specified in a python list:: |
| 613 | |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 614 | setup(..., |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 615 | classifiers=[ |
| 616 | 'Development Status :: 4 - Beta', |
| 617 | 'Environment :: Console', |
| 618 | 'Environment :: Web Environment', |
| 619 | 'Intended Audience :: End Users/Desktop', |
| 620 | 'Intended Audience :: Developers', |
| 621 | 'Intended Audience :: System Administrators', |
| 622 | 'License :: OSI Approved :: Python Software Foundation License', |
| 623 | 'Operating System :: MacOS :: MacOS X', |
| 624 | 'Operating System :: Microsoft :: Windows', |
| 625 | 'Operating System :: POSIX', |
| 626 | 'Programming Language :: Python', |
| 627 | 'Topic :: Communications :: Email', |
| 628 | 'Topic :: Office/Business', |
| 629 | 'Topic :: Software Development :: Bug Tracking', |
| 630 | ], |
| 631 | ) |
| 632 | |
| 633 | If you wish to include classifiers in your :file:`setup.py` file and also wish |
| 634 | to remain backwards-compatible with Python releases prior to 2.2.3, then you can |
| 635 | include the following code fragment in your :file:`setup.py` before the |
| 636 | :func:`setup` call. :: |
| 637 | |
| 638 | # patch distutils if it can't cope with the "classifiers" or |
| 639 | # "download_url" keywords |
| 640 | from sys import version |
| 641 | if version < '2.2.3': |
| 642 | from distutils.dist import DistributionMetadata |
| 643 | DistributionMetadata.classifiers = None |
| 644 | DistributionMetadata.download_url = None |
| 645 | |
| 646 | |
| 647 | Debugging the setup script |
| 648 | ========================== |
| 649 | |
| 650 | Sometimes things go wrong, and the setup script doesn't do what the developer |
| 651 | wants. |
| 652 | |
| 653 | Distutils catches any exceptions when running the setup script, and print a |
| 654 | simple error message before the script is terminated. The motivation for this |
| 655 | behaviour is to not confuse administrators who don't know much about Python and |
| 656 | are trying to install a package. If they get a big long traceback from deep |
| 657 | inside the guts of Distutils, they may think the package or the Python |
| 658 | installation is broken because they don't read all the way down to the bottom |
| 659 | and see that it's a permission problem. |
| 660 | |
| 661 | On the other hand, this doesn't help the developer to find the cause of the |
| 662 | failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set |
| 663 | to anything except an empty string, and distutils will now print detailed |
| 664 | information what it is doing, and prints the full traceback in case an exception |
| 665 | occurs. |
| 666 | |
| 667 | |