|
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 |