[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / 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>
Commit	Line	Data
86530b38 AT	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>