Codestin Search App

History

315 lines (288 loc) · 25.2 KB

Raw

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

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>4. Building C and C++ Extensions — Python 3.7.0 說明文件</title>

title="在 Python 3.7.0 說明文件中搜尋"

href="../_static/opensearch.xml"/>

</head><body>

<ul>

<a href="../genindex.html" title="General Index"

accesskey="I">索引</a></li>

<a href="../py-modindex.html" title="Python 模組索引"

>模組</a> |</li>

<a href="windows.html" title="5. Building C and C++ Extensions on Windows"

accesskey="N">下一頁</a> |</li>

<a href="newtypes.html" title="3. Defining Extension Types: Assorted Topics"

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>

zh_TW

3.7.0

<a href="../index.html">Documentation </a> »

</li>

<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Extending and Embedding the Python Interpreter</a> »</li>

</form>

</div>

</li>

</ul>

</div>

<h1>4. Building C and C++ Extensions<a class="headerlink" href="#building-c-and-c-extensions" title="本標題的永久連結">¶</a></h1>

A C extension for CPython is a shared library (e.g. a <code class="docutils literal notranslate">.so</code> file on Linux,

<code class="docutils literal notranslate">.pyd</code> on Windows), which exports an initialization function.

To be importable, the shared library must be available on <a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal notranslate">PYTHONPATH</code></a>,

and must be named after the module name, with an appropriate extension.

When using distutils, the correct filename is generated automatically.

The initialization function has the signature:

<a class="reference internal" href="../c-api/structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyInit_modulename</code>(void)<a class="headerlink" href="#c.PyInit_modulename" title="本定義的永久連結">¶</a></dt>

It returns either a fully-initialized module, or a <a class="reference internal" href="../c-api/module.html#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate">PyModuleDef</code></a>

instance. See <a class="reference internal" href="../c-api/module.html#initializing-modules">Initializing C modules</a> for details.

For modules with ASCII-only names, the function must be named

<code class="docutils literal notranslate">PyInit_<modulename></code>, with <code class="docutils literal notranslate"><modulename></code> replaced by the name of the

module. When using <a class="reference internal" href="../c-api/module.html#multi-phase-initialization">Multi-phase initialization</a>, non-ASCII module names

are allowed. In this case, the initialization function name is

<code class="docutils literal notranslate">PyInitU_<modulename></code>, with <code class="docutils literal notranslate"><modulename></code> encoded using Python’s

punycode encoding with hyphens replaced by underscores. In Python:

<div class="highlight-python notranslate"><div class="highlight"><pre>def initfunc_name(name):

try:

suffix = b'_' + name.encode('ascii')

except UnicodeEncodeError:

suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')

return b'PyInit' + suffix

</pre></div>

</div>

It is possible to export multiple modules from a single shared library by

defining multiple initialization functions. However, importing them requires

using symbolic links or a custom importer, because by default only the

function corresponding to the filename is found.

See the 「Multiple modules in one library」 section in <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0489">PEP 489</a> for details.

<h2>4.1. Building C and C++ Extensions with distutils<a class="headerlink" href="#building-c-and-c-extensions-with-distutils" title="本標題的永久連結">¶</a></h2>

Extension modules can be built using distutils, which is included in Python.

Since distutils also supports creation of binary packages, users don’t

necessarily need a compiler and distutils to install the extension.

A distutils package contains a driver script, <code class="file docutils literal notranslate">setup.py</code>. This is a plain

Python file, which, in the most simple case, could look like this:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>from distutils.core import setup, Extension

module1 = Extension('demo',

sources = ['demo.c'])

setup (name = 'PackageName',

version = '1.0',

description = 'This is a demo package',

ext_modules = [module1])

</pre></div>

</div>

With this <code class="file docutils literal notranslate">setup.py</code>, and a file <code class="file docutils literal notranslate">demo.c</code>, running

<div class="highlight-c notranslate"><div class="highlight"><pre>python setup.py build

</pre></div>

</div>

will compile <code class="file docutils literal notranslate">demo.c</code>, and produce an extension module named <code class="docutils literal notranslate">demo</code> in

the <code class="file docutils literal notranslate">build</code> directory. Depending on the system, the module file will end

up in a subdirectory <code class="file docutils literal notranslate">build/lib.system</code>, and may have a name like

<code class="file docutils literal notranslate">demo.so</code> or <code class="file docutils literal notranslate">demo.pyd</code>.

In the <code class="file docutils literal notranslate">setup.py</code>, all execution is performed by calling the <code class="docutils literal notranslate">setup</code>

function. This takes a variable number of keyword arguments, of which the

example above uses only a subset. Specifically, the example specifies

meta-information to build packages, and it specifies the contents of the

package. Normally, a package will contain additional modules, like Python

source modules, documentation, subpackages, etc. Please refer to the distutils

documentation in <a class="reference internal" href="../distutils/index.html#distutils-index">發布 Python 模組（舊版）</a> to learn more about the features of

distutils; this section explains building extension modules only.

It is common to pre-compute arguments to <code class="xref py py-func docutils literal notranslate">setup()</code>, to better structure the

driver script. In the example above, the <code class="docutils literal notranslate">ext_modules</code> argument to

<a class="reference internal" href="../distutils/apiref.html#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate">setup()</code></a> is a list of extension modules, each of which is

an instance of

the <code class="xref py py-class docutils literal notranslate">Extension</code>. In the example, the instance

defines an extension named <code class="docutils literal notranslate">demo</code> which is build by compiling a single source

file, <code class="file docutils literal notranslate">demo.c</code>.

In many cases, building an extension is more complex, since additional

preprocessor defines and libraries may be needed. This is demonstrated in the

example below.

module1 = Extension('demo',

define_macros = [('MAJOR_VERSION', '1'),

('MINOR_VERSION', '0')],

include_dirs = ['/usr/local/include'],

libraries = ['tcl83'],

library_dirs = ['/usr/local/lib'],

sources = ['demo.c'])

setup (name = 'PackageName',

version = '1.0',

description = 'This is a demo package',

author = 'Martin v. Loewis',

author_email = '[email protected]',

url = 'https://docs.python.org/extending/building',

long_description = '''

This is really just a demo package.

''',

ext_modules = [module1])

</pre></div>

</div>

In this example, <a class="reference internal" href="../distutils/apiref.html#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate">setup()</code></a> is called with additional

meta-information, which

is recommended when distribution packages have to be built. For the extension

itself, it specifies preprocessor defines, include directories, library

directories, and libraries. Depending on the compiler, distutils passes this

information in different ways to the compiler. For example, on Unix, this may

result in the compilation commands

<div class="highlight-c notranslate"><div class="highlight"><pre>gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o

gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so

</pre></div>

</div>

These lines are for demonstration purposes only; distutils users should trust

that distutils gets the invocations right.

</div>

<h2>4.2. Distributing your extension modules<a class="headerlink" href="#distributing-your-extension-modules" title="本標題的永久連結">¶</a></h2>

When an extension has been successfully build, there are three ways to use it.

End-users will typically want to install the module, they do so by running

</pre></div>

</div>

Module maintainers should produce source packages; to do so, they run

</pre></div>

</div>

In some cases, additional files need to be included in a source distribution;

this is done through a <code class="file docutils literal notranslate">MANIFEST.in</code> file; see <a class="reference internal" href="../distutils/sourcedist.html#manifest">Specifying the files to distribute</a> for details.

If the source distribution has been build successfully, maintainers can also

create binary distributions. Depending on the platform, one of the following

commands can be used to do so.

python setup.py bdist_rpm

python setup.py bdist_dumb

</pre></div>

</div>

<ul>

<li><a class="reference internal" href="#">4. Building C and C++ Extensions</a><ul>

<li><a class="reference internal" href="#building-c-and-c-extensions-with-distutils">4.1. Building C and C++ Extensions with distutils</a></li>

<li><a class="reference internal" href="#distributing-your-extension-modules">4.2. Distributing your extension modules</a></li>

</ul>

</li>

</ul>

<a href="newtypes.html"

title="上一章">3. Defining Extension Types: Assorted Topics</a>

<a href="windows.html"

title="下一章">5. Building C and C++ Extensions on Windows</a>

<li><a href="../bugs.html">Report a Bug</a></li>

<li>

<a href="https://github.com/python/cpython/blob/3.7/Doc/extending/building.rst"

rel="nofollow">Show Source

</a>

</li>

</ul>

</div>

</div>

<ul>

<a href="../genindex.html" title="General Index"

>索引</a></li>

<a href="../py-modindex.html" title="Python 模組索引"

>模組</a> |</li>

<a href="windows.html" title="5. Building C and C++ Extensions on Windows"

>下一頁</a> |</li>

<a href="newtypes.html" title="3. Defining Extension Types: Assorted Topics"

>上一頁</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>

zh_TW

3.7.0

<a href="../index.html">Documentation </a> »

</li>

<li class="nav-item nav-item-1"><a href="index.html" >Extending and Embedding the Python Interpreter</a> »</li>

</form>

</div>

</li>

</ul>

</div>

The Python Software Foundation is a non-profit corporation.

<a href="https://www.python.org/psf/donations/">Please donate.</a>

Last updated on 8月 22, 2018.

<a href="../bugs.html">Found a bug</a>?

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.7.

</div>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

building.html

Latest commit

History

building.html

File metadata and controls