/Doc/distutils/setupscript.rst

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