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 ``foo_bar`` in configuration files. 71 72 .. _distutils-build-ext-inplace: 73 74 For example, say you want your extensions to be built "in-place"---that is, you 75 have an extension :mod:`pkg.ext`, and you want the compiled extension file 76 (:file:`ext.so` on Unix, say) to be put in the same source directory as your 77 pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`. You can always use the 78 :option:`!--inplace` option on the command-line to ensure this:: 79 80 python setup.py build_ext --inplace 81 82 But this requires that you always specify the :command:`build_ext` command 83 explicitly, and remember to provide :option:`!--inplace`. An easier way is to 84 "set and forget" this option, by encoding it in :file:`setup.cfg`, the 85 configuration file for this distribution:: 86 87 [build_ext] 88 inplace=1 89 90 This will affect all builds of this module distribution, whether or not you 91 explicitly specify :command:`build_ext`. If you include :file:`setup.cfg` in 92 your source distribution, it will also affect end-user builds---which is 93 probably a bad idea for this option, since always building extensions in-place 94 would break installation of the module distribution. In certain peculiar cases, 95 though, modules are built right in their installation directory, so this is 96 conceivably a useful ability. (Distributing extensions that expect to be built 97 in their installation directory is almost always a bad idea, though.) 98 99 Another example: certain commands take a lot of options that don't change from 100 run to run; for example, :command:`bdist_rpm` needs to know everything required 101 to generate a "spec" file for creating an RPM distribution. Some of this 102 information comes from the setup script, and some is automatically generated by 103 the Distutils (such as the list of files installed). But some of it has to be 104 supplied as options to :command:`bdist_rpm`, which would be very tedious to do 105 on the command-line for every run. Hence, here is a snippet from the Distutils' 106 own :file:`setup.cfg`:: 107 108 [bdist_rpm] 109 release = 1 110 packager = Greg Ward <gward (a] python.net> 111 doc_files = CHANGES.txt 112 README.txt 113 USAGE.txt 114 doc/ 115 examples/ 116 117 Note that the ``doc_files`` option is simply a whitespace-separated string 118 split across multiple lines for readability. 119 120 121 .. seealso:: 122 123 :ref:`inst-config-syntax` in "Installing Python Modules" 124 More information on the configuration files is available in the manual for 125 system administrators. 126 127 128 .. rubric:: Footnotes 129 130 .. [#] This ideal probably won't be achieved until auto-configuration is fully 131 supported by the Distutils. 132 133
