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