[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / dist / describing-extensions.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="dist.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="dist.html" title='Distributing Python Modules' />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="node10.html" />
<link rel="prev" href="listing-modules.html" />
<link rel="parent" href="setup-script.html" />
<link rel="next" href="node10.html" />
<meta name='aesop' content='information' />
<title>2.3 Describing extension modules</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 Listing individual modules"
  href="listing-modules.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="2. Writing the Setup"
  href="setup-script.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="2.4 Installing Scripts"
  href="node10.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Distributing Python Modules</td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="listing-modules.html">2.2 Listing individual modules</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="setup-script.html">2. Writing the Setup</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node10.html">2.4 Installing Scripts</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="describing-extensions.html#SECTION002310000000000000000">2.3.1 Extension names and packages</a>
<LI><A href="describing-extensions.html#SECTION002320000000000000000">2.3.2 Extension source files</a>
<LI><A href="describing-extensions.html#SECTION002330000000000000000">2.3.3 Preprocessor options</a>
<LI><A href="describing-extensions.html#SECTION002340000000000000000">2.3.4 Library options</a>
<LI><A href="describing-extensions.html#SECTION002350000000000000000">2.3.5 Other options</a>
</ul>
<!--End of Table of Child-Links-->
</div>
<HR>

<H1><A NAME="SECTION002300000000000000000"></A>
<A NAME="describing-extensions"></A>
<BR>
2.3 Describing extension modules
</H1>

<P>
Just as writing Python extension modules is a bit more complicated than
writing pure Python modules, describing them to the Distutils is a bit
more complicated.  Unlike pure modules, it's not enough just to list
modules or packages and expect the Distutils to go out and find the
right files; you have to specify the extension name, source file(s), and
any compile/link requirements (include directories, libraries to link
with, etc.).

<P>
All of this is done through another keyword argument to
<tt class="function">setup()</tt>, the <span class="du-option">ext_modules</span> option.  <span class="du-option">ext_modules</span>
is just a list of <tt class="class">Extension</tt> instances, each of which describes a
single extension module.  Suppose your distribution includes a single
extension, called <tt class="module">foo</tt> and implemented by <span class="file">foo.c</span>.  If no
additional instructions to the compiler/linker are needed, describing
this extension is quite simple:

<P>
<div class="verbatim"><pre>
Extension('foo', ['foo.c'])
</pre></div>

<P>
The <tt class="class">Extension</tt> class can be imported from
<tt class="module">distutils.core</tt> along with <tt class="function">setup()</tt>.  Thus, the setup
script for a module distribution that contains only this one extension
and nothing else might be:

<P>
<div class="verbatim"><pre>
from distutils.core import setup, Extension
setup(name='foo',
      version='1.0',
      ext_modules=[Extension('foo', ['foo.c'])],
      )
</pre></div>

<P>
The <tt class="class">Extension</tt> class (actually, the underlying extension-building
machinery implemented by the <code class="du-command">build_ext</code> command) supports a
great deal of flexibility in describing Python extensions, which is
explained in the following sections.  

<P>

<H2><A NAME="SECTION002310000000000000000">
2.3.1 Extension names and packages</A>
</H2>

<P>
The first argument to the <tt class="class">Extension</tt> constructor is always the
name of the extension, including any package names.  For example,

<P>
<div class="verbatim"><pre>
Extension('foo', ['src/foo1.c', 'src/foo2.c'])
</pre></div>

<P>
describes an extension that lives in the root package, while

<P>
<div class="verbatim"><pre>
Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
</pre></div>

<P>
describes the same extension in the <tt class="module">pkg</tt> package.  The source
files and resulting object code are identical in both cases; the only
difference is where in the filesystem (and therefore where in Python's
namespace hierarchy) the resulting extension lives.

<P>
If you have a number of extensions all in the same package (or all under
the same base package), use the <span class="du-option">ext_package</span> keyword argument
to <tt class="function">setup()</tt>.  For example,

<P>
<div class="verbatim"><pre>
setup(...
      ext_package='pkg',
      ext_modules=[Extension('foo', ['foo.c']),
                   Extension('subpkg.bar', ['bar.c'])],
     )
</pre></div>

<P>
will compile <span class="file">foo.c</span> to the extension <tt class="module">pkg.foo</tt>, and
<span class="file">bar.c</span> to <tt class="module">pkg.subpkg.bar</tt>.

<P>

<H2><A NAME="SECTION002320000000000000000">
2.3.2 Extension source files</A>
</H2>

<P>
The second argument to the <tt class="class">Extension</tt> constructor is a list of
source files.  Since the Distutils currently only support C, C++, and
Objective-C extensions, these are normally C/C++/Objective-C source
files.  (Be sure to use appropriate extensions to distinguish C++ source files: <span class="file">.cc</span> and <span class="file">.cpp</span> seem to be recognized by both
<span class="Unix">Unix</span> and Windows compilers.)

<P>
However, you can also include SWIG interface (<span class="file">.i</span>) files in the
list; the <code class="du-command">build_ext</code> command knows how to deal with SWIG
extensions: it will run SWIG on the interface file and compile the
resulting C/C++ file into your extension.

<P>
<b class="du-xxx">SWIG support is rough around the edges and largely untested;
  especially SWIG support for C++ extensions!  Explain in more detail
  here when the interface firms up.</b>

<P>
On some platforms, you can include non-source files that are processed
by the compiler and included in your extension.  Currently, this just
means Windows message text (<span class="file">.mc</span>) files and resource definition
(<span class="file">.rc</span>) files for Visual C++. These will be compiled to binary resource
(<span class="file">.res</span>) files and linked into the executable.

<P>

<H2><A NAME="SECTION002330000000000000000">
2.3.3 Preprocessor options</A>
</H2>

<P>
Three optional arguments to <tt class="class">Extension</tt> will help if you need to
specify include directories to search or preprocessor macros to
define/undefine: <code>include_dirs</code>, <code>define_macros</code>, and
<code>undef_macros</code>.

<P>
For example, if your extension requires header files in the
<span class="file">include</span> directory under your distribution root, use the
<code>include_dirs</code> option:

<P>
<div class="verbatim"><pre>
Extension('foo', ['foo.c'], include_dirs=['include'])
</pre></div>

<P>
You can specify absolute directories there; if you know that your
extension will only be built on <span class="Unix">Unix</span> systems with X11R6 installed to
<span class="file">/usr</span>, you can get away with

<P>
<div class="verbatim"><pre>
Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
</pre></div>

<P>
You should avoid this sort of non-portable usage if you plan to
distribute your code: it's probably better to write C code like
<div class="verbatim"><pre>
#include &lt;X11/Xlib.h&gt;
</pre></div>

<P>
If you need to include header files from some other Python extension,
you can take advantage of the fact that header files are installed in a
consistent way by the Distutils <code class="du-command">install_header</code> command.  For
example, the Numerical Python header files are installed (on a standard
Unix installation) to <span class="file">/usr/local/include/python1.5/Numerical</span>.
(The exact location will differ according to your platform and Python
installation.)  Since the Python include
directory--<span class="file">/usr/local/include/python1.5</span> in this case--is always
included in the search path when building Python extensions, the best
approach is to write C code like
<div class="verbatim"><pre>
#include &lt;Numerical/arrayobject.h&gt;
</pre></div>
If you must put the <span class="file">Numerical</span> include directory right into your
header search path, though, you can find that directory using the
Distutils <tt class="module"><a href="module-distutils.sysconfig.html">distutils.sysconfig</a></tt> module:

<P>
<div class="verbatim"><pre>
from distutils.sysconfig import get_python_inc
incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
setup(...,
      Extension(..., include_dirs=[incdir]),
      )
</pre></div>

<P>
Even though this is quite portable--it will work on any Python
installation, regardless of platform--it's probably easier to just
write your C code in the sensible way.

<P>
You can define and undefine pre-processor macros with the
<code>define_macros</code> and <code>undef_macros</code> options.
<code>define_macros</code> takes a list of <code>(name, value)</code> tuples, where
<code>name</code> is the name of the macro to define (a string) and
<code>value</code> is its value: either a string or <code>None</code>.  (Defining a
macro <code>FOO</code> to <code>None</code> is the equivalent of a bare
<code>#define FOO</code> in your C source: with most compilers, this sets
<code>FOO</code> to the string <code>1</code>.)  <code>undef_macros</code> is just
a list of macros to undefine.

<P>
For example:

<P>
<div class="verbatim"><pre>
Extension(...,
          define_macros=[('NDEBUG', '1'),
                         ('HAVE_STRFTIME', None)],
          undef_macros=['HAVE_FOO', 'HAVE_BAR'])
</pre></div>

<P>
is the equivalent of having this at the top of every C source file:

<P>
<div class="verbatim"><pre>
#define NDEBUG 1
#define HAVE_STRFTIME
#undef HAVE_FOO
#undef HAVE_BAR
</pre></div>

<P>

<H2><A NAME="SECTION002340000000000000000">
2.3.4 Library options</A>
</H2>

<P>
You can also specify the libraries to link against when building your
extension, and the directories to search for those libraries.  The
<code>libraries</code> option is a list of libraries to link against,
<code>library_dirs</code> is a list of directories to search for libraries at 
link-time, and <code>runtime_library_dirs</code> is a list of directories to 
search for shared (dynamically loaded) libraries at run-time.

<P>
For example, if you need to link against libraries known to be in the
standard library search path on target systems

<P>
<div class="verbatim"><pre>
Extension(...,
          libraries=['gdbm', 'readline'])
</pre></div>

<P>
If you need to link with libraries in a non-standard location, you'll
have to include the location in <code>library_dirs</code>:

<P>
<div class="verbatim"><pre>
Extension(...,
          library_dirs=['/usr/X11R6/lib'],
          libraries=['X11', 'Xt'])
</pre></div>

<P>
(Again, this sort of non-portable construct should be avoided if you
intend to distribute your code.)

<P>
<b class="du-xxx">Should mention clib libraries here or somewhere else!</b>

<P>

<H2><A NAME="SECTION002350000000000000000">
2.3.5 Other options</A>
</H2>

<P>
There are still some other options which can be used to handle special
cases.

<P>
The <span class="du-option">extra_objects</span> option is a list of object files to be passed
to the linker. These files must not have extensions, as the default
extension for the compiler is used.

<P>
<span class="du-option">extra_compile_args</span> and <span class="du-option">extra_link_args</span> can be used
to specify additional command line options for the respective compiler and
linker command lines.

<P>
<span class="du-option">export_symbols</span> is only useful on Windows.  It can contain a list
of symbols (functions or variables) to be exported. This option
is not needed when building compiled extensions: Distutils 
will automatically add <code>initmodule</code>
to the list of exported symbols.

<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="2.2 Listing individual modules"
  href="listing-modules.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="2. Writing the Setup"
  href="setup-script.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="2.4 Installing Scripts"
  href="node10.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Distributing Python Modules</td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="listing-modules.html">2.2 Listing individual modules</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="setup-script.html">2. Writing the Setup</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node10.html">2.4 Installing Scripts</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="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="node10.html" />
	12	<link rel="prev" href="listing-modules.html" />
	13	<link rel="parent" href="setup-script.html" />
	14	<link rel="next" href="node10.html" />
	15	<meta name='aesop' content='information' />
	16	<title>2.3 Describing extension modules</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 Listing individual modules"
	24	href="listing-modules.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="2. Writing the Setup"
	27	href="setup-script.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="2.4 Installing Scripts"
	30	href="node10.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="listing-modules.html">2.2 Listing individual modules</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="setup-script.html">2. Writing the Setup</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="node10.html">2.4 Installing Scripts</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52	<div class='online-navigation'>
	53	<!--Table of Child-Links-->
	54	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
	55
	56	<UL CLASS="ChildLinks">
	57	<LI><A href="describing-extensions.html#SECTION002310000000000000000">2.3.1 Extension names and packages</a>
	58	<LI><A href="describing-extensions.html#SECTION002320000000000000000">2.3.2 Extension source files</a>
	59	<LI><A href="describing-extensions.html#SECTION002330000000000000000">2.3.3 Preprocessor options</a>
	60	<LI><A href="describing-extensions.html#SECTION002340000000000000000">2.3.4 Library options</a>
	61	<LI><A href="describing-extensions.html#SECTION002350000000000000000">2.3.5 Other options</a>
	62	</ul>
	63	<!--End of Table of Child-Links-->
	64	</div>
65	<HR>
66
67	<H1><A NAME="SECTION002300000000000000000"></A>
68	<A NAME="describing-extensions"></A>
69	<BR>
70	2.3 Describing extension modules
71	</H1>
72
73	<P>
74	Just as writing Python extension modules is a bit more complicated than
75	writing pure Python modules, describing them to the Distutils is a bit
76	more complicated. Unlike pure modules, it's not enough just to list
77	modules or packages and expect the Distutils to go out and find the
78	right files; you have to specify the extension name, source file(s), and
79	any compile/link requirements (include directories, libraries to link
80	with, etc.).
81
82	<P>
83	All of this is done through another keyword argument to
84	<tt class="function">setup()</tt>, the <span class="du-option">ext_modules</span> option. <span class="du-option">ext_modules</span>
85	is just a list of <tt class="class">Extension</tt> instances, each of which describes a
86	single extension module. Suppose your distribution includes a single
87	extension, called <tt class="module">foo</tt> and implemented by <span class="file">foo.c</span>. If no
88	additional instructions to the compiler/linker are needed, describing
89	this extension is quite simple:
90
91	<P>
92	<div class="verbatim"><pre>
93	Extension('foo', ['foo.c'])
94	</pre></div>
95
96	<P>
97	The <tt class="class">Extension</tt> class can be imported from
98	<tt class="module">distutils.core</tt> along with <tt class="function">setup()</tt>. Thus, the setup
99	script for a module distribution that contains only this one extension
100	and nothing else might be:
101
102	<P>
103	<div class="verbatim"><pre>
104	from distutils.core import setup, Extension
105	setup(name='foo',
106	version='1.0',
107	ext_modules=[Extension('foo', ['foo.c'])],
108	)
109	</pre></div>
110
111	<P>
112	The <tt class="class">Extension</tt> class (actually, the underlying extension-building
113	machinery implemented by the <code class="du-command">build_ext</code> command) supports a
114	great deal of flexibility in describing Python extensions, which is
115	explained in the following sections.
116
117	<P>
118
119	<H2><A NAME="SECTION002310000000000000000">
120	2.3.1 Extension names and packages</A>
121	</H2>
122
123	<P>
124	The first argument to the <tt class="class">Extension</tt> constructor is always the
125	name of the extension, including any package names. For example,
126
127	<P>
128	<div class="verbatim"><pre>
129	Extension('foo', ['src/foo1.c', 'src/foo2.c'])
130	</pre></div>
131
132	<P>
133	describes an extension that lives in the root package, while
134
135	<P>
136	<div class="verbatim"><pre>
137	Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
138	</pre></div>
139
140	<P>
141	describes the same extension in the <tt class="module">pkg</tt> package. The source
142	files and resulting object code are identical in both cases; the only
143	difference is where in the filesystem (and therefore where in Python's
144	namespace hierarchy) the resulting extension lives.
145
146	<P>
147	If you have a number of extensions all in the same package (or all under
148	the same base package), use the <span class="du-option">ext_package</span> keyword argument
149	to <tt class="function">setup()</tt>. For example,
150
151	<P>
152	<div class="verbatim"><pre>
153	setup(...
154	ext_package='pkg',
155	ext_modules=[Extension('foo', ['foo.c']),
156	Extension('subpkg.bar', ['bar.c'])],
157	)
158	</pre></div>
159
160	<P>
161	will compile <span class="file">foo.c</span> to the extension <tt class="module">pkg.foo</tt>, and
162	<span class="file">bar.c</span> to <tt class="module">pkg.subpkg.bar</tt>.
163
164	<P>
165
166	<H2><A NAME="SECTION002320000000000000000">
167	2.3.2 Extension source files</A>
168	</H2>
169
170	<P>
171	The second argument to the <tt class="class">Extension</tt> constructor is a list of
172	source files. Since the Distutils currently only support C, C++, and
173	Objective-C extensions, these are normally C/C++/Objective-C source
174	files. (Be sure to use appropriate extensions to distinguish C++ source files: <span class="file">.cc</span> and <span class="file">.cpp</span> seem to be recognized by both
175	<span class="Unix">Unix</span> and Windows compilers.)
176
177	<P>
178	However, you can also include SWIG interface (<span class="file">.i</span>) files in the
179	list; the <code class="du-command">build_ext</code> command knows how to deal with SWIG
180	extensions: it will run SWIG on the interface file and compile the
181	resulting C/C++ file into your extension.
182
183	<P>
184	<b class="du-xxx">SWIG support is rough around the edges and largely untested;
185	especially SWIG support for C++ extensions! Explain in more detail
186	here when the interface firms up.</b>
187
188	<P>
189	On some platforms, you can include non-source files that are processed
190	by the compiler and included in your extension. Currently, this just
191	means Windows message text (<span class="file">.mc</span>) files and resource definition
192	(<span class="file">.rc</span>) files for Visual C++. These will be compiled to binary resource
193	(<span class="file">.res</span>) files and linked into the executable.
194
195	<P>
196
197	<H2><A NAME="SECTION002330000000000000000">
198	2.3.3 Preprocessor options</A>
199	</H2>
200
201	<P>
202	Three optional arguments to <tt class="class">Extension</tt> will help if you need to
203	specify include directories to search or preprocessor macros to
204	define/undefine: <code>include_dirs</code>, <code>define_macros</code>, and
205	<code>undef_macros</code>.
206
207	<P>
208	For example, if your extension requires header files in the
209	<span class="file">include</span> directory under your distribution root, use the
210	<code>include_dirs</code> option:
211
212	<P>
213	<div class="verbatim"><pre>
214	Extension('foo', ['foo.c'], include_dirs=['include'])
215	</pre></div>
216
217	<P>
218	You can specify absolute directories there; if you know that your
219	extension will only be built on <span class="Unix">Unix</span> systems with X11R6 installed to
220	<span class="file">/usr</span>, you can get away with
221
222	<P>
223	<div class="verbatim"><pre>
224	Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
225	</pre></div>
226
227	<P>
228	You should avoid this sort of non-portable usage if you plan to
229	distribute your code: it's probably better to write C code like
230	<div class="verbatim"><pre>
231	#include <X11/Xlib.h>
232	</pre></div>
233
234	<P>
235	If you need to include header files from some other Python extension,
236	you can take advantage of the fact that header files are installed in a
237	consistent way by the Distutils <code class="du-command">install_header</code> command. For
238	example, the Numerical Python header files are installed (on a standard
239	Unix installation) to <span class="file">/usr/local/include/python1.5/Numerical</span>.
240	(The exact location will differ according to your platform and Python
241	installation.) Since the Python include
242	directory--<span class="file">/usr/local/include/python1.5</span> in this case--is always
243	included in the search path when building Python extensions, the best
244	approach is to write C code like
245	<div class="verbatim"><pre>
246	#include <Numerical/arrayobject.h>
247	</pre></div>
248	If you must put the <span class="file">Numerical</span> include directory right into your
249	header search path, though, you can find that directory using the
250	Distutils <tt class="module"><a href="module-distutils.sysconfig.html">distutils.sysconfig</a></tt> module:
251
252	<P>
253	<div class="verbatim"><pre>
254	from distutils.sysconfig import get_python_inc
255	incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
256	setup(...,
257	Extension(..., include_dirs=[incdir]),
258	)
259	</pre></div>
260
261	<P>
262	Even though this is quite portable--it will work on any Python
263	installation, regardless of platform--it's probably easier to just
264	write your C code in the sensible way.
265
266	<P>
267	You can define and undefine pre-processor macros with the
268	<code>define_macros</code> and <code>undef_macros</code> options.
269	<code>define_macros</code> takes a list of <code>(name, value)</code> tuples, where
270	<code>name</code> is the name of the macro to define (a string) and
271	<code>value</code> is its value: either a string or <code>None</code>. (Defining a
272	macro <code>FOO</code> to <code>None</code> is the equivalent of a bare
273	<code>#define FOO</code> in your C source: with most compilers, this sets
274	<code>FOO</code> to the string <code>1</code>.) <code>undef_macros</code> is just
275	a list of macros to undefine.
276
277	<P>
278	For example:
279
280	<P>
281	<div class="verbatim"><pre>
282	Extension(...,
283	define_macros=[('NDEBUG', '1'),
284	('HAVE_STRFTIME', None)],
285	undef_macros=['HAVE_FOO', 'HAVE_BAR'])
286	</pre></div>
287
288	<P>
289	is the equivalent of having this at the top of every C source file:
290
291	<P>
292	<div class="verbatim"><pre>
293	#define NDEBUG 1
294	#define HAVE_STRFTIME
295	#undef HAVE_FOO
296	#undef HAVE_BAR
297	</pre></div>
298
299	<P>
300
301	<H2><A NAME="SECTION002340000000000000000">
302	2.3.4 Library options</A>
303	</H2>
304
305	<P>
306	You can also specify the libraries to link against when building your
307	extension, and the directories to search for those libraries. The
308	<code>libraries</code> option is a list of libraries to link against,
309	<code>library_dirs</code> is a list of directories to search for libraries at
310	link-time, and <code>runtime_library_dirs</code> is a list of directories to
311	search for shared (dynamically loaded) libraries at run-time.
312
313	<P>
314	For example, if you need to link against libraries known to be in the
315	standard library search path on target systems
316
317	<P>
318	<div class="verbatim"><pre>
319	Extension(...,
320	libraries=['gdbm', 'readline'])
321	</pre></div>
322
323	<P>
324	If you need to link with libraries in a non-standard location, you'll
325	have to include the location in <code>library_dirs</code>:
326
327	<P>
328	<div class="verbatim"><pre>
329	Extension(...,
330	library_dirs=['/usr/X11R6/lib'],
331	libraries=['X11', 'Xt'])
332	</pre></div>
333
334	<P>
335	(Again, this sort of non-portable construct should be avoided if you
336	intend to distribute your code.)
337
338	<P>
339	<b class="du-xxx">Should mention clib libraries here or somewhere else!</b>
340
341	<P>
342
343	<H2><A NAME="SECTION002350000000000000000">
344	2.3.5 Other options</A>
345	</H2>
346
347	<P>
348	There are still some other options which can be used to handle special
349	cases.
350
351	<P>
352	The <span class="du-option">extra_objects</span> option is a list of object files to be passed
353	to the linker. These files must not have extensions, as the default
354	extension for the compiler is used.
355
356	<P>
357	<span class="du-option">extra_compile_args</span> and <span class="du-option">extra_link_args</span> can be used
358	to specify additional command line options for the respective compiler and
359	linker command lines.
360
361	<P>
362	<span class="du-option">export_symbols</span> is only useful on Windows. It can contain a list
363	of symbols (functions or variables) to be exported. This option
364	is not needed when building compiled extensions: Distutils
365	will automatically add <code>initmodule</code>
366	to the list of exported symbols.
367
368	<P>
369
370	<DIV CLASS="navigation">
371	<div class='online-navigation'>
372	<p></p><hr />
373	<table align="center" width="100%" cellpadding="0" cellspacing="2">
374	<tr>
375	<td class='online-navigation'><a rel="prev" title="2.2 Listing individual modules"
376	href="listing-modules.html"><img src='../icons/previous.png'
377	border='0' height='32' alt='Previous Page' width='32' /></A></td>
378	<td class='online-navigation'><a rel="parent" title="2. Writing the Setup"
379	href="setup-script.html"><img src='../icons/up.png'
380	border='0' height='32' alt='Up One Level' width='32' /></A></td>
381	<td class='online-navigation'><a rel="next" title="2.4 Installing Scripts"
382	href="node10.html"><img src='../icons/next.png'
383	border='0' height='32' alt='Next Page' width='32' /></A></td>
384	<td align="center" width="100%">Distributing Python Modules</td>
385	<td class='online-navigation'><img src='../icons/blank.png'
386	border='0' height='32' alt='' width='32' /></td>
387	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
388	border='0' height='32' alt='Module Index' width='32' /></a></td>
389	<td class='online-navigation'><a rel="index" title="Index"
390	href="genindex.html"><img src='../icons/index.png'
391	border='0' height='32' alt='Index' width='32' /></A></td>
392	</tr></table>
393	<div class='online-navigation'>
394	<b class="navlabel">Previous:</b>
395	<a class="sectref" rel="prev" href="listing-modules.html">2.2 Listing individual modules</A>
396	<b class="navlabel">Up:</b>
397	<a class="sectref" rel="parent" href="setup-script.html">2. Writing the Setup</A>
398	<b class="navlabel">Next:</b>
399	<a class="sectref" rel="next" href="node10.html">2.4 Installing Scripts</A>
400	</div>
401	</div>
402	<hr />
403	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
404	</DIV>
405	<!--End of Navigation Panel-->
406	<ADDRESS>
407	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
408	</ADDRESS>
409	</BODY>
410	</HTML>