| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="dist.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="dist.html" title='Distributing Python Modules' /> |
| 8 | <link rel='index' href='genindex.html' title='Index' /> |
| 9 | <link rel='last' href='about.html' title='About this document...' /> |
| 10 | <link rel='help' href='about.html' title='About this document...' /> |
| 11 | <link rel="next" href="source-dist.html" /> |
| 12 | <link rel="prev" href="setup-script.html" /> |
| 13 | <link rel="parent" href="dist.html" /> |
| 14 | <link rel="next" href="source-dist.html" /> |
| 15 | <meta name='aesop' content='information' /> |
| 16 | <title>3. Writing the Setup Configuration File</title> |
| 17 | </head> |
| 18 | <body> |
| 19 | <DIV CLASS="navigation"> |
| 20 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 21 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 22 | <tr> |
| 23 | <td class='online-navigation'><a rel="prev" title="2.8 Debugging the setup" |
| 24 | href="node14.html"><img src='../icons/previous.png' |
| 25 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 26 | <td class='online-navigation'><a rel="parent" title="Distributing Python Modules" |
| 27 | href="dist.html"><img src='../icons/up.png' |
| 28 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 29 | <td class='online-navigation'><a rel="next" title="4. Creating a Source" |
| 30 | href="source-dist.html"><img src='../icons/next.png' |
| 31 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 32 | <td align="center" width="100%">Distributing Python Modules</td> |
| 33 | <td class='online-navigation'><img src='../icons/blank.png' |
| 34 | border='0' height='32' alt='' width='32' /></td> |
| 35 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 36 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 37 | <td class='online-navigation'><a rel="index" title="Index" |
| 38 | href="genindex.html"><img src='../icons/index.png' |
| 39 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 40 | </tr></table> |
| 41 | <div class='online-navigation'> |
| 42 | <b class="navlabel">Previous:</b> |
| 43 | <a class="sectref" rel="prev" href="node14.html">2.8 Debugging the setup</A> |
| 44 | <b class="navlabel">Up:</b> |
| 45 | <a class="sectref" rel="parent" href="dist.html">Distributing Python Modules</A> |
| 46 | <b class="navlabel">Next:</b> |
| 47 | <a class="sectref" rel="next" href="source-dist.html">4. Creating a Source</A> |
| 48 | </div> |
| 49 | <hr /></div> |
| 50 | </DIV> |
| 51 | <!--End of Navigation Panel--> |
| 52 | |
| 53 | <H1><A NAME="SECTION003000000000000000000"></A> |
| 54 | <A NAME="setup-config"></A> |
| 55 | <BR> |
| 56 | 3. Writing the Setup Configuration File |
| 57 | </H1> |
| 58 | |
| 59 | <P> |
| 60 | Often, it's not possible to write down everything needed to build a |
| 61 | distribution <em>a priori</em>: you may need to get some information from |
| 62 | the user, or from the user's system, in order to proceed. As long as |
| 63 | that information is fairly simple--a list of directories to search for |
| 64 | C header files or libraries, for example--then providing a |
| 65 | configuration file, <span class="file">setup.cfg</span>, for users to edit is a cheap and |
| 66 | easy way to solicit it. Configuration files also let you provide |
| 67 | default values for any command option, which the installer can then |
| 68 | override either on the command-line or by editing the config file. |
| 69 | |
| 70 | <P> |
| 71 | The setup configuration file is a useful middle-ground between the setup |
| 72 | script--which, ideally, would be opaque to installers<A NAME="tex2html1" |
| 73 | HREF="#foot393"><SUP>3.1</SUP></A>--and the command-line to the setup |
| 74 | script, which is outside of your control and entirely up to the |
| 75 | installer. In fact, <span class="file">setup.cfg</span> (and any other Distutils |
| 76 | configuration files present on the target system) are processed after |
| 77 | the contents of the setup script, but before the command-line. This has |
| 78 | several useful consequences: |
| 79 | |
| 80 | <UL> |
| 81 | <LI>installers can override some of what you put in <span class="file">setup.py</span> by |
| 82 | editing <span class="file">setup.cfg</span> |
| 83 | </LI> |
| 84 | <LI>you can provide non-standard defaults for options that are not |
| 85 | easily set in <span class="file">setup.py</span> |
| 86 | </LI> |
| 87 | <LI>installers can override anything in <span class="file">setup.cfg</span> using the |
| 88 | command-line options to <span class="file">setup.py</span> |
| 89 | </LI> |
| 90 | </UL> |
| 91 | |
| 92 | <P> |
| 93 | The basic syntax of the configuration file is simple: |
| 94 | |
| 95 | <P> |
| 96 | <div class="verbatim"><pre> |
| 97 | [command] |
| 98 | option=value |
| 99 | ... |
| 100 | </pre></div> |
| 101 | |
| 102 | <P> |
| 103 | where <var>command</var> is one of the Distutils commands (e.g. |
| 104 | <code class="du-command">build_py</code>, <code class="du-command">install</code>), and <var>option</var> is one of |
| 105 | the options that command supports. Any number of options can be |
| 106 | supplied for each command, and any number of command sections can be |
| 107 | included in the file. Blank lines are ignored, as are comments, which |
| 108 | run from a "<tt class="character">#</tt>" character until the end of the line. Long |
| 109 | option values can be split across multiple lines simply by indenting |
| 110 | the continuation lines. |
| 111 | |
| 112 | <P> |
| 113 | You can find out the list of options supported by a particular command |
| 114 | with the universal <b class="programopt">--help</b> option, e.g. |
| 115 | |
| 116 | <P> |
| 117 | <div class="verbatim"><pre> |
| 118 | > python setup.py --help build_ext |
| 119 | [...] |
| 120 | Options for 'build_ext' command: |
| 121 | --build-lib (-b) directory for compiled extension modules |
| 122 | --build-temp (-t) directory for temporary files (build by-products) |
| 123 | --inplace (-i) ignore build-lib and put compiled extensions into the |
| 124 | source directory alongside your pure Python modules |
| 125 | --include-dirs (-I) list of directories to search for header files |
| 126 | --define (-D) C preprocessor macros to define |
| 127 | --undef (-U) C preprocessor macros to undefine |
| 128 | [...] |
| 129 | </pre></div> |
| 130 | |
| 131 | <P> |
| 132 | Note that an option spelled <b class="programopt">--foo-bar</b> on the command-line |
| 133 | is spelled <span class="du-option">foo_bar</span> in configuration files. |
| 134 | |
| 135 | <P> |
| 136 | For example, say you want your extensions to be built |
| 137 | ``in-place''--that is, you have an extension <tt class="module">pkg.ext</tt>, and you |
| 138 | want the compiled extension file (<span class="file">ext.so</span> on <span class="Unix">Unix</span>, say) to be put |
| 139 | in the same source directory as your pure Python modules |
| 140 | <tt class="module">pkg.mod1</tt> and <tt class="module">pkg.mod2</tt>. You can always use the |
| 141 | <b class="programopt">--inplace</b> option on the command-line to ensure this: |
| 142 | |
| 143 | <P> |
| 144 | <div class="verbatim"><pre> |
| 145 | python setup.py build_ext --inplace |
| 146 | </pre></div> |
| 147 | |
| 148 | <P> |
| 149 | But this requires that you always specify the <code class="du-command">build_ext</code> |
| 150 | command explicitly, and remember to provide <b class="programopt">--inplace</b>. |
| 151 | An easier way is to ``set and forget'' this option, by encoding it in |
| 152 | <span class="file">setup.cfg</span>, the configuration file for this distribution: |
| 153 | |
| 154 | <P> |
| 155 | <div class="verbatim"><pre> |
| 156 | [build_ext] |
| 157 | inplace=1 |
| 158 | </pre></div> |
| 159 | |
| 160 | <P> |
| 161 | This will affect all builds of this module distribution, whether or not |
| 162 | you explicitly specify <code class="du-command">build_ext</code>. If you include |
| 163 | <span class="file">setup.cfg</span> in your source distribution, it will also affect |
| 164 | end-user builds--which is probably a bad idea for this option, since |
| 165 | always building extensions in-place would break installation of the |
| 166 | module distribution. In certain peculiar cases, though, modules are |
| 167 | built right in their installation directory, so this is conceivably a |
| 168 | useful ability. (Distributing extensions that expect to be built in |
| 169 | their installation directory is almost always a bad idea, though.) |
| 170 | |
| 171 | <P> |
| 172 | Another example: certain commands take a lot of options that don't |
| 173 | change from run to run; for example, <code class="du-command">bdist_rpm</code> needs to know |
| 174 | everything required to generate a ``spec'' file for creating an RPM |
| 175 | distribution. Some of this information comes from the setup script, and |
| 176 | some is automatically generated by the Distutils (such as the list of |
| 177 | files installed). But some of it has to be supplied as options to |
| 178 | <code class="du-command">bdist_rpm</code>, which would be very tedious to do on the |
| 179 | command-line for every run. Hence, here is a snippet from the |
| 180 | Distutils' own <span class="file">setup.cfg</span>: |
| 181 | |
| 182 | <P> |
| 183 | <div class="verbatim"><pre> |
| 184 | [bdist_rpm] |
| 185 | release = 1 |
| 186 | packager = Greg Ward <gward@python.net> |
| 187 | doc_files = CHANGES.txt |
| 188 | README.txt |
| 189 | USAGE.txt |
| 190 | doc/ |
| 191 | examples/ |
| 192 | </pre></div> |
| 193 | |
| 194 | <P> |
| 195 | Note that the <span class="du-option">doc_files</span> option is simply a |
| 196 | whitespace-separated string split across multiple lines for readability. |
| 197 | |
| 198 | <P> |
| 199 | <div class="seealso"> |
| 200 | <p class="heading">See Also:</p> |
| 201 | |
| 202 | <dl compact="compact" class="seetitle"> |
| 203 | <dt><em class="citetitle"><a href="../inst/config-syntax.html" |
| 204 | >Installing Python |
| 205 | Modules</a></em></dt> |
| 206 | <dd>More information on the configuration files is |
| 207 | available in the manual for system administrators.</dd> |
| 208 | </dl> |
| 209 | </div> |
| 210 | |
| 211 | <P> |
| 212 | <BR><HR><H4>Footnotes</H4> |
| 213 | <DL> |
| 214 | <DT><A NAME="foot393">... installers</A><A |
| 215 | href="setup-config.html#tex2html1"><SUP>3.1</SUP></A></DT> |
| 216 | <DD>This |
| 217 | ideal probably won't be achieved until auto-configuration is fully |
| 218 | supported by the Distutils. |
| 219 | |
| 220 | </DD> |
| 221 | </DL> |
| 222 | <DIV CLASS="navigation"> |
| 223 | <div class='online-navigation'> |
| 224 | <p></p><hr /> |
| 225 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 226 | <tr> |
| 227 | <td class='online-navigation'><a rel="prev" title="2.8 Debugging the setup" |
| 228 | href="node14.html"><img src='../icons/previous.png' |
| 229 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 230 | <td class='online-navigation'><a rel="parent" title="Distributing Python Modules" |
| 231 | href="dist.html"><img src='../icons/up.png' |
| 232 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 233 | <td class='online-navigation'><a rel="next" title="4. Creating a Source" |
| 234 | href="source-dist.html"><img src='../icons/next.png' |
| 235 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 236 | <td align="center" width="100%">Distributing Python Modules</td> |
| 237 | <td class='online-navigation'><img src='../icons/blank.png' |
| 238 | border='0' height='32' alt='' width='32' /></td> |
| 239 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' |
| 240 | border='0' height='32' alt='Module Index' width='32' /></a></td> |
| 241 | <td class='online-navigation'><a rel="index" title="Index" |
| 242 | href="genindex.html"><img src='../icons/index.png' |
| 243 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 244 | </tr></table> |
| 245 | <div class='online-navigation'> |
| 246 | <b class="navlabel">Previous:</b> |
| 247 | <a class="sectref" rel="prev" href="node14.html">2.8 Debugging the setup</A> |
| 248 | <b class="navlabel">Up:</b> |
| 249 | <a class="sectref" rel="parent" href="dist.html">Distributing Python Modules</A> |
| 250 | <b class="navlabel">Next:</b> |
| 251 | <a class="sectref" rel="next" href="source-dist.html">4. Creating a Source</A> |
| 252 | </div> |
| 253 | </div> |
| 254 | <hr /> |
| 255 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 256 | </DIV> |
| 257 | <!--End of Navigation Panel--> |
| 258 | <ADDRESS> |
| 259 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 260 | </ADDRESS> |
| 261 | </BODY> |
| 262 | </HTML> |