projects / OpenSPARC-T2-SAM / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / dist / setup-config.html
CommitLineData
920dae64
AT		 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>
563. Writing the Setup Configuration File
57</H1>
58
59<P>
60Often, it's not possible to write down everything needed to build a
61distribution <em>a priori</em>: you may need to get some information from
62the user, or from the user's system, in order to proceed. As long as
63that information is fairly simple--a list of directories to search for
64C header files or libraries, for example--then providing a
65configuration file, <span class="file">setup.cfg</span>, for users to edit is a cheap and
66easy way to solicit it. Configuration files also let you provide
67default values for any command option, which the installer can then
68override either on the command-line or by editing the config file.
69
70<P>
71The setup configuration file is a useful middle-ground between the setup
72script--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
74script, which is outside of your control and entirely up to the
75installer. In fact, <span class="file">setup.cfg</span> (and any other Distutils
76configuration files present on the target system) are processed after
77the contents of the setup script, but before the command-line. This has
78several 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>
93The basic syntax of the configuration file is simple:
94
95<P>
96<div class="verbatim"><pre>
97[command]
98option=value
99...
100</pre></div>
101
102<P>
103where <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
105the options that command supports. Any number of options can be
106supplied for each command, and any number of command sections can be
107included in the file. Blank lines are ignored, as are comments, which
108run from a "<tt class="character">#</tt>" character until the end of the line. Long
109option values can be split across multiple lines simply by indenting
110the continuation lines.
111
112<P>
113You can find out the list of options supported by a particular command
114with the universal <b class="programopt">--help</b> option, e.g.
115
116<P>
117<div class="verbatim"><pre>
118&gt; python setup.py --help build_ext
119[...]
120Options 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>
132Note that an option spelled <b class="programopt">--foo-bar</b> on the command-line
133is spelled <span class="du-option">foo_bar</span> in configuration files.
134
135<P>
136For 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
138want the compiled extension file (<span class="file">ext.so</span> on <span class="Unix">Unix</span>, say) to be put
139in 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>
145python setup.py build_ext --inplace
146</pre></div>
147
148<P>
149But this requires that you always specify the <code class="du-command">build_ext</code>
150command explicitly, and remember to provide <b class="programopt">--inplace</b>.
151An 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]
157inplace=1
158</pre></div>
159
160<P>
161This will affect all builds of this module distribution, whether or not
162you 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
164end-user builds--which is probably a bad idea for this option, since
165always building extensions in-place would break installation of the
166module distribution. In certain peculiar cases, though, modules are
167built right in their installation directory, so this is conceivably a
168useful ability. (Distributing extensions that expect to be built in
169their installation directory is almost always a bad idea, though.)
170
171<P>
172Another example: certain commands take a lot of options that don't
173change from run to run; for example, <code class="du-command">bdist_rpm</code> needs to know
174everything required to generate a ``spec'' file for creating an RPM
175distribution. Some of this information comes from the setup script, and
176some is automatically generated by the Distutils (such as the list of
177files 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
179command-line for every run. Hence, here is a snippet from the
180Distutils' own <span class="file">setup.cfg</span>:
181
182<P>
183<div class="verbatim"><pre>
184[bdist_rpm]
185release = 1
186packager = Greg Ward &lt;gward@python.net&gt;
187doc_files = CHANGES.txt
188 README.txt
189 USAGE.txt
190 doc/
191 examples/
192</pre></div>
193
194<P>
195Note that the <span class="du-option">doc_files</span> option is simply a
196whitespace-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>
259See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
260</ADDRESS>
261</BODY>
262</HTML>
Full OpenSPARC architecture tarball including simulator, hypervisor, and OBP.