-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathconfigfile.html
More file actions
285 lines (265 loc) · 16 KB
/
configfile.html
File metadata and controls
285 lines (265 loc) · 16 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_TW">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>3. Writing the Setup Configuration File — Python 3.7.0 說明文件</title>
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/translations.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="在 Python 3.7.0 說明文件 中搜尋"
href="../_static/opensearch.xml"/>
<link rel="author" title="關於這些文件" href="../about.html" />
<link rel="index" title="索引" href="../genindex.html" />
<link rel="search" title="搜尋" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="4. Creating a Source Distribution" href="sourcedist.html" />
<link rel="prev" title="2. Writing the Setup Script" href="setupscript.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/3/distutils/configfile.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/switchers.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>瀏覽</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模組索引"
>模組</a> |</li>
<li class="right" >
<a href="sourcedist.html" title="4. Creating a Source Distribution"
accesskey="N">下一頁</a> |</li>
<li class="right" >
<a href="setupscript.html" title="2. Writing the Setup Script"
accesskey="P">上一頁</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<span class="language_switcher_placeholder">zh_TW</span>
<span class="version_switcher_placeholder">3.7.0</span>
<a href="../index.html">Documentation </a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">發布 Python 模組（舊版）</a> »</li>
<li class="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="writing-the-setup-configuration-file">
<span id="setup-config"></span><h1>3. Writing the Setup Configuration File<a class="headerlink" href="#writing-the-setup-configuration-file" title="本標題的永久連結">¶</a></h1>
<p>Often, it’s not possible to write down everything needed to build a distribution
<em>a priori</em>: you may need to get some information from the user, or from the
user’s system, in order to proceed. As long as that information is fairly
simple—a list of directories to search for C header files or libraries, for
example—then providing a configuration file, <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>, for users to
edit is a cheap and easy way to solicit it. Configuration files also let you
provide default values for any command option, which the installer can then
override either on the command-line or by editing the config file.</p>
<p>The setup configuration file is a useful middle-ground between the setup script
—which, ideally, would be opaque to installers <a class="footnote-reference" href="#id2" id="id1">[1]</a>—and the command-line to
the setup script, which is outside of your control and entirely up to the
installer. In fact, <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code> (and any other Distutils configuration
files present on the target system) are processed after the contents of the
setup script, but before the command-line. This has several useful
consequences:</p>
<ul class="simple">
<li>installers can override some of what you put in <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> by editing
<code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code></li>
<li>you can provide non-standard defaults for options that are not easily set in
<code class="file docutils literal notranslate"><span class="pre">setup.py</span></code></li>
<li>installers can override anything in <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code> using the command-line
options to <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code></li>
</ul>
<p>The basic syntax of the configuration file is simple:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[command]</span>
<span class="na">option</span><span class="o">=</span><span class="s">value</span>
<span class="na">...</span>
</pre></div>
</div>
<p>where <em>command</em> is one of the Distutils commands (e.g. <strong class="command">build_py</strong>,
<strong class="command">install</strong>), and <em>option</em> is one of the options that command supports.
Any number of options can be supplied for each command, and any number of
command sections can be included in the file. Blank lines are ignored, as are
comments, which run from a <code class="docutils literal notranslate"><span class="pre">'#'</span></code> character until the end of the line. Long
option values can be split across multiple lines simply by indenting the
continuation lines.</p>
<p>You can find out the list of options supported by a particular command with the
universal <code class="xref std std-option docutils literal notranslate"><span class="pre">--help</span></code> option, e.g.</p>
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python setup.py --help build_ext
<span class="go">[...]</span>
<span class="go">Options for 'build_ext' command:</span>
<span class="go"> --build-lib (-b) directory for compiled extension modules</span>
<span class="go"> --build-temp (-t) directory for temporary files (build by-products)</span>
<span class="go"> --inplace (-i) ignore build-lib and put compiled extensions into the</span>
<span class="go"> source directory alongside your pure Python modules</span>
<span class="go"> --include-dirs (-I) list of directories to search for header files</span>
<span class="go"> --define (-D) C preprocessor macros to define</span>
<span class="go"> --undef (-U) C preprocessor macros to undefine</span>
<span class="go"> --swig-opts list of SWIG command line options</span>
<span class="go">[...]</span>
</pre></div>
</div>
<p>Note that an option spelled <code class="xref std std-option docutils literal notranslate"><span class="pre">--foo-bar</span></code> on the command-line is spelled
<code class="docutils literal notranslate"><span class="pre">foo_bar</span></code> in configuration files.</p>
<p id="distutils-build-ext-inplace">For example, say you want your extensions to be built 「in-place」—that is, you
have an extension <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.ext</span></code>, and you want the compiled extension file
(<code class="file docutils literal notranslate"><span class="pre">ext.so</span></code> on Unix, say) to be put in the same source directory as your
pure Python modules <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.mod1</span></code> and <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.mod2</span></code>. You can always use the
<code class="xref std std-option docutils literal notranslate"><span class="pre">--inplace</span></code> option on the command-line to ensure this:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>python setup.py build_ext --inplace
</pre></div>
</div>
<p>But this requires that you always specify the <strong class="command">build_ext</strong> command
explicitly, and remember to provide <code class="xref std std-option docutils literal notranslate"><span class="pre">--inplace</span></code>. An easier way is to
「set and forget」 this option, by encoding it in <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>, the
configuration file for this distribution:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[build_ext]</span>
<span class="na">inplace</span><span class="o">=</span><span class="s">1</span>
</pre></div>
</div>
<p>This will affect all builds of this module distribution, whether or not you
explicitly specify <strong class="command">build_ext</strong>. If you include <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code> in
your source distribution, it will also affect end-user builds—which is
probably a bad idea for this option, since always building extensions in-place
would break installation of the module distribution. In certain peculiar cases,
though, modules are built right in their installation directory, so this is
conceivably a useful ability. (Distributing extensions that expect to be built
in their installation directory is almost always a bad idea, though.)</p>
<p>Another example: certain commands take a lot of options that don’t change from
run to run; for example, <strong class="command">bdist_rpm</strong> needs to know everything required
to generate a 「spec」 file for creating an RPM distribution. Some of this
information comes from the setup script, and some is automatically generated by
the Distutils (such as the list of files installed). But some of it has to be
supplied as options to <strong class="command">bdist_rpm</strong>, which would be very tedious to do
on the command-line for every run. Hence, here is a snippet from the Distutils』
own <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>:</p>
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[bdist_rpm]</span>
<span class="na">release</span> <span class="o">=</span> <span class="s">1</span>
<span class="na">packager</span> <span class="o">=</span> <span class="s">Greg Ward <[email protected]></span>
<span class="na">doc_files</span> <span class="o">=</span> <span class="s">CHANGES.txt</span>
<span class="s"> README.txt</span>
<span class="s"> USAGE.txt</span>
<span class="s"> doc/</span>
<span class="s"> examples/</span>
</pre></div>
</div>
<p>Note that the <code class="docutils literal notranslate"><span class="pre">doc_files</span></code> option is simply a whitespace-separated string
split across multiple lines for readability.</p>
<div class="admonition seealso">
<p class="first admonition-title">也參考</p>
<dl class="last docutils">
<dt><a class="reference internal" href="../install/index.html#inst-config-syntax"><span class="std std-ref">Syntax of config files</span></a> in 「Installing Python Modules」</dt>
<dd>More information on the configuration files is available in the manual for
system administrators.</dd>
</dl>
</div>
<p class="rubric">註解</p>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>This ideal probably won’t be achieved until auto-configuration is fully
supported by the Distutils.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>上個主題</h4>
<p class="topless"><a href="setupscript.html"
title="上一章">2. Writing the Setup Script</a></p>
<h4>下個主題</h4>
<p class="topless"><a href="sourcedist.html"
title="下一章">4. Creating a Source Distribution</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/configfile.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>瀏覽</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>索引</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python 模組索引"
>模組</a> |</li>
<li class="right" >
<a href="sourcedist.html" title="4. Creating a Source Distribution"
>下一頁</a> |</li>
<li class="right" >
<a href="setupscript.html" title="2. Writing the Setup Script"
>上一頁</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<span class="language_switcher_placeholder">zh_TW</span>
<span class="version_switcher_placeholder">3.7.0</span>
<a href="../index.html">Documentation </a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >發布 Python 模組（舊版）</a> »</li>
<li class="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2001-2018, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on 8月 22, 2018.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.7.
</div>
</body>
</html>