sam-t2/devtools/amd64/html/python/inst/config-syntax.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="inst.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="inst.html" title='Installing Python Modules' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="tweak-flags.html" />
<link rel="prev" href="search-path.html" />
<link rel="parent" href="inst.html" />
<link rel="next" href="tweak-flags.html" />
<meta name='aesop' content='information' />
<title>5 Distutils Configuration Files</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4 Custom Installation"
  href="search-path.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="Installing Python Modules"
  href="inst.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6 Building Extensions: Tips"
  href="tweak-flags.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Installing Python Modules</td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="search-path.html">4 Custom Installation</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="inst.html">Installing Python Modules</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="tweak-flags.html">6 Building Extensions: Tips</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="config-syntax.html#SECTION000510000000000000000">5.1 Location and names of config files</a>
<LI><A href="config-syntax.html#SECTION000520000000000000000">5.2 Syntax of config files</a>
</ul>
<!--End of Table of Child-Links-->
</div>
<HR>

<H1><A NAME="SECTION000500000000000000000"></A>
<A NAME="config-files"></A>
<BR>
5 Distutils Configuration Files
</H1>

<P>
As mentioned above, you can use Distutils configuration files to record
personal or site preferences for any Distutils options.  That is, any
option to any command can be stored in one of two or three (depending on
your platform) configuration files, which will be consulted before the
command-line is parsed.  This means that configuration files will
override default values, and the command-line will in turn override
configuration files.  Furthermore, if multiple configuration files
apply, values from ``earlier'' files are overridden by ``later'' files.

<P>

<H2><A NAME="SECTION000510000000000000000"></A>
<A NAME="config-filenames"></A>
<BR>
5.1 Location and names of config files
</H2>

<P>
The names and locations of the configuration files vary slightly across
platforms.  On <span class="Unix">Unix</span>and Mac OS X, the three configuration files (in the order they
are processed) are:
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="left"  >Type of file</th>
      <th class="left"  >Location and filename</th>
      <th class="center">Notes</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="left"   valign="baseline">system</td>
        <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>
        <td class="center">(1)</td></tr>
    <tr><td class="left"   valign="baseline">personal</td>
        <td class="left"  ><span class="file">$HOME/.pydistutils.cfg</span></td>
        <td class="center">(2)</td></tr>
    <tr><td class="left"   valign="baseline">local</td>
        <td class="left"  ><span class="file">setup.cfg</span></td>
        <td class="center">(3)</td></tr></tbody>
</table></div>

<P>
And on Windows, the configuration files are:
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="left"  >Type of file</th>
      <th class="left"  >Location and filename</th>
      <th class="center">Notes</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="left"   valign="baseline">system</td>
        <td class="left"  ><span class="file"><span class="du-filevar">prefix</span>&#92;Lib&#92;distutils&#92;distutils.cfg</span></td>
        <td class="center">(4)</td></tr>
    <tr><td class="left"   valign="baseline">personal</td>
        <td class="left"  ><span class="file">%HOME%&#92;pydistutils.cfg</span></td>
        <td class="center">(5)</td></tr>
    <tr><td class="left"   valign="baseline">local</td>
        <td class="left"  ><span class="file">setup.cfg</span></td>
        <td class="center">(3)</td></tr></tbody>
</table></div>

<P>
Notes:
<DL>
<DT><STRONG>(1)</STRONG></DT>
<DD>Strictly speaking, the system-wide configuration file lives
  in the directory where the Distutils are installed; under Python 1.6
  and later on <span class="Unix">Unix</span>, this is as shown. For Python 1.5.2, the Distutils
  will normally be installed to
  <span class="file"><span class="du-filevar">prefix</span>/lib/python1.5/site-packages/distutils</span>,
  so the system configuration file should be put there under Python
  1.5.2.
</DD>
<DT><STRONG>(2)</STRONG></DT>
<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
  defined, the user's home directory will be determined with the
  <tt class="function">getpwuid()</tt> function from the standard
  <a class="ulink" href="../lib/module-pwd.html"
  ><tt class="module">pwd</tt></a> module.
</DD>
<DT><STRONG>(3)</STRONG></DT>
<DD>I.e., in the current directory (usually the location of the
  setup script).
</DD>
<DT><STRONG>(4)</STRONG></DT>
<DD>(See also note (1).)  Under Python 1.6 and later, Python's
  default ``installation prefix'' is <span class="file">C:&#92;Python</span>, so
  the system configuration file is normally
  <span class="file">C:&#92;Python&#92;Lib&#92;distutils&#92;distutils.cfg</span>.
  Under Python 1.5.2, the default prefix was
  <span class="file">C:&#92;Program&nbsp;Files&#92;Python</span>, and the
  Distutils were not part of the standard library--so the system
  configuration file would be
  <span class="file">C:&#92;Program&nbsp;Files&#92;Python&#92;distutils&#92;distutils.cfg</span>
  in a standard Python 1.5.2 installation under Windows.
</DD>
<DT><STRONG>(5)</STRONG></DT>
<DD>On Windows, if the <a class="envvar" id='l2h-6' xml:id='l2h-6'>HOME</a> environment variable is not
  defined, no personal configuration file will be found or used.  (In
  other words, the Distutils make no attempt to guess your home
  directory on Windows.)
</DD>
</DL>

<P>

<H2><A NAME="SECTION000520000000000000000"></A>
<A NAME="config-syntax"></A>
<BR>
5.2 Syntax of config files
</H2>

<P>
The Distutils configuration files all have the same syntax.  The config
files are grouped into sections.  There is one section for each Distutils
command, plus a <code>global</code> section for global options that affect
every command.  Each section consists of one option per line, specified
as <code>option=value</code>.

<P>
For example, the following is a complete config file that just forces
all commands to run quietly by default:

<P>
<div class="verbatim"><pre>
[global]
verbose=0
</pre></div>

<P>
If this is installed as the system config file, it will affect all
processing of any Python module distribution by any user on the current
system.  If it is installed as your personal config file (on systems
that support them), it will affect only module distributions processed
by you.  And if it is used as the <span class="file">setup.cfg</span> for a particular
module distribution, it affects only that distribution.

<P>
You could override the default ``build base'' directory and make the
<code class="du-command">build*</code> commands always forcibly rebuild all files with the
following:

<P>
<div class="verbatim"><pre>
[build]
build-base=blib
force=1
</pre></div>

<P>
which corresponds to the command-line arguments

<P>
<div class="verbatim"><pre>
python setup.py build --build-base=blib --force
</pre></div>

<P>
except that including the <code class="du-command">build</code> command on the command-line
means that command will be run.  Including a particular command in
config files has no such implication; it only means that if the command
is run, the options in the config file will apply.  (Or if other
commands that derive values from it are run, they will use the values in
the config file.)

<P>
You can find out the complete list of options for any command using the
<b class="programopt">--help</b> option, e.g.:

<P>
<div class="verbatim"><pre>
python setup.py build --help
</pre></div>

<P>
and you can find out the complete list of global options by using
<b class="programopt">--help</b> without a command:

<P>
<div class="verbatim"><pre>
python setup.py --help
</pre></div>

<P>
See also the ``Reference'' section of the ``Distributing Python
Modules'' manual.

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4 Custom Installation"
  href="search-path.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="Installing Python Modules"
  href="inst.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6 Building Extensions: Tips"
  href="tweak-flags.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Installing Python Modules</td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="search-path.html">4 Custom Installation</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="inst.html">Installing Python Modules</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="tweak-flags.html">6 Building Extensions: Tips</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>