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