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