← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/distutils/configfile.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

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