3. Writing the Setup Configuration File¶

Often, it’s not possible to write down everything needed to build a distributiona priori: you may need to get some information from the user, or from theuser’s system, in order to proceed. As long as that information is fairlysimple—a list of directories to search for C header files or libraries, forexample—then providing a configuration file,setup.cfg, for users toedit is a cheap and easy way to solicit it. Configuration files also let youprovide default values for any command option, which the installer can thenoverride either on the command-line or by editing the config file.

The setup configuration file is a useful middle-ground between the setup script—which, ideally, would be opaque to installers[1]—and the command-line tothe setup script, which is outside of your control and entirely up to theinstaller. In fact,setup.cfg (and any other Distutils configurationfiles present on the target system) are processed after the contents of thesetup script, but before the command-line. This has several usefulconsequences:

• installers can override some of what you put insetup.py by editingsetup.cfg
• you can provide non-standard defaults for options that are not easily set insetup.py
• installers can override anything insetup.cfg using the command-lineoptions tosetup.py

The basic syntax of the configuration file is simple:

[command]option=value...

wherecommand is one of the Distutils commands (e.g.build_py,install), andoption is one of the options that command supports.Any number of options can be supplied for each command, and any number ofcommand sections can be included in the file. Blank lines are ignored, as arecomments, which run from a'#' character until the end of the line. Longoption values can be split across multiple lines simply by indenting thecontinuation lines.

You can find out the list of options supported by a particular command with theuniversal--help option, e.g.

>pythonsetup.py--helpbuild_ext[...]Optionsfor'build_ext'command:--build-lib(-b)directoryforcompiledextensionmodules--build-temp(-t)directoryfortemporaryfiles(buildby-products)--inplace(-i)ignorebuild-libandputcompiledextensionsintothesourcedirectoryalongsideyourpurePythonmodules--include-dirs(-I)listofdirectoriestosearchforheaderfiles--define(-D)Cpreprocessormacrostodefine--undef(-U)Cpreprocessormacrostoundefine--swig-optslistofSWIGcommandlineoptions[...]

Note that an option spelled--foo-bar on the command-line is spelledfoo_bar in configuration files.

For example, say you want your extensions to be built “in-place”—that is, youhave an extensionpkg.ext, and you want the compiled extension file(ext.so on Unix, say) to be put in the same source directory as yourpure Python modulespkg.mod1 andpkg.mod2. You can always use the--inplace option on the command-line to ensure this:

pythonsetup.pybuild_ext--inplace

But this requires that you always specify thebuild_ext commandexplicitly, and remember to provide--inplace. An easier way is to“set and forget” this option, by encoding it insetup.cfg, theconfiguration file for this distribution:

[build_ext]inplace=1

This will affect all builds of this module distribution, whether or not youexplicitly specifybuild_ext. If you includesetup.cfg inyour source distribution, it will also affect end-user builds—which isprobably a bad idea for this option, since always building extensions in-placewould break installation of the module distribution. In certain peculiar cases,though, modules are built right in their installation directory, so this isconceivably a useful ability. (Distributing extensions that expect to be builtin their installation directory is almost always a bad idea, though.)

Another example: certain commands take a lot of options that don’t change fromrun to run; for example,bdist_rpm needs to know everything requiredto generate a “spec” file for creating an RPM distribution. Some of thisinformation comes from the setup script, and some is automatically generated bythe Distutils (such as the list of files installed). But some of it has to besupplied as options tobdist_rpm, which would be very tedious to doon the command-line for every run. Hence, here is a snippet from the Distutils’ownsetup.cfg:

[bdist_rpm]release=1packager=GregWard<gward@python.net>doc_files=CHANGES.txtREADME.txtUSAGE.txtdoc/examples/

Note that thedoc_files option is simply a whitespace-separated stringsplit across multiple lines for readability.

Footnotes