projects / OpenSPARC-T2-SAM / blame
| 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="module-distutils.ccompiler.html" /> | |
| 12 | <link rel="prev" href="api-reference.html" /> | |
| 13 | <link rel="parent" href="api-reference.html" /> | |
| 14 | <link rel="next" href="module-distutils.ccompiler.html" /> | |
| 15 | <meta name='aesop' content='information' /> | |
| 16 | <title>10.1 distutils.core -- Core Distutils functionality</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="10. API Reference" | |
| 24 | href="api-reference.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="10. API Reference" | |
| 27 | href="api-reference.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="10.2 distutils.ccompiler " | |
| 30 | href="module-distutils.ccompiler.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="api-reference.html">10. API Reference</A> | |
| 44 | <b class="navlabel">Up:</b> | |
| 45 | <a class="sectref" rel="parent" href="api-reference.html">10. API Reference</A> | |
| 46 | <b class="navlabel">Next:</b> | |
| 47 | <a class="sectref" rel="next" href="module-distutils.ccompiler.html">10.2 distutils.ccompiler </A> | |
| 48 | </div> | |
| 49 | <hr /></div> | |
| 50 | </DIV> | |
| 51 | <!--End of Navigation Panel--> | |
| 52 | ||
| 53 | <H1><A NAME="SECTION0010100000000000000000"> | |
| 54 | 10.1 <tt class="module">distutils.core</tt> -- Core Distutils functionality</A> | |
| 55 | </H1> | |
| 56 | ||
| 57 | <P> | |
| 58 | <A NAME="module-distutils.core"></A> | |
| 59 | ||
| 60 | <P> | |
| 61 | The <tt class="module">distutils.core</tt> module is the only module that needs to be | |
| 62 | installed to use the Distutils. It provides the <tt class="function">setup()</tt> (which | |
| 63 | is called from the setup script). Indirectly provides the | |
| 64 | <tt class="class">distutils.dist.Distribution</tt> and <tt class="class">distutils.cmd.Command</tt> class. | |
| 65 | ||
| 66 | <P> | |
| 67 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
| 68 | <td><nobr><b><tt id='l2h-6' xml:id='l2h-6' class="function">setup</tt></b>(</nobr></td> | |
| 69 | <td><var>arguments</var>)</td></tr></table></dt> | |
| 70 | <dd> | |
| 71 | The basic do-everything function that does most everything you could ever | |
| 72 | ask for from a Distutils method. See XXXXX | |
| 73 | ||
| 74 | <P> | |
| 75 | The setup function takes a large number of arguments. These | |
| 76 | are laid out in the following table. | |
| 77 | ||
| 78 | <P> | |
| 79 | <div class="center"><table class="realtable"> | |
| 80 | <thead> | |
| 81 | <tr> | |
| 82 | <th class="center">argument name</th> | |
| 83 | <th class="left" >value</th> | |
| 84 | <th class="left" >type</th> | |
| 85 | </tr> | |
| 86 | </thead> | |
| 87 | <tbody> | |
| 88 | <tr><td class="center" valign="baseline"><argument name>name</argument></td> | |
| 89 | <td class="left" >The name of the package</td> | |
| 90 | <td class="left" >a string</td></tr> | |
| 91 | <tr><td class="center" valign="baseline"><argument name>version</argument></td> | |
| 92 | <td class="left" >The version number of the package</td> | |
| 93 | <td class="left" >See <tt class="module"><a href="module-distutils.version.html">distutils.version</a></tt></td></tr> | |
| 94 | <tr><td class="center" valign="baseline"><argument name>description</argument></td> | |
| 95 | <td class="left" >A single line describing the package</td> | |
| 96 | <td class="left" >a string</td></tr> | |
| 97 | <tr><td class="center" valign="baseline"><argument name>long_description</argument></td> | |
| 98 | <td class="left" >Longer description of the package</td> | |
| 99 | <td class="left" >a string</td></tr> | |
| 100 | <tr><td class="center" valign="baseline"><argument name>author</argument></td> | |
| 101 | <td class="left" >The name of the package author</td> | |
| 102 | <td class="left" >a string</td></tr> | |
| 103 | <tr><td class="center" valign="baseline"><argument name>author_email</argument></td> | |
| 104 | <td class="left" >The email address of the package author</td> | |
| 105 | <td class="left" >a string</td></tr> | |
| 106 | <tr><td class="center" valign="baseline"><argument name>maintainer</argument></td> | |
| 107 | <td class="left" >The name of the current maintainer, if different from the author</td> | |
| 108 | <td class="left" >a string</td></tr> | |
| 109 | <tr><td class="center" valign="baseline"><argument name>maintainer_email</argument></td> | |
| 110 | <td class="left" >The email address of the current maintainer, if different from the author</td> | |
| 111 | <td class="left" ></td></tr> | |
| 112 | <tr><td class="center" valign="baseline"><argument name>url</argument></td> | |
| 113 | <td class="left" >A URL for the package (homepage)</td> | |
| 114 | <td class="left" >a URL</td></tr> | |
| 115 | <tr><td class="center" valign="baseline"><argument name>download_url</argument></td> | |
| 116 | <td class="left" >A URL to download the package</td> | |
| 117 | <td class="left" >a URL</td></tr> | |
| 118 | <tr><td class="center" valign="baseline"><argument name>packages</argument></td> | |
| 119 | <td class="left" >A list of Python packages that distutils will manipulate</td> | |
| 120 | <td class="left" >a list of strings</td></tr> | |
| 121 | <tr><td class="center" valign="baseline"><argument name>py_modules</argument></td> | |
| 122 | <td class="left" >A list of Python modules that distutils will manipulate</td> | |
| 123 | <td class="left" >a list of strings</td></tr> | |
| 124 | <tr><td class="center" valign="baseline"><argument name>scripts</argument></td> | |
| 125 | <td class="left" >A list of standalone script files to be built and installed</td> | |
| 126 | <td class="left" >a list of strings</td></tr> | |
| 127 | <tr><td class="center" valign="baseline"><argument name>ext_modules</argument></td> | |
| 128 | <td class="left" >A list of Python extensions to be built</td> | |
| 129 | <td class="left" >A list of | |
| 130 | instances of <tt class="class">distutils.core.Extension</tt></td></tr> | |
| 131 | <tr><td class="center" valign="baseline"><argument name>classifiers</argument></td> | |
| 132 | <td class="left" >A list of Trove categories for the package</td> | |
| 133 | <td class="left" >XXX link to better definition</td></tr> | |
| 134 | <tr><td class="center" valign="baseline"><argument name>distclass</argument></td> | |
| 135 | <td class="left" >the <tt class="class">Distribution</tt> class to use</td> | |
| 136 | <td class="left" >A subclass of <tt class="class">distutils.core.Distribution</tt></td></tr> | |
| 137 | <tr><td class="center" valign="baseline"><argument name>script_name</argument></td> | |
| 138 | <td class="left" >The name of the setup.py script - defaults to <code>sys.argv[0]</code></td> | |
| 139 | <td class="left" >a string</td></tr> | |
| 140 | <tr><td class="center" valign="baseline"><argument name>script_args</argument></td> | |
| 141 | <td class="left" >Arguments to supply to the setup script</td> | |
| 142 | <td class="left" >a list of strings</td></tr> | |
| 143 | <tr><td class="center" valign="baseline"><argument name>options</argument></td> | |
| 144 | <td class="left" >default options for the setup script</td> | |
| 145 | <td class="left" >a string</td></tr> | |
| 146 | <tr><td class="center" valign="baseline"><argument name>license</argument></td> | |
| 147 | <td class="left" >The license for the package</td> | |
| 148 | <td class="left" ></td></tr> | |
| 149 | <tr><td class="center" valign="baseline"><argument name>keywords</argument></td> | |
| 150 | <td class="left" >Descriptive meta-data. See <a class="rfc" id='rfcref-5120' xml:id='rfcref-5120' | |
| 151 | href="http://www.python.org/peps/pep-0314.html">PEP 314</a></td> | |
| 152 | <td class="left" ></td></tr> | |
| 153 | <tr><td class="center" valign="baseline"><argument name>platforms</argument></td> | |
| 154 | <td class="left" ></td> | |
| 155 | <td class="left" ></td></tr> | |
| 156 | <tr><td class="center" valign="baseline"><argument name>cmdclass</argument></td> | |
| 157 | <td class="left" >A mapping of command names to <tt class="class">Command</tt> subclasses</td> | |
| 158 | <td class="left" >a dictionary</td></tr></tbody> | |
| 159 | </table></div> | |
| 160 | ||
| 161 | <P> | |
| 162 | </dl> | |
| 163 | ||
| 164 | <P> | |
| 165 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
| 166 | <td><nobr><b><tt id='l2h-7' xml:id='l2h-7' class="function">run_setup</tt></b>(</nobr></td> | |
| 167 | <td><var>script_name</var><big>[</big><var>, script_args=<code>None</code>, stop_after=<code>'run'</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
| 168 | <dd> | |
| 169 | Run a setup script in a somewhat controlled environment, and return | |
| 170 | the <tt class="class">distutils.dist.Distribution</tt> instance that drives things. | |
| 171 | This is useful if you need to find out the distribution meta-data | |
| 172 | (passed as keyword args from <var>script</var> to <tt class="function">setup()</tt>), or | |
| 173 | the contents of the config files or command-line. | |
| 174 | ||
| 175 | <P> | |
| 176 | <var>script_name</var> is a file that will be run with <tt class="function">execfile()</tt> | |
| 177 | <code>sys.argv[0]</code> will be replaced with <var>script</var> for the duration of the | |
| 178 | call. <var>script_args</var> is a list of strings; if supplied, | |
| 179 | <code>sys.argv[1:]</code> will be replaced by <var>script_args</var> for the duration | |
| 180 | of the call. | |
| 181 | ||
| 182 | <P> | |
| 183 | <var>stop_after</var> tells <tt class="function">setup()</tt> when to stop processing; possible | |
| 184 | values: | |
| 185 | ||
| 186 | <P> | |
| 187 | <div class="center"><table class="realtable"> | |
| 188 | <thead> | |
| 189 | <tr> | |
| 190 | <th class="center">value</th> | |
| 191 | <th class="left" >description</th> | |
| 192 | </tr> | |
| 193 | </thead> | |
| 194 | <tbody> | |
| 195 | <tr><td class="center" valign="baseline"><argument name>init</argument></td> | |
| 196 | <td class="left" >Stop after the <tt class="class">Distribution</tt> instance has been created | |
| 197 | and populated with the keyword arguments to <tt class="function">setup()</tt></td></tr> | |
| 198 | <tr><td class="center" valign="baseline"><argument name>config</argument></td> | |
| 199 | <td class="left" >Stop after config files have been parsed (and their data | |
| 200 | stored in the <tt class="class">Distribution</tt> instance)</td></tr> | |
| 201 | <tr><td class="center" valign="baseline"><argument name>commandline</argument></td> | |
| 202 | <td class="left" >Stop after the command-line (<code>sys.argv[1:]</code> or | |
| 203 | <var>script_args</var>) have been parsed (and the data stored in the | |
| 204 | <tt class="class">Distribution</tt> instance.)</td></tr> | |
| 205 | <tr><td class="center" valign="baseline"><argument name>run</argument></td> | |
| 206 | <td class="left" >Stop after all commands have been run (the same as | |
| 207 | if <tt class="function">setup()</tt> had been called in the usual way). This is the default | |
| 208 | value.</td></tr></tbody> | |
| 209 | </table></div> | |
| 210 | </dl> | |
| 211 | ||
| 212 | <P> | |
| 213 | In addition, the <tt class="module">distutils.core</tt> module exposed a number of | |
| 214 | classes that live elsewhere. | |
| 215 | ||
| 216 | <P> | |
| 217 | ||
| 218 | <UL> | |
| 219 | <LI><tt class="class">Extension</tt> from <tt class="module"><a href="module-distutils.extension.html">distutils.extension</a></tt> | |
| 220 | </LI> | |
| 221 | <LI><tt class="class">Command</tt> from <tt class="module"><a href="module-distutils.cmd.html">distutils.cmd</a></tt> | |
| 222 | </LI> | |
| 223 | <LI><tt class="class">Distribution</tt> from <tt class="module"><a href="module-distutils.dist.html">distutils.dist</a></tt> | |
| 224 | </LI> | |
| 225 | </UL> | |
| 226 | ||
| 227 | <P> | |
| 228 | A short description of each of these follows, but see the relevant | |
| 229 | module for the full reference. | |
| 230 | ||
| 231 | <P> | |
| 232 | <dl><dt><b><span class="typelabel">class</span> <tt id='l2h-8' xml:id='l2h-8' class="class">Extension</tt></b> | |
| 233 | <dd> | |
| 234 | ||
| 235 | <P> | |
| 236 | The Extension class describes a single C or C++extension module in a | |
| 237 | setup script. It accepts the following keyword arguments in its | |
| 238 | constructor | |
| 239 | ||
| 240 | <P> | |
| 241 | <div class="center"><table class="realtable"> | |
| 242 | <thead> | |
| 243 | <tr> | |
| 244 | <th class="center">argument name</th> | |
| 245 | <th class="left" >value</th> | |
| 246 | <th class="left" >type</th> | |
| 247 | </tr> | |
| 248 | </thead> | |
| 249 | <tbody> | |
| 250 | <tr><td class="center" valign="baseline"><argument name>name</argument></td> | |
| 251 | <td class="left" >the full name of the extension, including any packages | |
| 252 | -- ie. <em>not</em> a filename or pathname, but Python dotted name</td> | |
| 253 | <td class="left" >string</td></tr> | |
| 254 | <tr><td class="center" valign="baseline"><argument name>sources</argument></td> | |
| 255 | <td class="left" >list of source filenames, relative to the distribution | |
| 256 | root (where the setup script lives), in Unix form (slash-separated) for | |
| 257 | portability. Source files may be C, C++, SWIG (.i), platform-specific | |
| 258 | resource files, or whatever else is recognized by the <code class="du-command">build_ext</code> | |
| 259 | command as source for a Python extension.</td> | |
| 260 | <td class="left" >string</td></tr> | |
| 261 | <tr><td class="center" valign="baseline"><argument name>include_dirs</argument></td> | |
| 262 | <td class="left" >list of directories to search for C/C++ header | |
| 263 | files (in <span class="Unix">Unix</span> form for portability)</td> | |
| 264 | <td class="left" >string</td></tr> | |
| 265 | <tr><td class="center" valign="baseline"><argument name>define_macros</argument></td> | |
| 266 | <td class="left" >list of macros to define; each macro is defined | |
| 267 | using a 2-tuple, where 'value' is either the string to define it to or | |
| 268 | <code>None</code> to define it without a particular value (equivalent of | |
| 269 | <code>#define FOO</code> in source or <b class="programopt">-DFOO</b> on <span class="Unix">Unix</span> C | |
| 270 | compiler command line) </td> | |
| 271 | <td class="left" > (string,string) | |
| 272 | tuple or (name,<code>None</code>) </td></tr> | |
| 273 | <tr><td class="center" valign="baseline"><argument name>undef_macros</argument></td> | |
| 274 | <td class="left" >list of macros to undefine explicitly</td> | |
| 275 | <td class="left" >string</td></tr> | |
| 276 | <tr><td class="center" valign="baseline"><argument name>library_dirs</argument></td> | |
| 277 | <td class="left" >list of directories to search for C/C++ libraries | |
| 278 | at link time </td> | |
| 279 | <td class="left" >string</td></tr> | |
| 280 | <tr><td class="center" valign="baseline"><argument name>libraries</argument></td> | |
| 281 | <td class="left" >list of library names (not filenames or paths) to | |
| 282 | link against </td> | |
| 283 | <td class="left" >string</td></tr> | |
| 284 | <tr><td class="center" valign="baseline"><argument name>runtime_library_dirs</argument></td> | |
| 285 | <td class="left" >list of directories to search for C/C++ | |
| 286 | libraries at run time (for shared extensions, this is when the extension | |
| 287 | is loaded)</td> | |
| 288 | <td class="left" >string</td></tr> | |
| 289 | <tr><td class="center" valign="baseline"><argument name>extra_objects</argument></td> | |
| 290 | <td class="left" >list of extra files to link with (eg. object | |
| 291 | files not implied by 'sources', static library that must be explicitly | |
| 292 | specified, binary resource files, etc.)</td> | |
| 293 | <td class="left" >string</td></tr> | |
| 294 | <tr><td class="center" valign="baseline"><argument name>extra_compile_args</argument></td> | |
| 295 | <td class="left" >any extra platform- and compiler-specific | |
| 296 | information to use when compiling the source files in 'sources'. For | |
| 297 | platforms and compilers where a command line makes sense, this is | |
| 298 | typically a list of command-line arguments, but for other platforms it | |
| 299 | could be anything.</td> | |
| 300 | <td class="left" >string</td></tr> | |
| 301 | <tr><td class="center" valign="baseline"><argument name>extra_link_args</argument></td> | |
| 302 | <td class="left" >any extra platform- and compiler-specific | |
| 303 | information to use when linking object files together to create the | |
| 304 | extension (or to create a new static Python interpreter). Similar | |
| 305 | interpretation as for 'extra_compile_args'.</td> | |
| 306 | <td class="left" >string</td></tr> | |
| 307 | <tr><td class="center" valign="baseline"><argument name>export_symbols</argument></td> | |
| 308 | <td class="left" >list of symbols to be exported from a shared | |
| 309 | extension. Not used on all platforms, and not generally necessary for | |
| 310 | Python extensions, which typically export exactly one symbol: <code>init</code> + | |
| 311 | extension_name. </td> | |
| 312 | <td class="left" >string</td></tr> | |
| 313 | <tr><td class="center" valign="baseline"><argument name>depends</argument></td> | |
| 314 | <td class="left" >list of files that the extension depends on </td> | |
| 315 | <td class="left" >string</td></tr> | |
| 316 | <tr><td class="center" valign="baseline"><argument name>language</argument></td> | |
| 317 | <td class="left" >extension language (i.e. <code>'c'</code>, <code>'c++'</code>, | |
| 318 | <code>'objc'</code>). Will be detected from the source extensions if not provided. | |
| 319 | </td> | |
| 320 | <td class="left" >string</td></tr></tbody> | |
| 321 | </table></div> | |
| 322 | </dl> | |
| 323 | ||
| 324 | <P> | |
| 325 | <dl><dt><b><span class="typelabel">class</span> <tt id='l2h-9' xml:id='l2h-9' class="class">Distribution</tt></b> | |
| 326 | <dd> | |
| 327 | A <tt class="class">Distribution</tt> describes how to build, install and package up a | |
| 328 | Python software package. | |
| 329 | ||
| 330 | <P> | |
| 331 | See the <tt class="function">setup()</tt> function for a list of keyword arguments accepted | |
| 332 | by the Distribution constructor. <tt class="function">setup()</tt> creates a Distribution | |
| 333 | instance. | |
| 334 | </dl> | |
| 335 | ||
| 336 | <P> | |
| 337 | <dl><dt><b><span class="typelabel">class</span> <tt id='l2h-10' xml:id='l2h-10' class="class">Command</tt></b> | |
| 338 | <dd> | |
| 339 | A <tt class="class">Command</tt> class (or rather, an instance of one of its subclasses) | |
| 340 | implement a single distutils command. | |
| 341 | </dl> | |
| 342 | ||
| 343 | <P> | |
| 344 | ||
| 345 | <DIV CLASS="navigation"> | |
| 346 | <div class='online-navigation'> | |
| 347 | <p></p><hr /> | |
| 348 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
| 349 | <tr> | |
| 350 | <td class='online-navigation'><a rel="prev" title="10. API Reference" | |
| 351 | href="api-reference.html"><img src='../icons/previous.png' | |
| 352 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
| 353 | <td class='online-navigation'><a rel="parent" title="10. API Reference" | |
| 354 | href="api-reference.html"><img src='../icons/up.png' | |
| 355 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
| 356 | <td class='online-navigation'><a rel="next" title="10.2 distutils.ccompiler " | |
| 357 | href="module-distutils.ccompiler.html"><img src='../icons/next.png' | |
| 358 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
| 359 | <td align="center" width="100%">Distributing Python Modules</td> | |
| 360 | <td class='online-navigation'><img src='../icons/blank.png' | |
| 361 | border='0' height='32' alt='' width='32' /></td> | |
| 362 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
| 363 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
| 364 | <td class='online-navigation'><a rel="index" title="Index" | |
| 365 | href="genindex.html"><img src='../icons/index.png' | |
| 366 | border='0' height='32' alt='Index' width='32' /></A></td> | |
| 367 | </tr></table> | |
| 368 | <div class='online-navigation'> | |
| 369 | <b class="navlabel">Previous:</b> | |
| 370 | <a class="sectref" rel="prev" href="api-reference.html">10. API Reference</A> | |
| 371 | <b class="navlabel">Up:</b> | |
| 372 | <a class="sectref" rel="parent" href="api-reference.html">10. API Reference</A> | |
| 373 | <b class="navlabel">Next:</b> | |
| 374 | <a class="sectref" rel="next" href="module-distutils.ccompiler.html">10.2 distutils.ccompiler </A> | |
| 375 | </div> | |
| 376 | </div> | |
| 377 | <hr /> | |
| 378 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
| 379 | </DIV> | |
| 380 | <!--End of Navigation Panel--> | |
| 381 | <ADDRESS> | |
| 382 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
| 383 | </ADDRESS> | |
| 384 | </BODY> | |
| 385 | </HTML> |