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
17script---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.. code-block:: ini
42
43   [command]
44   option=value
45   ...
46
47where *command* is one of the Distutils commands (e.g. :command:`build_py`,
48:command:`install`), and *option* is one of the options that command supports.
49Any number of options can be supplied for each command, and any number of
50command sections can be included in the file.  Blank lines are ignored, as are
51comments, which run from a ``'#'`` character until the end of the line.  Long
52option values can be split across multiple lines simply by indenting the
53continuation lines.
54
55You can find out the list of options supported by a particular command with the
56universal :option:`!--help` option, e.g.
57
58.. code-block:: shell-session
59
60   $ python setup.py --help build_ext
61   [...]
62   Options for 'build_ext' command:
63     --build-lib (-b)     directory for compiled extension modules
64     --build-temp (-t)    directory for temporary files (build by-products)
65     --inplace (-i)       ignore build-lib and put compiled extensions into the
66                          source directory alongside your pure Python modules
67     --include-dirs (-I)  list of directories to search for header files
68     --define (-D)        C preprocessor macros to define
69     --undef (-U)         C preprocessor macros to undefine
70     --swig-opts          list of SWIG command line options
71   [...]
72
73Note that an option spelled :option:`!--foo-bar` on the command-line  is spelled
74``foo_bar`` in configuration files.
75
76.. _distutils-build-ext-inplace:
77
78For example, say you want your extensions to be built "in-place"---that is, you
79have an extension :mod:`pkg.ext`, and you want the compiled extension file
80(:file:`ext.so` on Unix, say) to be put in the same source directory as your
81pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`.  You can always use the
82:option:`!--inplace` option on the command-line to ensure this:
83
84.. code-block:: sh
85
86   python setup.py build_ext --inplace
87
88But this requires that you always specify the :command:`build_ext` command
89explicitly, and remember to provide :option:`!--inplace`. An easier way is to
90"set and forget" this option, by encoding it in :file:`setup.cfg`, the
91configuration file for this distribution:
92
93.. code-block:: ini
94
95   [build_ext]
96   inplace=1
97
98This will affect all builds of this module distribution, whether or not you
99explicitly specify :command:`build_ext`.  If you include :file:`setup.cfg` in
100your source distribution, it will also affect end-user builds---which is
101probably a bad idea for this option, since always building extensions in-place
102would break installation of the module distribution.  In certain peculiar cases,
103though, modules are built right in their installation directory, so this is
104conceivably a useful ability.  (Distributing extensions that expect to be built
105in their installation directory is almost always a bad idea, though.)
106
107Another example: certain commands take a lot of options that don't change from
108run to run; for example, :command:`bdist_rpm` needs to know everything required
109to generate a "spec" file for creating an RPM distribution.  Some of this
110information comes from the setup script, and some is automatically generated by
111the Distutils (such as the list of files installed).  But some of it has to be
112supplied as options to :command:`bdist_rpm`, which would be very tedious to do
113on the command-line for every run.  Hence, here is a snippet from the Distutils'
114own :file:`setup.cfg`:
115
116.. code-block:: ini
117
118   [bdist_rpm]
119   release = 1
120   packager = Greg Ward <gward@python.net>
121   doc_files = CHANGES.txt
122               README.txt
123               USAGE.txt
124               doc/
125               examples/
126
127Note that the ``doc_files`` option is simply a whitespace-separated string
128split across multiple lines for readability.
129
130
131.. seealso::
132
133   :ref:`inst-config-syntax` in "Installing Python Modules"
134      More information on the configuration files is available in the manual for
135      system administrators.
136
137
138.. rubric:: Footnotes
139
140.. [#] This ideal probably won't be achieved until auto-configuration is fully
141   supported by the Distutils.
142
143