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