/Doc/distutils/configfile.rst

  1.. _setup-config:
  2
  3************************************
  4Writing the Setup Configuration File
  5************************************
  6
  7Often, 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
  9user's system, in order to proceed.  As long as that information is fairly
 10simple---a list of directories to search for C header files or libraries, for
 11example---then providing a configuration file, :file:`setup.cfg`, for users to
 12edit is a cheap and easy way to solicit it.  Configuration files also let you
 13provide default values for any command option, which the installer can then
 14override either on the command-line or by editing the config file.
 15
 16The 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
 18the setup script, which is outside of your control and entirely up to the
 19installer.  In fact, :file:`setup.cfg` (and any other Distutils configuration
 20files present on the target system) are processed after the contents of the
 21setup script, but before the command-line.  This has  several useful
 22consequences:
 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
 39The basic syntax of the configuration file is simple::
 40
 41   [command]
 42   option=value
 43   ...
 44
 45where *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.
 47Any number of options can be supplied for each command, and any number of
 48command sections can be included in the file.  Blank lines are ignored, as are
 49comments, which run from a ``'#'`` character until the end of the line.  Long
 50option values can be split across multiple lines simply by indenting the
 51continuation lines.
 52
 53You can find out the list of options supported by a particular command with the
 54universal :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
 69Note that an option spelled :option:`--foo-bar` on the command-line  is spelled
 70:option:`foo_bar` in configuration files.
 71
 72For example, say you want your extensions to be built "in-place"---that is, you
 73have 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
 75pure 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
 80But this requires that you always specify the :command:`build_ext` command
 81explicitly, 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
 83configuration file for this distribution::
 84
 85   [build_ext]
 86   inplace=1
 87
 88This will affect all builds of this module distribution, whether or not you
 89explicitly specify :command:`build_ext`.  If you include :file:`setup.cfg` in
 90your source distribution, it will also affect end-user builds---which is
 91probably a bad idea for this option, since always building extensions in-place
 92would break installation of the module distribution.  In certain peculiar cases,
 93though, modules are built right in their installation directory, so this is
 94conceivably a useful ability.  (Distributing extensions that expect to be built
 95in their installation directory is almost always a bad idea, though.)
 96
 97Another example: certain commands take a lot of options that don't change from
 98run to run; for example, :command:`bdist_rpm` needs to know everything required
 99to generate a "spec" file for creating an RPM distribution.  Some of this
100information comes from the setup script, and some is automatically generated by
101the Distutils (such as the list of files installed).  But some of it has to be
102supplied as options to :command:`bdist_rpm`, which would be very tedious to do
103on the command-line for every run.  Hence, here is a snippet from the Distutils'
104own :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
115Note that the :option:`doc_files` option is simply a whitespace-separated string
116split 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