[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / ext / building.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="ext.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="ext.html" title='Extending and Embedding the Python Interpreter' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="building-on-windows.html" />
<link rel="prev" href="defining-new-types.html" />
<link rel="parent" href="ext.html" />
<link rel="next" href="distributing.html" />
<meta name='aesop' content='information' />
<title>3. Building C and C++ Extensions with distutils </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="2.2.6 More Suggestions"
  href="node33.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="Extending and Embedding the"
  href="ext.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="3.1 Distributing your extension"
  href="distributing.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></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="node33.html">2.2.6 More Suggestions</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="ext.html">Extending and Embedding the</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="distributing.html">3.1 Distributing your extension</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION005000000000000000000"></A><A NAME="building"></A>
<BR>
3. Building C and C++ Extensions with distutils
     
</H1>

<P>

<P>
Starting in Python 1.4, Python provides, on <span class="Unix">Unix</span>, a special make
file for building make files for building dynamically-linked
extensions and custom interpreters.  Starting with Python 2.0, this
mechanism (known as related to Makefile.pre.in, and Setup files) is no
longer supported. Building custom interpreters was rarely used, and
extension modules can be built using distutils.

<P>
Building an extension module using distutils requires that distutils
is installed on the build machine, which is included in Python 2.x and
available separately for Python 1.5. Since distutils also supports
creation of binary packages, users don't necessarily need a compiler
and distutils to install the extension.

<P>
A distutils package contains a driver script, <span class="file">setup.py</span>. This is
a plain Python file, which, in the most simple case, could look like
this:

<P>
<div class="verbatim"><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>

<P>
With this <span class="file">setup.py</span>, and a file <span class="file">demo.c</span>, running

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

<P>
will compile <span class="file">demo.c</span>, and produce an extension module named
"<tt class="samp">demo</tt>" in the <span class="file">build</span> directory. Depending on the system,
the module file will end up in a subdirectory <span class="file">build/lib.system</span>,
and may have a name like <span class="file">demo.so</span> or <span class="file">demo.pyd</span>.

<P>
In the <span class="file">setup.py</span>, all execution is performed by calling the
"<tt class="samp">setup</tt>" 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 of addition modules, like Python source modules,
documentation, subpackages, etc. Please refer to the distutils
documentation in <em class="citetitle"><a
 href="../dist/dist.html"
 title="Distributing Python
Modules"
 >Distributing Python
Modules</a></em> to learn more about the features of distutils; this section
explains building extension modules only.

<P>
It is common to pre-compute arguments to <tt class="function">setup</tt>, to better
structure the driver script. In the example above,
the"<tt class="samp">ext_modules</tt>" argument to <tt class="function">setup</tt> is a list of
extension modules, each of which is an instance of the
<tt class="class">Extension</tt>. In the example, the instance defines an extension
named "<tt class="samp">demo</tt>" which is build by compiling a single source file,
<span class="file">demo.c</span>.

<P>
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.

<P>
<div class="verbatim"><pre>
from distutils.core import setup, Extension

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 = 'martin@v.loewis.de',
       url = 'http://www.python.org/doc/current/ext/building.html',
       long_description = '''
This is really just a demo package.
''',
       ext_modules = [module1])
</pre></div>

<P>
In this example, <tt class="function">setup</tt> 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 <span class="Unix">Unix</span>, this may
result in the compilation commands

<P>
<div class="verbatim"><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>

<P>
These lines are for demonstration purposes only; distutils users
should trust that distutils gets the invocations right.

<P>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="distributing.html">3.1 Distributing your extension modules</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<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="2.2.6 More Suggestions"
  href="node33.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="Extending and Embedding the"
  href="ext.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="3.1 Distributing your extension"
  href="distributing.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></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="node33.html">2.2.6 More Suggestions</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="ext.html">Extending and Embedding the</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="distributing.html">3.1 Distributing your extension</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
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="ext.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="ext.html" title='Extending and Embedding the Python Interpreter' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	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="building-on-windows.html" />
	12	<link rel="prev" href="defining-new-types.html" />
	13	<link rel="parent" href="ext.html" />
	14	<link rel="next" href="distributing.html" />
	15	<meta name='aesop' content='information' />
	16	<title>3. Building C and C++ Extensions with distutils </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.2.6 More Suggestions"
	24	href="node33.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="Extending and Embedding the"
	27	href="ext.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="3.1 Distributing your extension"
	30	href="distributing.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><img src='../icons/blank.png'
	37	border='0' height='32' alt='' width='32' /></td>
	38	<td class='online-navigation'><img src='../icons/blank.png'
	39	border='0' height='32' alt='' width='32' /></td>
	40	</tr></table>
	41	<div class='online-navigation'>
	42	<b class="navlabel">Previous:</b>
	43	<a class="sectref" rel="prev" href="node33.html">2.2.6 More Suggestions</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="ext.html">Extending and Embedding the</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="distributing.html">3.1 Distributing your extension</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H1><A NAME="SECTION005000000000000000000"></A><A NAME="building"></A>
	54	<BR>
	55	3. Building C and C++ Extensions with distutils
	56
	57	</H1>
	58
	59	<P>
	60
	61	<P>
	62	Starting in Python 1.4, Python provides, on <span class="Unix">Unix</span>, a special make
	63	file for building make files for building dynamically-linked
	64	extensions and custom interpreters. Starting with Python 2.0, this
65	mechanism (known as related to Makefile.pre.in, and Setup files) is no
66	longer supported. Building custom interpreters was rarely used, and
67	extension modules can be built using distutils.
68
69	<P>
70	Building an extension module using distutils requires that distutils
71	is installed on the build machine, which is included in Python 2.x and
72	available separately for Python 1.5. Since distutils also supports
73	creation of binary packages, users don't necessarily need a compiler
74	and distutils to install the extension.
75
76	<P>
77	A distutils package contains a driver script, <span class="file">setup.py</span>. This is
78	a plain Python file, which, in the most simple case, could look like
79	this:
80
81	<P>
82	<div class="verbatim"><pre>
83	from distutils.core import setup, Extension
84
85	module1 = Extension('demo',
86	sources = ['demo.c'])
87
88	setup (name = 'PackageName',
89	version = '1.0',
90	description = 'This is a demo package',
91	ext_modules = [module1])
92	</pre></div>
93
94	<P>
95	With this <span class="file">setup.py</span>, and a file <span class="file">demo.c</span>, running
96
97	<P>
98	<div class="verbatim"><pre>
99	python setup.py build
100	</pre></div>
101
102	<P>
103	will compile <span class="file">demo.c</span>, and produce an extension module named
104	"<tt class="samp">demo</tt>" in the <span class="file">build</span> directory. Depending on the system,
105	the module file will end up in a subdirectory <span class="file">build/lib.system</span>,
106	and may have a name like <span class="file">demo.so</span> or <span class="file">demo.pyd</span>.
107
108	<P>
109	In the <span class="file">setup.py</span>, all execution is performed by calling the
110	"<tt class="samp">setup</tt>" function. This takes a variable number of keyword
111	arguments, of which the example above uses only a
112	subset. Specifically, the example specifies meta-information to build
113	packages, and it specifies the contents of the package. Normally, a
114	package will contain of addition modules, like Python source modules,
115	documentation, subpackages, etc. Please refer to the distutils
116	documentation in <em class="citetitle"><a
117	href="../dist/dist.html"
118	title="Distributing Python
119	Modules"
120	>Distributing Python
121	Modules</a></em> to learn more about the features of distutils; this section
122	explains building extension modules only.
123
124	<P>
125	It is common to pre-compute arguments to <tt class="function">setup</tt>, to better
126	structure the driver script. In the example above,
127	the"<tt class="samp">ext_modules</tt>" argument to <tt class="function">setup</tt> is a list of
128	extension modules, each of which is an instance of the
129	<tt class="class">Extension</tt>. In the example, the instance defines an extension
130	named "<tt class="samp">demo</tt>" which is build by compiling a single source file,
131	<span class="file">demo.c</span>.
132
133	<P>
134	In many cases, building an extension is more complex, since additional
135	preprocessor defines and libraries may be needed. This is demonstrated
136	in the example below.
137
138	<P>
139	<div class="verbatim"><pre>
140	from distutils.core import setup, Extension
141
142	module1 = Extension('demo',
143	define_macros = [('MAJOR_VERSION', '1'),
144	('MINOR_VERSION', '0')],
145	include_dirs = ['/usr/local/include'],
146	libraries = ['tcl83'],
147	library_dirs = ['/usr/local/lib'],
148	sources = ['demo.c'])
149
150	setup (name = 'PackageName',
151	version = '1.0',
152	description = 'This is a demo package',
153	author = 'Martin v. Loewis',
154	author_email = 'martin@v.loewis.de',
155	url = 'http://www.python.org/doc/current/ext/building.html',
156	long_description = '''
157	This is really just a demo package.
158	''',
159	ext_modules = [module1])
160	</pre></div>
161
162	<P>
163	In this example, <tt class="function">setup</tt> is called with additional
164	meta-information, which is recommended when distribution packages have
165	to be built. For the extension itself, it specifies preprocessor
166	defines, include directories, library directories, and libraries.
167	Depending on the compiler, distutils passes this information in
168	different ways to the compiler. For example, on <span class="Unix">Unix</span>, this may
169	result in the compilation commands
170
171	<P>
172	<div class="verbatim"><pre>
173	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
174
175	gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so
176	</pre></div>
177
178	<P>
179	These lines are for demonstration purposes only; distutils users
180	should trust that distutils gets the invocations right.
181
182	<P>
183
184	<p><br /></p><hr class='online-navigation' />
185	<div class='online-navigation'>
186	<!--Table of Child-Links-->
187	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
188
189	<UL CLASS="ChildLinks">
190	<LI><A href="distributing.html">3.1 Distributing your extension modules</a>
191	</ul>
192	<!--End of Table of Child-Links-->
193	</div>
194
195	<DIV CLASS="navigation">
196	<div class='online-navigation'>
197	<p></p><hr />
198	<table align="center" width="100%" cellpadding="0" cellspacing="2">
199	<tr>
200	<td class='online-navigation'><a rel="prev" title="2.2.6 More Suggestions"
201	href="node33.html"><img src='../icons/previous.png'
202	border='0' height='32' alt='Previous Page' width='32' /></A></td>
203	<td class='online-navigation'><a rel="parent" title="Extending and Embedding the"
204	href="ext.html"><img src='../icons/up.png'
205	border='0' height='32' alt='Up One Level' width='32' /></A></td>
206	<td class='online-navigation'><a rel="next" title="3.1 Distributing your extension"
207	href="distributing.html"><img src='../icons/next.png'
208	border='0' height='32' alt='Next Page' width='32' /></A></td>
209	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
210	<td class='online-navigation'><a rel="contents" title="Table of Contents"
211	href="contents.html"><img src='../icons/contents.png'
212	border='0' height='32' alt='Contents' width='32' /></A></td>
213	<td class='online-navigation'><img src='../icons/blank.png'
214	border='0' height='32' alt='' width='32' /></td>
215	<td class='online-navigation'><img src='../icons/blank.png'
216	border='0' height='32' alt='' width='32' /></td>
217	</tr></table>
218	<div class='online-navigation'>
219	<b class="navlabel">Previous:</b>
220	<a class="sectref" rel="prev" href="node33.html">2.2.6 More Suggestions</A>
221	<b class="navlabel">Up:</b>
222	<a class="sectref" rel="parent" href="ext.html">Extending and Embedding the</A>
223	<b class="navlabel">Next:</b>
224	<a class="sectref" rel="next" href="distributing.html">3.1 Distributing your extension</A>
225	</div>
226	</div>
227	<hr />
228	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
229	</DIV>
230	<!--End of Navigation Panel-->
231	<ADDRESS>
232	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
233	</ADDRESS>
234	</BODY>
235	</HTML>