| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="inst.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="inst.html" title='Installing Python Modules' /> |
| 8 | <link rel='last' href='about.html' title='About this document...' /> |
| 9 | <link rel='help' href='about.html' title='About this document...' /> |
| 10 | <link rel="next" href="tweak-flags.html" /> |
| 11 | <link rel="prev" href="search-path.html" /> |
| 12 | <link rel="parent" href="inst.html" /> |
| 13 | <link rel="next" href="tweak-flags.html" /> |
| 14 | <meta name='aesop' content='information' /> |
| 15 | <title>5 Distutils Configuration Files</title> |
| 16 | </head> |
| 17 | <body> |
| 18 | <DIV CLASS="navigation"> |
| 19 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 20 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 21 | <tr> |
| 22 | <td class='online-navigation'><a rel="prev" title="4 Custom Installation" |
| 23 | href="search-path.html"><img src='../icons/previous.png' |
| 24 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 25 | <td class='online-navigation'><a rel="parent" title="Installing Python Modules" |
| 26 | href="inst.html"><img src='../icons/up.png' |
| 27 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 28 | <td class='online-navigation'><a rel="next" title="6 Building Extensions: Tips" |
| 29 | href="tweak-flags.html"><img src='../icons/next.png' |
| 30 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 31 | <td align="center" width="100%">Installing Python Modules</td> |
| 32 | <td class='online-navigation'><img src='../icons/blank.png' |
| 33 | border='0' height='32' alt='' width='32' /></td> |
| 34 | <td class='online-navigation'><img src='../icons/blank.png' |
| 35 | border='0' height='32' alt='' width='32' /></td> |
| 36 | <td class='online-navigation'><img src='../icons/blank.png' |
| 37 | border='0' height='32' alt='' width='32' /></td> |
| 38 | </tr></table> |
| 39 | <div class='online-navigation'> |
| 40 | <b class="navlabel">Previous:</b> |
| 41 | <a class="sectref" rel="prev" href="search-path.html">4 Custom Installation</A> |
| 42 | <b class="navlabel">Up:</b> |
| 43 | <a class="sectref" rel="parent" href="inst.html">Installing Python Modules</A> |
| 44 | <b class="navlabel">Next:</b> |
| 45 | <a class="sectref" rel="next" href="tweak-flags.html">6 Building Extensions: Tips</A> |
| 46 | </div> |
| 47 | <hr /></div> |
| 48 | </DIV> |
| 49 | <!--End of Navigation Panel--> |
| 50 | <div class='online-navigation'> |
| 51 | <!--Table of Child-Links--> |
| 52 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> |
| 53 | |
| 54 | <UL CLASS="ChildLinks"> |
| 55 | <LI><A href="config-syntax.html#SECTION000510000000000000000">5.1 Location and names of config files</a> |
| 56 | <LI><A href="config-syntax.html#SECTION000520000000000000000">5.2 Syntax of config files</a> |
| 57 | </ul> |
| 58 | <!--End of Table of Child-Links--> |
| 59 | </div> |
| 60 | <HR> |
| 61 | |
| 62 | <H1><A NAME="SECTION000500000000000000000"></A> |
| 63 | <A NAME="config-files"></A> |
| 64 | <BR> |
| 65 | 5 Distutils Configuration Files |
| 66 | </H1> |
| 67 | |
| 68 | <P> |
| 69 | As mentioned above, you can use Distutils configuration files to record |
| 70 | personal or site preferences for any Distutils options. That is, any |
| 71 | option to any command can be stored in one of two or three (depending on |
| 72 | your platform) configuration files, which will be consulted before the |
| 73 | command-line is parsed. This means that configuration files will |
| 74 | override default values, and the command-line will in turn override |
| 75 | configuration files. Furthermore, if multiple configuration files |
| 76 | apply, values from ``earlier'' files are overridden by ``later'' files. |
| 77 | |
| 78 | <P> |
| 79 | |
| 80 | <H2><A NAME="SECTION000510000000000000000"></A> |
| 81 | <A NAME="config-filenames"></A> |
| 82 | <BR> |
| 83 | 5.1 Location and names of config files |
| 84 | </H2> |
| 85 | |
| 86 | <P> |
| 87 | The names and locations of the configuration files vary slightly across |
| 88 | platforms. On <span class="Unix">Unix</span>and Mac OS X, the three configuration files (in the order they |
| 89 | are processed) are: |
| 90 | <div class="center"><table class="realtable"> |
| 91 | <thead> |
| 92 | <tr> |
| 93 | <th class="left" >Type of file</th> |
| 94 | <th class="left" >Location and filename</th> |
| 95 | <th class="center">Notes</th> |
| 96 | </tr> |
| 97 | </thead> |
| 98 | <tbody> |
| 99 | <tr><td class="left" valign="baseline">system</td> |
| 100 | <td class="left" ><span class="file"><span class="du-filevar">prefix</span>/lib/python<span class="du-filevar">ver</span>/distutils/distutils.cfg</span></td> |
| 101 | <td class="center">(1)</td></tr> |
| 102 | <tr><td class="left" valign="baseline">personal</td> |
| 103 | <td class="left" ><span class="file">$HOME/.pydistutils.cfg</span></td> |
| 104 | <td class="center">(2)</td></tr> |
| 105 | <tr><td class="left" valign="baseline">local</td> |
| 106 | <td class="left" ><span class="file">setup.cfg</span></td> |
| 107 | <td class="center">(3)</td></tr></tbody> |
| 108 | </table></div> |
| 109 | |
| 110 | <P> |
| 111 | And on Windows, the configuration files are: |
| 112 | <div class="center"><table class="realtable"> |
| 113 | <thead> |
| 114 | <tr> |
| 115 | <th class="left" >Type of file</th> |
| 116 | <th class="left" >Location and filename</th> |
| 117 | <th class="center">Notes</th> |
| 118 | </tr> |
| 119 | </thead> |
| 120 | <tbody> |
| 121 | <tr><td class="left" valign="baseline">system</td> |
| 122 | <td class="left" ><span class="file"><span class="du-filevar">prefix</span>\Lib\distutils\distutils.cfg</span></td> |
| 123 | <td class="center">(4)</td></tr> |
| 124 | <tr><td class="left" valign="baseline">personal</td> |
| 125 | <td class="left" ><span class="file">%HOME%\pydistutils.cfg</span></td> |
| 126 | <td class="center">(5)</td></tr> |
| 127 | <tr><td class="left" valign="baseline">local</td> |
| 128 | <td class="left" ><span class="file">setup.cfg</span></td> |
| 129 | <td class="center">(3)</td></tr></tbody> |
| 130 | </table></div> |
| 131 | |
| 132 | <P> |
| 133 | Notes: |
| 134 | <DL> |
| 135 | <DT><STRONG>(1)</STRONG></DT> |
| 136 | <DD>Strictly speaking, the system-wide configuration file lives |
| 137 | in the directory where the Distutils are installed; under Python 1.6 |
| 138 | and later on <span class="Unix">Unix</span>, this is as shown. For Python 1.5.2, the Distutils |
| 139 | will normally be installed to |
| 140 | <span class="file"><span class="du-filevar">prefix</span>/lib/python1.5/site-packages/distutils</span>, |
| 141 | so the system configuration file should be put there under Python |
| 142 | 1.5.2. |
| 143 | </DD> |
| 144 | <DT><STRONG>(2)</STRONG></DT> |
| 145 | <DD>On <span class="Unix">Unix</span>, if the <a class="envvar" id='l2h-5' xml:id='l2h-5'>HOME</a> environment variable is not |
| 146 | defined, the user's home directory will be determined with the |
| 147 | <tt class="function">getpwuid()</tt> function from the standard |
| 148 | <a class="ulink" href="../lib/module-pwd.html" |
| 149 | ><tt class="module">pwd</tt></a> module. |
| 150 | </DD> |
| 151 | <DT><STRONG>(3)</STRONG></DT> |
| 152 | <DD>I.e., in the current directory (usually the location of the |
| 153 | setup script). |
| 154 | </DD> |
| 155 | <DT><STRONG>(4)</STRONG></DT> |
| 156 | <DD>(See also note (1).) Under Python 1.6 and later, Python's |
| 157 | default ``installation prefix'' is <span class="file">C:\Python</span>, so |
| 158 | the system configuration file is normally |
| 159 | <span class="file">C:\Python\Lib\distutils\distutils.cfg</span>. |
| 160 | Under Python 1.5.2, the default prefix was |
| 161 | <span class="file">C:\Program Files\Python</span>, and the |
| 162 | Distutils were not part of the standard library--so the system |
| 163 | configuration file would be |
| 164 | <span class="file">C:\Program Files\Python\distutils\distutils.cfg</span> |
| 165 | in a standard Python 1.5.2 installation under Windows. |
| 166 | </DD> |
| 167 | <DT><STRONG>(5)</STRONG></DT> |
| 168 | <DD>On Windows, if the <a class="envvar" id='l2h-6' xml:id='l2h-6'>HOME</a> environment variable is not |
| 169 | defined, no personal configuration file will be found or used. (In |
| 170 | other words, the Distutils make no attempt to guess your home |
| 171 | directory on Windows.) |
| 172 | </DD> |
| 173 | </DL> |
| 174 | |
| 175 | <P> |
| 176 | |
| 177 | <H2><A NAME="SECTION000520000000000000000"></A> |
| 178 | <A NAME="config-syntax"></A> |
| 179 | <BR> |
| 180 | 5.2 Syntax of config files |
| 181 | </H2> |
| 182 | |
| 183 | <P> |
| 184 | The Distutils configuration files all have the same syntax. The config |
| 185 | files are grouped into sections. There is one section for each Distutils |
| 186 | command, plus a <code>global</code> section for global options that affect |
| 187 | every command. Each section consists of one option per line, specified |
| 188 | as <code>option=value</code>. |
| 189 | |
| 190 | <P> |
| 191 | For example, the following is a complete config file that just forces |
| 192 | all commands to run quietly by default: |
| 193 | |
| 194 | <P> |
| 195 | <div class="verbatim"><pre> |
| 196 | [global] |
| 197 | verbose=0 |
| 198 | </pre></div> |
| 199 | |
| 200 | <P> |
| 201 | If this is installed as the system config file, it will affect all |
| 202 | processing of any Python module distribution by any user on the current |
| 203 | system. If it is installed as your personal config file (on systems |
| 204 | that support them), it will affect only module distributions processed |
| 205 | by you. And if it is used as the <span class="file">setup.cfg</span> for a particular |
| 206 | module distribution, it affects only that distribution. |
| 207 | |
| 208 | <P> |
| 209 | You could override the default ``build base'' directory and make the |
| 210 | <code class="du-command">build*</code> commands always forcibly rebuild all files with the |
| 211 | following: |
| 212 | |
| 213 | <P> |
| 214 | <div class="verbatim"><pre> |
| 215 | [build] |
| 216 | build-base=blib |
| 217 | force=1 |
| 218 | </pre></div> |
| 219 | |
| 220 | <P> |
| 221 | which corresponds to the command-line arguments |
| 222 | |
| 223 | <P> |
| 224 | <div class="verbatim"><pre> |
| 225 | python setup.py build --build-base=blib --force |
| 226 | </pre></div> |
| 227 | |
| 228 | <P> |
| 229 | except that including the <code class="du-command">build</code> command on the command-line |
| 230 | means that command will be run. Including a particular command in |
| 231 | config files has no such implication; it only means that if the command |
| 232 | is run, the options in the config file will apply. (Or if other |
| 233 | commands that derive values from it are run, they will use the values in |
| 234 | the config file.) |
| 235 | |
| 236 | <P> |
| 237 | You can find out the complete list of options for any command using the |
| 238 | <b class="programopt">--help</b> option, e.g.: |
| 239 | |
| 240 | <P> |
| 241 | <div class="verbatim"><pre> |
| 242 | python setup.py build --help |
| 243 | </pre></div> |
| 244 | |
| 245 | <P> |
| 246 | and you can find out the complete list of global options by using |
| 247 | <b class="programopt">--help</b> without a command: |
| 248 | |
| 249 | <P> |
| 250 | <div class="verbatim"><pre> |
| 251 | python setup.py --help |
| 252 | </pre></div> |
| 253 | |
| 254 | <P> |
| 255 | See also the ``Reference'' section of the ``Distributing Python |
| 256 | Modules'' manual. |
| 257 | |
| 258 | <P> |
| 259 | |
| 260 | <DIV CLASS="navigation"> |
| 261 | <div class='online-navigation'> |
| 262 | <p></p><hr /> |
| 263 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 264 | <tr> |
| 265 | <td class='online-navigation'><a rel="prev" title="4 Custom Installation" |
| 266 | href="search-path.html"><img src='../icons/previous.png' |
| 267 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 268 | <td class='online-navigation'><a rel="parent" title="Installing Python Modules" |
| 269 | href="inst.html"><img src='../icons/up.png' |
| 270 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 271 | <td class='online-navigation'><a rel="next" title="6 Building Extensions: Tips" |
| 272 | href="tweak-flags.html"><img src='../icons/next.png' |
| 273 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 274 | <td align="center" width="100%">Installing Python Modules</td> |
| 275 | <td class='online-navigation'><img src='../icons/blank.png' |
| 276 | border='0' height='32' alt='' width='32' /></td> |
| 277 | <td class='online-navigation'><img src='../icons/blank.png' |
| 278 | border='0' height='32' alt='' width='32' /></td> |
| 279 | <td class='online-navigation'><img src='../icons/blank.png' |
| 280 | border='0' height='32' alt='' width='32' /></td> |
| 281 | </tr></table> |
| 282 | <div class='online-navigation'> |
| 283 | <b class="navlabel">Previous:</b> |
| 284 | <a class="sectref" rel="prev" href="search-path.html">4 Custom Installation</A> |
| 285 | <b class="navlabel">Up:</b> |
| 286 | <a class="sectref" rel="parent" href="inst.html">Installing Python Modules</A> |
| 287 | <b class="navlabel">Next:</b> |
| 288 | <a class="sectref" rel="next" href="tweak-flags.html">6 Building Extensions: Tips</A> |
| 289 | </div> |
| 290 | </div> |
| 291 | <hr /> |
| 292 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 293 | </DIV> |
| 294 | <!--End of Navigation Panel--> |
| 295 | <ADDRESS> |
| 296 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 297 | </ADDRESS> |
| 298 | </BODY> |
| 299 | </HTML> |