/Doc/distutils/configfile.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 130 lines · 102 code · 28 blank · 0 comment · 0 complexity · f22ab5ba2ea8442c311f31c67665d6ee MD5 · raw file
- .. _setup-config:
- ************************************
- Writing the Setup Configuration File
- ************************************
- Often, it's not possible to write down everything needed to build a distribution
- *a priori*: you may need to get some information from the user, or from the
- user's system, in order to proceed. As long as that information is fairly
- simple---a list of directories to search for C header files or libraries, for
- example---then providing a configuration file, :file:`setup.cfg`, for users to
- edit is a cheap and easy way to solicit it. Configuration files also let you
- provide default values for any command option, which the installer can then
- override 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 [#]_---and the command-line to
- the setup script, which is outside of your control and entirely up to the
- installer. In fact, :file:`setup.cfg` (and any other Distutils configuration
- files present on the target system) are processed after the contents of the
- setup script, but before the command-line. This has several useful
- consequences:
- .. % (If you have more advanced needs, such as determining which extensions
- .. % to build based on what capabilities are present on the target system,
- .. % then you need the Distutils ``auto-configuration'' facility. This
- .. % started to appear in Distutils 0.9 but, as of this writing, isn't mature
- .. % or stable enough yet for real-world use.)
- * installers can override some of what you put in :file:`setup.py` by editing
- :file:`setup.cfg`
- * you can provide non-standard defaults for options that are not easily set in
- :file:`setup.py`
- * installers can override anything in :file:`setup.cfg` using the command-line
- options to :file:`setup.py`
- The basic syntax of the configuration file is simple::
- [command]
- option=value
- ...
- where *command* is one of the Distutils commands (e.g. :command:`build_py`,
- :command:`install`), and *option* is one of the options that command supports.
- Any number of options can be supplied for each command, and any number of
- command sections can be included in the file. Blank lines are ignored, as are
- comments, which run from a ``'#'`` character until the end of the line. Long
- option values can be split across multiple lines simply by indenting the
- continuation lines.
- You can find out the list of options supported by a particular command with the
- universal :option:`--help` option, e.g. ::
- > python setup.py --help build_ext
- [...]
- Options for 'build_ext' command:
- --build-lib (-b) directory for compiled extension modules
- --build-temp (-t) directory for temporary files (build by-products)
- --inplace (-i) ignore build-lib and put compiled extensions into the
- source directory alongside your pure Python modules
- --include-dirs (-I) list of directories to search for header files
- --define (-D) C preprocessor macros to define
- --undef (-U) C preprocessor macros to undefine
- --swig-opts list of SWIG command line options
- [...]
- Note that an option spelled :option:`--foo-bar` on the command-line is spelled
- :option:`foo_bar` in configuration files.
- For example, say you want your extensions to be built "in-place"---that is, you
- have an extension :mod:`pkg.ext`, and you want the compiled extension file
- (:file:`ext.so` on Unix, say) to be put in the same source directory as your
- pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`. You can always use the
- :option:`--inplace` option on the command-line to ensure this::
- python setup.py build_ext --inplace
- But this requires that you always specify the :command:`build_ext` command
- explicitly, and remember to provide :option:`--inplace`. An easier way is to
- "set and forget" this option, by encoding it in :file:`setup.cfg`, the
- configuration file for this distribution::
- [build_ext]
- inplace=1
- This will affect all builds of this module distribution, whether or not you
- explicitly specify :command:`build_ext`. If you include :file:`setup.cfg` in
- your source distribution, it will also affect end-user builds---which is
- probably a bad idea for this option, since always building extensions in-place
- would break installation of the module distribution. In certain peculiar cases,
- though, modules are built right in their installation directory, so this is
- conceivably a useful ability. (Distributing extensions that expect to be built
- in their installation directory is almost always a bad idea, though.)
- Another example: certain commands take a lot of options that don't change from
- run to run; for example, :command:`bdist_rpm` needs to know everything required
- to generate a "spec" file for creating an RPM distribution. Some of this
- information comes from the setup script, and some is automatically generated by
- the Distutils (such as the list of files installed). But some of it has to be
- supplied as options to :command:`bdist_rpm`, which would be very tedious to do
- on the command-line for every run. Hence, here is a snippet from the Distutils'
- own :file:`setup.cfg`::
- [bdist_rpm]
- release = 1
- packager = Greg Ward <gward@python.net>
- doc_files = CHANGES.txt
- README.txt
- USAGE.txt
- doc/
- examples/
- Note that the :option:`doc_files` option is simply a whitespace-separated string
- split across multiple lines for readability.
- .. seealso::
- :ref:`inst-config-syntax` in "Installing Python Modules"
- More information on the configuration files is available in the manual for
- system administrators.
- .. rubric:: Footnotes
- .. [#] This ideal probably won't be achieved until auto-configuration is fully
- supported by the Distutils.