Doc/distutils/configfile.rst

   1 .. _setup-config:
   2
   3 ************************************
   4 Writing the Setup Configuration File
   5 ************************************
   6
   7 Often, it's not possible to write down everything needed to build a distribution
   8 *a priori*: you may need to get some information from the user, or from the
   9 user's system, in order to proceed.  As long as that information is fairly
  10 simple---a list of directories to search for C header files or libraries, for
  11 example---then providing a configuration file, :file:`setup.cfg`, for users to
  12 edit is a cheap and easy way to solicit it.  Configuration files also let you
  13 provide default values for any command option, which the installer can then
  14 override either on the command-line or by editing the config file.
  15
  16 The setup configuration file is a useful middle-ground between the setup script
  17 ---which, ideally, would be opaque to installers [#]_---and the command-line to
  18 the setup script, which is outside of your control and entirely up to the
  19 installer.  In fact, :file:`setup.cfg` (and any other Distutils configuration
  20 files present on the target system) are processed after the contents of the
  21 setup script, but before the command-line.  This has  several useful
  22 consequences:
  23
  24 .. % (If you have more advanced needs, such as determining which extensions
  25 .. % to build based on what capabilities are present on the target system,
  26 .. % then you need the Distutils ``auto-configuration'' facility.  This
  27 .. % started to appear in Distutils 0.9 but, as of this writing, isn't mature
  28 .. % or stable enough yet for real-world use.)
  29
  30 * installers can override some of what you put in :file:`setup.py` by editing
  31   :file:`setup.cfg`
  32
  33 * you can provide non-standard defaults for options that are not easily set in
  34   :file:`setup.py`
  35
  36 * installers can override anything in :file:`setup.cfg` using the command-line
  37   options to :file:`setup.py`
  38
  39 The basic syntax of the configuration file is simple::
  40
  41    [command]
  42    option=value
  43    ...
  44
  45 where *command* is one of the Distutils commands (e.g. :command:`build_py`,
  46 :command:`install`), and *option* is one of the options that command supports.
  47 Any number of options can be supplied for each command, and any number of
  48 command sections can be included in the file.  Blank lines are ignored, as are
  49 comments, which run from a ``'#'`` character until the end of the line.  Long
  50 option values can be split across multiple lines simply by indenting the
  51 continuation lines.
  52
  53 You can find out the list of options supported by a particular command with the
  54 universal :option:`--help` option, e.g. ::
  55
  56    > python setup.py --help build_ext
  57    [...]
  58    Options for 'build_ext' command:
  59      --build-lib (-b)     directory for compiled extension modules
  60      --build-temp (-t)    directory for temporary files (build by-products)
  61      --inplace (-i)       ignore build-lib and put compiled extensions into the
  62                           source directory alongside your pure Python modules
  63      --include-dirs (-I)  list of directories to search for header files
  64      --define (-D)        C preprocessor macros to define
  65      --undef (-U)         C preprocessor macros to undefine
  66      --swig-opts          list of SWIG command line options
  67    [...]
  68
  69 Note that an option spelled :option:`--foo-bar` on the command-line  is spelled
  70 :option:`foo_bar` in configuration files.
  71
  72 For example, say you want your extensions to be built "in-place"---that is, you
  73 have an extension :mod:`pkg.ext`, and you want the compiled extension file
  74 (:file:`ext.so` on Unix, say) to be put in the same source directory as your
  75 pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`.  You can always use the
  76 :option:`--inplace` option on the command-line to ensure this::
  77
  78    python setup.py build_ext --inplace
  79
  80 But this requires that you always specify the :command:`build_ext` command
  81 explicitly, and remember to provide :option:`--inplace`. An easier way is to
  82 "set and forget" this option, by encoding it in :file:`setup.cfg`, the
  83 configuration file for this distribution::
  84
  85    [build_ext]
  86    inplace=1
  87
  88 This will affect all builds of this module distribution, whether or not you
  89 explicitly specify :command:`build_ext`.  If you include :file:`setup.cfg` in
  90 your source distribution, it will also affect end-user builds---which is
  91 probably a bad idea for this option, since always building extensions in-place
  92 would break installation of the module distribution.  In certain peculiar cases,
  93 though, modules are built right in their installation directory, so this is
  94 conceivably a useful ability.  (Distributing extensions that expect to be built
  95 in their installation directory is almost always a bad idea, though.)
  96
  97 Another example: certain commands take a lot of options that don't change from
  98 run to run; for example, :command:`bdist_rpm` needs to know everything required
  99 to generate a "spec" file for creating an RPM distribution.  Some of this
 100 information comes from the setup script, and some is automatically generated by
 101 the Distutils (such as the list of files installed).  But some of it has to be
 102 supplied as options to :command:`bdist_rpm`, which would be very tedious to do
 103 on the command-line for every run.  Hence, here is a snippet from the Distutils'
 104 own :file:`setup.cfg`::
 105
 106    [bdist_rpm]
 107    release = 1
 108    packager = Greg Ward <gward@python.net>
 109    doc_files = CHANGES.txt
 110                README.txt
 111                USAGE.txt
 112                doc/
 113                examples/
 114
 115 Note that the :option:`doc_files` option is simply a whitespace-separated string
 116 split across multiple lines for readability.
 117
 118
 119 .. seealso::
 120
 121    :ref:`inst-config-syntax` in "Installing Python Modules"
 122       More information on the configuration files is available in the manual for
 123       system administrators.
 124
 125
 126 .. rubric:: Footnotes
 127
 128 .. [#] This ideal probably won't be achieved until auto-configuration is fully
 129    supported by the Distutils.
 130