Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | .. highlightlang:: none |
| 2 | |
| 3 | .. _install-index: |
| 4 | |
| 5 | ***************************** |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 6 | Installing Python Modules |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | ***************************** |
| 8 | |
| 9 | :Author: Greg Ward |
| 10 | :Release: |version| |
| 11 | :Date: |today| |
| 12 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 13 | .. TODO: Fill in XXX comments |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 15 | .. The audience for this document includes people who don't know anything |
| 16 | about Python and aren't about to learn the language just in order to |
| 17 | install and maintain it for their users, i.e. system administrators. |
| 18 | Thus, I have to be sure to explain the basics at some point: |
| 19 | sys.path and PYTHONPATH at least. Should probably give pointers to |
| 20 | other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 21 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 22 | Finally, it might be useful to include all the material from my "Care |
| 23 | and Feeding of a Python Installation" talk in here somewhere. Yow! |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | |
| 25 | .. topic:: Abstract |
| 26 | |
| 27 | This document describes the Python Distribution Utilities ("Distutils") from the |
| 28 | end-user's point-of-view, describing how to extend the capabilities of a |
| 29 | standard Python installation by building and installing third-party Python |
| 30 | modules and extensions. |
| 31 | |
| 32 | |
| 33 | .. _inst-intro: |
| 34 | |
| 35 | Introduction |
| 36 | ============ |
| 37 | |
| 38 | Although Python's extensive standard library covers many programming needs, |
| 39 | there often comes a time when you need to add some new functionality to your |
| 40 | Python installation in the form of third-party modules. This might be necessary |
| 41 | to support your own programming, or to support an application that you want to |
| 42 | use and that happens to be written in Python. |
| 43 | |
| 44 | In the past, there has been little support for adding third-party modules to an |
| 45 | existing Python installation. With the introduction of the Python Distribution |
| 46 | Utilities (Distutils for short) in Python 2.0, this changed. |
| 47 | |
| 48 | This document is aimed primarily at the people who need to install third-party |
| 49 | Python modules: end-users and system administrators who just need to get some |
| 50 | Python application running, and existing Python programmers who want to add some |
| 51 | new goodies to their toolbox. You don't need to know Python to read this |
| 52 | document; there will be some brief forays into using Python's interactive mode |
| 53 | to explore your installation, but that's it. If you're looking for information |
| 54 | on how to distribute your own Python modules so that others may use them, see |
| 55 | the :ref:`distutils-index` manual. |
| 56 | |
| 57 | |
| 58 | .. _inst-trivial-install: |
| 59 | |
| 60 | Best case: trivial installation |
| 61 | ------------------------------- |
| 62 | |
| 63 | In the best case, someone will have prepared a special version of the module |
| 64 | distribution you want to install that is targeted specifically at your platform |
| 65 | and is installed just like any other software on your platform. For example, |
| 66 | the module developer might make an executable installer available for Windows |
| 67 | users, an RPM package for users of RPM-based Linux systems (Red Hat, SuSE, |
| 68 | Mandrake, and many others), a Debian package for users of Debian-based Linux |
| 69 | systems, and so forth. |
| 70 | |
| 71 | In that case, you would download the installer appropriate to your platform and |
| 72 | do the obvious thing with it: run it if it's an executable installer, ``rpm |
| 73 | --install`` it if it's an RPM, etc. You don't need to run Python or a setup |
| 74 | script, you don't need to compile anything---you might not even need to read any |
| 75 | instructions (although it's always a good idea to do so anyways). |
| 76 | |
| 77 | Of course, things will not always be that easy. You might be interested in a |
| 78 | module distribution that doesn't have an easy-to-use installer for your |
| 79 | platform. In that case, you'll have to start with the source distribution |
| 80 | released by the module's author/maintainer. Installing from a source |
| 81 | distribution is not too hard, as long as the modules are packaged in the |
| 82 | standard way. The bulk of this document is about building and installing |
| 83 | modules from standard source distributions. |
| 84 | |
| 85 | |
| 86 | .. _inst-new-standard: |
| 87 | |
| 88 | The new standard: Distutils |
| 89 | --------------------------- |
| 90 | |
| 91 | If you download a module source distribution, you can tell pretty quickly if it |
| 92 | was packaged and distributed in the standard way, i.e. using the Distutils. |
| 93 | First, the distribution's name and version number will be featured prominently |
| 94 | in the name of the downloaded archive, e.g. :file:`foo-1.0.tar.gz` or |
| 95 | :file:`widget-0.9.7.zip`. Next, the archive will unpack into a similarly-named |
| 96 | directory: :file:`foo-1.0` or :file:`widget-0.9.7`. Additionally, the |
| 97 | distribution will contain a setup script :file:`setup.py`, and a file named |
| 98 | :file:`README.txt` or possibly just :file:`README`, which should explain that |
Éric Araujo | 577a6af | 2011-06-09 16:28:19 +0200 | [diff] [blame^] | 99 | building and installing the module distribution is a simple matter of running |
| 100 | one command from a terminal:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 101 | |
| 102 | python setup.py install |
| 103 | |
Éric Araujo | 577a6af | 2011-06-09 16:28:19 +0200 | [diff] [blame^] | 104 | For Windows, this command should be run from a command prompt windows ("DOS |
| 105 | box"):: |
| 106 | |
| 107 | setup.py install |
| 108 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 109 | If all these things are true, then you already know how to build and install the |
| 110 | modules you've just downloaded: Run the command above. Unless you need to |
| 111 | install things in a non-standard way or customize the build process, you don't |
| 112 | really need this manual. Or rather, the above command is everything you need to |
| 113 | get out of this manual. |
| 114 | |
| 115 | |
| 116 | .. _inst-standard-install: |
| 117 | |
| 118 | Standard Build and Install |
| 119 | ========================== |
| 120 | |
| 121 | As described in section :ref:`inst-new-standard`, building and installing a module |
Éric Araujo | 577a6af | 2011-06-09 16:28:19 +0200 | [diff] [blame^] | 122 | distribution using the Distutils is usually one simple command to run from a |
| 123 | terminal:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 124 | |
| 125 | python setup.py install |
| 126 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 127 | |
| 128 | .. _inst-platform-variations: |
| 129 | |
| 130 | Platform variations |
| 131 | ------------------- |
| 132 | |
| 133 | You should always run the setup command from the distribution root directory, |
| 134 | i.e. the top-level subdirectory that the module source distribution unpacks |
| 135 | into. For example, if you've just downloaded a module source distribution |
| 136 | :file:`foo-1.0.tar.gz` onto a Unix system, the normal thing to do is:: |
| 137 | |
| 138 | gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0 |
| 139 | cd foo-1.0 |
| 140 | python setup.py install |
| 141 | |
| 142 | On Windows, you'd probably download :file:`foo-1.0.zip`. If you downloaded the |
| 143 | archive file to :file:`C:\\Temp`, then it would unpack into |
| 144 | :file:`C:\\Temp\\foo-1.0`; you can use either a archive manipulator with a |
| 145 | graphical user interface (such as WinZip) or a command-line tool (such as |
| 146 | :program:`unzip` or :program:`pkunzip`) to unpack the archive. Then, open a |
| 147 | command prompt window ("DOS box"), and run:: |
| 148 | |
| 149 | cd c:\Temp\foo-1.0 |
| 150 | python setup.py install |
| 151 | |
| 152 | |
| 153 | .. _inst-splitting-up: |
| 154 | |
| 155 | Splitting the job up |
| 156 | -------------------- |
| 157 | |
| 158 | Running ``setup.py install`` builds and installs all modules in one run. If you |
| 159 | prefer to work incrementally---especially useful if you want to customize the |
| 160 | build process, or if things are going wrong---you can use the setup script to do |
| 161 | one thing at a time. This is particularly helpful when the build and install |
| 162 | will be done by different users---for example, you might want to build a module |
| 163 | distribution and hand it off to a system administrator for installation (or do |
| 164 | it yourself, with super-user privileges). |
| 165 | |
| 166 | For example, you can build everything in one step, and then install everything |
| 167 | in a second step, by invoking the setup script twice:: |
| 168 | |
| 169 | python setup.py build |
| 170 | python setup.py install |
| 171 | |
| 172 | If you do this, you will notice that running the :command:`install` command |
| 173 | first runs the :command:`build` command, which---in this case---quickly notices |
| 174 | that it has nothing to do, since everything in the :file:`build` directory is |
| 175 | up-to-date. |
| 176 | |
| 177 | You may not need this ability to break things down often if all you do is |
| 178 | install modules downloaded off the 'net, but it's very handy for more advanced |
| 179 | tasks. If you get into distributing your own Python modules and extensions, |
| 180 | you'll run lots of individual Distutils commands on their own. |
| 181 | |
| 182 | |
| 183 | .. _inst-how-build-works: |
| 184 | |
| 185 | How building works |
| 186 | ------------------ |
| 187 | |
| 188 | As implied above, the :command:`build` command is responsible for putting the |
| 189 | files to install into a *build directory*. By default, this is :file:`build` |
| 190 | under the distribution root; if you're excessively concerned with speed, or want |
| 191 | to keep the source tree pristine, you can change the build directory with the |
| 192 | :option:`--build-base` option. For example:: |
| 193 | |
| 194 | python setup.py build --build-base=/tmp/pybuild/foo-1.0 |
| 195 | |
| 196 | (Or you could do this permanently with a directive in your system or personal |
| 197 | Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this |
| 198 | isn't necessary. |
| 199 | |
| 200 | The default layout for the build tree is as follows:: |
| 201 | |
| 202 | --- build/ --- lib/ |
| 203 | or |
| 204 | --- build/ --- lib.<plat>/ |
| 205 | temp.<plat>/ |
| 206 | |
| 207 | where ``<plat>`` expands to a brief description of the current OS/hardware |
| 208 | platform and Python version. The first form, with just a :file:`lib` directory, |
| 209 | is used for "pure module distributions"---that is, module distributions that |
| 210 | include only pure Python modules. If a module distribution contains any |
| 211 | extensions (modules written in C/C++), then the second form, with two ``<plat>`` |
| 212 | directories, is used. In that case, the :file:`temp.{plat}` directory holds |
| 213 | temporary files generated by the compile/link process that don't actually get |
| 214 | installed. In either case, the :file:`lib` (or :file:`lib.{plat}`) directory |
| 215 | contains all Python modules (pure Python and extensions) that will be installed. |
| 216 | |
| 217 | In the future, more directories will be added to handle Python scripts, |
| 218 | documentation, binary executables, and whatever else is needed to handle the job |
| 219 | of installing Python modules and applications. |
| 220 | |
| 221 | |
| 222 | .. _inst-how-install-works: |
| 223 | |
| 224 | How installation works |
| 225 | ---------------------- |
| 226 | |
| 227 | After the :command:`build` command runs (whether you run it explicitly, or the |
| 228 | :command:`install` command does it for you), the work of the :command:`install` |
| 229 | command is relatively simple: all it has to do is copy everything under |
| 230 | :file:`build/lib` (or :file:`build/lib.{plat}`) to your chosen installation |
| 231 | directory. |
| 232 | |
| 233 | If you don't choose an installation directory---i.e., if you just run ``setup.py |
| 234 | install``\ ---then the :command:`install` command installs to the standard |
| 235 | location for third-party Python modules. This location varies by platform and |
| 236 | by how you built/installed Python itself. On Unix (and Mac OS X, which is also |
| 237 | Unix-based), it also depends on whether the module distribution being installed |
| 238 | is pure Python or contains extensions ("non-pure"): |
| 239 | |
| 240 | +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ |
| 241 | | Platform | Standard installation location | Default value | Notes | |
| 242 | +=================+=====================================================+==================================================+=======+ |
| 243 | | Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | |
| 244 | +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ |
| 245 | | Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | |
| 246 | +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ |
Brian Curtin | 308053e | 2011-05-03 21:57:00 -0500 | [diff] [blame] | 247 | | Windows | :file:`{prefix}\\Lib\\site-packages` | :file:`C:\\Python{XY}\\Lib\\site-packages` | \(2) | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 248 | +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ |
| 249 | |
| 250 | Notes: |
| 251 | |
| 252 | (1) |
| 253 | Most Linux distributions include Python as a standard part of the system, so |
| 254 | :file:`{prefix}` and :file:`{exec-prefix}` are usually both :file:`/usr` on |
| 255 | Linux. If you build Python yourself on Linux (or any Unix-like system), the |
| 256 | default :file:`{prefix}` and :file:`{exec-prefix}` are :file:`/usr/local`. |
| 257 | |
| 258 | (2) |
| 259 | The default installation directory on Windows was :file:`C:\\Program |
| 260 | Files\\Python` under Python 1.6a1, 1.5.2, and earlier. |
| 261 | |
| 262 | :file:`{prefix}` and :file:`{exec-prefix}` stand for the directories that Python |
| 263 | is installed to, and where it finds its libraries at run-time. They are always |
| 264 | the same under Windows, and very often the same under Unix and Mac OS X. You |
| 265 | can find out what your Python installation uses for :file:`{prefix}` and |
| 266 | :file:`{exec-prefix}` by running Python in interactive mode and typing a few |
| 267 | simple commands. Under Unix, just type ``python`` at the shell prompt. Under |
| 268 | Windows, choose :menuselection:`Start --> Programs --> Python X.Y --> |
| 269 | Python (command line)`. Once the interpreter is started, you type Python code |
| 270 | at the prompt. For example, on my Linux system, I type the three Python |
| 271 | statements shown below, and get the output as shown, to find out my |
| 272 | :file:`{prefix}` and :file:`{exec-prefix}`:: |
| 273 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 274 | Python 2.4 (#26, Aug 7 2004, 17:19:02) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 275 | Type "help", "copyright", "credits" or "license" for more information. |
| 276 | >>> import sys |
| 277 | >>> sys.prefix |
| 278 | '/usr' |
| 279 | >>> sys.exec_prefix |
| 280 | '/usr' |
| 281 | |
| 282 | If you don't want to install modules to the standard location, or if you don't |
| 283 | have permission to write there, then you need to read about alternate |
| 284 | installations in section :ref:`inst-alt-install`. If you want to customize your |
| 285 | installation directories more heavily, see section :ref:`inst-custom-install` on |
| 286 | custom installations. |
| 287 | |
| 288 | |
| 289 | .. _inst-alt-install: |
| 290 | |
| 291 | Alternate Installation |
| 292 | ====================== |
| 293 | |
| 294 | Often, it is necessary or desirable to install modules to a location other than |
| 295 | the standard location for third-party Python modules. For example, on a Unix |
| 296 | system you might not have permission to write to the standard third-party module |
| 297 | directory. Or you might wish to try out a module before making it a standard |
| 298 | part of your local Python installation. This is especially true when upgrading |
| 299 | a distribution already present: you want to make sure your existing base of |
| 300 | scripts still works with the new version before actually upgrading. |
| 301 | |
| 302 | The Distutils :command:`install` command is designed to make installing module |
| 303 | distributions to an alternate location simple and painless. The basic idea is |
| 304 | that you supply a base directory for the installation, and the |
| 305 | :command:`install` command picks a set of directories (called an *installation |
| 306 | scheme*) under this base directory in which to install files. The details |
| 307 | differ across platforms, so read whichever of the following sections applies to |
| 308 | you. |
| 309 | |
| 310 | |
| 311 | .. _inst-alt-install-prefix: |
| 312 | |
| 313 | Alternate installation: the home scheme |
| 314 | --------------------------------------- |
| 315 | |
| 316 | The idea behind the "home scheme" is that you build and maintain a personal |
| 317 | stash of Python modules. This scheme's name is derived from the idea of a |
| 318 | "home" directory on Unix, since it's not unusual for a Unix user to make their |
| 319 | home directory have a layout similar to :file:`/usr/` or :file:`/usr/local/`. |
Georg Brandl | f6914aa | 2010-07-26 15:11:49 +0000 | [diff] [blame] | 320 | This scheme can be used by anyone, regardless of the operating system they |
| 321 | are installing for. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 322 | |
| 323 | Installing a new module distribution is as simple as :: |
| 324 | |
| 325 | python setup.py install --home=<dir> |
| 326 | |
| 327 | where you can supply any directory you like for the :option:`--home` option. On |
| 328 | Unix, lazy typists can just type a tilde (``~``); the :command:`install` command |
| 329 | will expand this to your home directory:: |
| 330 | |
| 331 | python setup.py install --home=~ |
| 332 | |
| 333 | The :option:`--home` option defines the installation base directory. Files are |
| 334 | installed to the following directories under the installation base as follows: |
| 335 | |
| 336 | +------------------------------+---------------------------+-----------------------------+ |
| 337 | | Type of file | Installation Directory | Override option | |
| 338 | +==============================+===========================+=============================+ |
| 339 | | pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` | |
| 340 | +------------------------------+---------------------------+-----------------------------+ |
| 341 | | non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` | |
| 342 | +------------------------------+---------------------------+-----------------------------+ |
| 343 | | scripts | :file:`{home}/bin` | :option:`--install-scripts` | |
| 344 | +------------------------------+---------------------------+-----------------------------+ |
| 345 | | data | :file:`{home}/share` | :option:`--install-data` | |
| 346 | +------------------------------+---------------------------+-----------------------------+ |
| 347 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 348 | |
| 349 | .. _inst-alt-install-home: |
| 350 | |
| 351 | Alternate installation: Unix (the prefix scheme) |
| 352 | ------------------------------------------------ |
| 353 | |
| 354 | The "prefix scheme" is useful when you wish to use one Python installation to |
| 355 | perform the build/install (i.e., to run the setup script), but install modules |
| 356 | into the third-party module directory of a different Python installation (or |
| 357 | something that looks like a different Python installation). If this sounds a |
| 358 | trifle unusual, it is---that's why the "home scheme" comes first. However, |
| 359 | there are at least two known cases where the prefix scheme will be useful. |
| 360 | |
| 361 | First, consider that many Linux distributions put Python in :file:`/usr`, rather |
| 362 | than the more traditional :file:`/usr/local`. This is entirely appropriate, |
| 363 | since in those cases Python is part of "the system" rather than a local add-on. |
| 364 | However, if you are installing Python modules from source, you probably want |
| 365 | them to go in :file:`/usr/local/lib/python2.{X}` rather than |
| 366 | :file:`/usr/lib/python2.{X}`. This can be done with :: |
| 367 | |
| 368 | /usr/bin/python setup.py install --prefix=/usr/local |
| 369 | |
| 370 | Another possibility is a network filesystem where the name used to write to a |
| 371 | remote directory is different from the name used to read it: for example, the |
| 372 | Python interpreter accessed as :file:`/usr/local/bin/python` might search for |
| 373 | modules in :file:`/usr/local/lib/python2.{X}`, but those modules would have to |
| 374 | be installed to, say, :file:`/mnt/{@server}/export/lib/python2.{X}`. This could |
| 375 | be done with :: |
| 376 | |
| 377 | /usr/local/bin/python setup.py install --prefix=/mnt/@server/export |
| 378 | |
| 379 | In either case, the :option:`--prefix` option defines the installation base, and |
| 380 | the :option:`--exec-prefix` option defines the platform-specific installation |
| 381 | base, which is used for platform-specific files. (Currently, this just means |
| 382 | non-pure module distributions, but could be expanded to C libraries, binary |
| 383 | executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to |
| 384 | :option:`--prefix`. Files are installed as follows: |
| 385 | |
| 386 | +------------------------------+-----------------------------------------------------+-----------------------------+ |
| 387 | | Type of file | Installation Directory | Override option | |
| 388 | +==============================+=====================================================+=============================+ |
| 389 | | pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` | |
| 390 | +------------------------------+-----------------------------------------------------+-----------------------------+ |
| 391 | | non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` | |
| 392 | +------------------------------+-----------------------------------------------------+-----------------------------+ |
| 393 | | scripts | :file:`{prefix}/bin` | :option:`--install-scripts` | |
| 394 | +------------------------------+-----------------------------------------------------+-----------------------------+ |
| 395 | | data | :file:`{prefix}/share` | :option:`--install-data` | |
| 396 | +------------------------------+-----------------------------------------------------+-----------------------------+ |
| 397 | |
| 398 | There is no requirement that :option:`--prefix` or :option:`--exec-prefix` |
| 399 | actually point to an alternate Python installation; if the directories listed |
| 400 | above do not already exist, they are created at installation time. |
| 401 | |
| 402 | Incidentally, the real reason the prefix scheme is important is simply that a |
| 403 | standard Unix installation uses the prefix scheme, but with :option:`--prefix` |
| 404 | and :option:`--exec-prefix` supplied by Python itself as ``sys.prefix`` and |
| 405 | ``sys.exec_prefix``. Thus, you might think you'll never use the prefix scheme, |
| 406 | but every time you run ``python setup.py install`` without any other options, |
| 407 | you're using it. |
| 408 | |
| 409 | Note that installing extensions to an alternate Python installation has no |
| 410 | effect on how those extensions are built: in particular, the Python header files |
| 411 | (:file:`Python.h` and friends) installed with the Python interpreter used to run |
| 412 | the setup script will be used in compiling extensions. It is your |
| 413 | responsibility to ensure that the interpreter used to run extensions installed |
| 414 | in this way is compatible with the interpreter used to build them. The best way |
| 415 | to do this is to ensure that the two interpreters are the same version of Python |
| 416 | (possibly different builds, or possibly copies of the same build). (Of course, |
| 417 | if your :option:`--prefix` and :option:`--exec-prefix` don't even point to an |
| 418 | alternate Python installation, this is immaterial.) |
| 419 | |
| 420 | |
| 421 | .. _inst-alt-install-windows: |
| 422 | |
| 423 | Alternate installation: Windows (the prefix scheme) |
| 424 | --------------------------------------------------- |
| 425 | |
| 426 | Windows has no concept of a user's home directory, and since the standard Python |
| 427 | installation under Windows is simpler than under Unix, the :option:`--prefix` |
| 428 | option has traditionally been used to install additional packages in separate |
| 429 | locations on Windows. :: |
| 430 | |
| 431 | python setup.py install --prefix="\Temp\Python" |
| 432 | |
| 433 | to install modules to the :file:`\\Temp\\Python` directory on the current drive. |
| 434 | |
| 435 | The installation base is defined by the :option:`--prefix` option; the |
| 436 | :option:`--exec-prefix` option is not supported under Windows. Files are |
| 437 | installed as follows: |
| 438 | |
| 439 | +------------------------------+---------------------------+-----------------------------+ |
| 440 | | Type of file | Installation Directory | Override option | |
| 441 | +==============================+===========================+=============================+ |
| 442 | | pure module distribution | :file:`{prefix}` | :option:`--install-purelib` | |
| 443 | +------------------------------+---------------------------+-----------------------------+ |
| 444 | | non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` | |
| 445 | +------------------------------+---------------------------+-----------------------------+ |
| 446 | | scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` | |
| 447 | +------------------------------+---------------------------+-----------------------------+ |
| 448 | | data | :file:`{prefix}\\Data` | :option:`--install-data` | |
| 449 | +------------------------------+---------------------------+-----------------------------+ |
| 450 | |
| 451 | |
| 452 | .. _inst-custom-install: |
| 453 | |
| 454 | Custom Installation |
| 455 | =================== |
| 456 | |
| 457 | Sometimes, the alternate installation schemes described in section |
| 458 | :ref:`inst-alt-install` just don't do what you want. You might want to tweak just |
| 459 | one or two directories while keeping everything under the same base directory, |
| 460 | or you might want to completely redefine the installation scheme. In either |
| 461 | case, you're creating a *custom installation scheme*. |
| 462 | |
| 463 | You probably noticed the column of "override options" in the tables describing |
| 464 | the alternate installation schemes above. Those options are how you define a |
| 465 | custom installation scheme. These override options can be relative, absolute, |
| 466 | or explicitly defined in terms of one of the installation base directories. |
| 467 | (There are two installation base directories, and they are normally the same--- |
| 468 | they only differ when you use the Unix "prefix scheme" and supply different |
| 469 | :option:`--prefix` and :option:`--exec-prefix` options.) |
| 470 | |
| 471 | For example, say you're installing a module distribution to your home directory |
| 472 | under Unix---but you want scripts to go in :file:`~/scripts` rather than |
| 473 | :file:`~/bin`. As you might expect, you can override this directory with the |
| 474 | :option:`--install-scripts` option; in this case, it makes most sense to supply |
| 475 | a relative path, which will be interpreted relative to the installation base |
| 476 | directory (your home directory, in this case):: |
| 477 | |
| 478 | python setup.py install --home=~ --install-scripts=scripts |
| 479 | |
| 480 | Another Unix example: suppose your Python installation was built and installed |
| 481 | with a prefix of :file:`/usr/local/python`, so under a standard installation |
| 482 | scripts will wind up in :file:`/usr/local/python/bin`. If you want them in |
| 483 | :file:`/usr/local/bin` instead, you would supply this absolute directory for the |
| 484 | :option:`--install-scripts` option:: |
| 485 | |
| 486 | python setup.py install --install-scripts=/usr/local/bin |
| 487 | |
| 488 | (This performs an installation using the "prefix scheme," where the prefix is |
| 489 | whatever your Python interpreter was installed with--- :file:`/usr/local/python` |
| 490 | in this case.) |
| 491 | |
| 492 | If you maintain Python on Windows, you might want third-party modules to live in |
| 493 | a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}` |
| 494 | itself. This is almost as easy as customizing the script installation directory |
| 495 | ---you just have to remember that there are two types of modules to worry about, |
| 496 | pure modules and non-pure modules (i.e., modules from a non-pure distribution). |
| 497 | For example:: |
| 498 | |
| 499 | python setup.py install --install-purelib=Site --install-platlib=Site |
| 500 | |
| 501 | The specified installation directories are relative to :file:`{prefix}`. Of |
| 502 | course, you also have to ensure that these directories are in Python's module |
| 503 | search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See |
| 504 | section :ref:`inst-search-path` to find out how to modify Python's search path. |
| 505 | |
| 506 | If you want to define an entire installation scheme, you just have to supply all |
| 507 | of the installation directory options. The recommended way to do this is to |
| 508 | supply relative paths; for example, if you want to maintain all Python |
| 509 | module-related files under :file:`python` in your home directory, and you want a |
| 510 | separate directory for each platform that you use your home directory from, you |
| 511 | might define the following installation scheme:: |
| 512 | |
| 513 | python setup.py install --home=~ \ |
| 514 | --install-purelib=python/lib \ |
| 515 | --install-platlib=python/lib.$PLAT \ |
| 516 | --install-scripts=python/scripts |
| 517 | --install-data=python/data |
| 518 | |
Georg Brandl | 81ac1ce | 2007-08-31 17:17:17 +0000 | [diff] [blame] | 519 | or, equivalently, :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 520 | |
| 521 | python setup.py install --home=~/python \ |
| 522 | --install-purelib=lib \ |
| 523 | --install-platlib='lib.$PLAT' \ |
| 524 | --install-scripts=scripts |
| 525 | --install-data=data |
| 526 | |
| 527 | ``$PLAT`` is not (necessarily) an environment variable---it will be expanded by |
| 528 | the Distutils as it parses your command line options, just as it does when |
| 529 | parsing your configuration file(s). |
| 530 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 531 | Obviously, specifying the entire installation scheme every time you install a |
| 532 | new module distribution would be very tedious. Thus, you can put these options |
| 533 | into your Distutils config file (see section :ref:`inst-config-files`):: |
| 534 | |
| 535 | [install] |
| 536 | install-base=$HOME |
| 537 | install-purelib=python/lib |
| 538 | install-platlib=python/lib.$PLAT |
| 539 | install-scripts=python/scripts |
| 540 | install-data=python/data |
| 541 | |
| 542 | or, equivalently, :: |
| 543 | |
| 544 | [install] |
| 545 | install-base=$HOME/python |
| 546 | install-purelib=lib |
| 547 | install-platlib=lib.$PLAT |
| 548 | install-scripts=scripts |
| 549 | install-data=data |
| 550 | |
| 551 | Note that these two are *not* equivalent if you supply a different installation |
| 552 | base directory when you run the setup script. For example, :: |
| 553 | |
| 554 | python setup.py install --install-base=/tmp |
| 555 | |
| 556 | would install pure modules to :file:`{/tmp/python/lib}` in the first case, and |
| 557 | to :file:`{/tmp/lib}` in the second case. (For the second case, you probably |
| 558 | want to supply an installation base of :file:`/tmp/python`.) |
| 559 | |
| 560 | You probably noticed the use of ``$HOME`` and ``$PLAT`` in the sample |
| 561 | configuration file input. These are Distutils configuration variables, which |
| 562 | bear a strong resemblance to environment variables. In fact, you can use |
| 563 | environment variables in config files on platforms that have such a notion but |
| 564 | the Distutils additionally define a few extra variables that may not be in your |
| 565 | environment, such as ``$PLAT``. (And of course, on systems that don't have |
| 566 | environment variables, such as Mac OS 9, the configuration variables supplied by |
| 567 | the Distutils are the only ones you can use.) See section :ref:`inst-config-files` |
| 568 | for details. |
| 569 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 570 | .. XXX need some Windows examples---when would custom installation schemes be |
| 571 | needed on those platforms? |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 572 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 573 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 574 | .. XXX I'm not sure where this section should go. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 575 | |
| 576 | .. _inst-search-path: |
| 577 | |
| 578 | Modifying Python's Search Path |
| 579 | ------------------------------ |
| 580 | |
| 581 | When the Python interpreter executes an :keyword:`import` statement, it searches |
| 582 | for both Python code and extension modules along a search path. A default value |
| 583 | for the path is configured into the Python binary when the interpreter is built. |
| 584 | You can determine the path by importing the :mod:`sys` module and printing the |
| 585 | value of ``sys.path``. :: |
| 586 | |
| 587 | $ python |
| 588 | Python 2.2 (#11, Oct 3 2002, 13:31:27) |
| 589 | [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2 |
Georg Brandl | 1f01deb | 2009-01-03 22:47:39 +0000 | [diff] [blame] | 590 | Type "help", "copyright", "credits" or "license" for more information. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 591 | >>> import sys |
| 592 | >>> sys.path |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 593 | ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2', |
| 594 | '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload', |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 595 | '/usr/local/lib/python2.3/site-packages'] |
| 596 | >>> |
| 597 | |
| 598 | The null string in ``sys.path`` represents the current working directory. |
| 599 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 600 | The expected convention for locally installed packages is to put them in the |
| 601 | :file:`{...}/site-packages/` directory, but you may want to install Python |
| 602 | modules into some arbitrary directory. For example, your site may have a |
| 603 | convention of keeping all software related to the web server under :file:`/www`. |
| 604 | Add-on Python modules might then belong in :file:`/www/python`, and in order to |
| 605 | import them, this directory must be added to ``sys.path``. There are several |
| 606 | different ways to add the directory. |
| 607 | |
| 608 | The most convenient way is to add a path configuration file to a directory |
| 609 | that's already on Python's path, usually to the :file:`.../site-packages/` |
| 610 | directory. Path configuration files have an extension of :file:`.pth`, and each |
| 611 | line must contain a single path that will be appended to ``sys.path``. (Because |
| 612 | the new paths are appended to ``sys.path``, modules in the added directories |
| 613 | will not override standard modules. This means you can't use this mechanism for |
| 614 | installing fixed versions of standard modules.) |
| 615 | |
| 616 | Paths can be absolute or relative, in which case they're relative to the |
Christian Heimes | 9cd1775 | 2007-11-18 19:35:23 +0000 | [diff] [blame] | 617 | directory containing the :file:`.pth` file. See the documentation of |
Thomas Wouters | ed03b41 | 2007-08-28 21:37:11 +0000 | [diff] [blame] | 618 | the :mod:`site` module for more information. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 619 | |
| 620 | A slightly less convenient way is to edit the :file:`site.py` file in Python's |
| 621 | standard library, and modify ``sys.path``. :file:`site.py` is automatically |
| 622 | imported when the Python interpreter is executed, unless the :option:`-S` switch |
| 623 | is supplied to suppress this behaviour. So you could simply edit |
| 624 | :file:`site.py` and add two lines to it:: |
| 625 | |
| 626 | import sys |
| 627 | sys.path.append('/www/python/') |
| 628 | |
| 629 | However, if you reinstall the same major version of Python (perhaps when |
| 630 | upgrading from 2.2 to 2.2.2, for example) :file:`site.py` will be overwritten by |
| 631 | the stock version. You'd have to remember that it was modified and save a copy |
| 632 | before doing the installation. |
| 633 | |
| 634 | There are two environment variables that can modify ``sys.path``. |
| 635 | :envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python |
| 636 | installation. For example, if :envvar:`PYTHONHOME` is set to ``/www/python``, |
| 637 | the search path will be set to ``['', '/www/python/lib/pythonX.Y/', |
| 638 | '/www/python/lib/pythonX.Y/plat-linux2', ...]``. |
| 639 | |
| 640 | The :envvar:`PYTHONPATH` variable can be set to a list of paths that will be |
| 641 | added to the beginning of ``sys.path``. For example, if :envvar:`PYTHONPATH` is |
| 642 | set to ``/www/python:/opt/py``, the search path will begin with |
| 643 | ``['/www/python', '/opt/py']``. (Note that directories must exist in order to |
| 644 | be added to ``sys.path``; the :mod:`site` module removes paths that don't |
| 645 | exist.) |
| 646 | |
| 647 | Finally, ``sys.path`` is just a regular Python list, so any Python application |
| 648 | can modify it by adding or removing entries. |
| 649 | |
| 650 | |
| 651 | .. _inst-config-files: |
| 652 | |
| 653 | Distutils Configuration Files |
| 654 | ============================= |
| 655 | |
| 656 | As mentioned above, you can use Distutils configuration files to record personal |
| 657 | or site preferences for any Distutils options. That is, any option to any |
| 658 | command can be stored in one of two or three (depending on your platform) |
| 659 | configuration files, which will be consulted before the command-line is parsed. |
| 660 | This means that configuration files will override default values, and the |
| 661 | command-line will in turn override configuration files. Furthermore, if |
| 662 | multiple configuration files apply, values from "earlier" files are overridden |
| 663 | by "later" files. |
| 664 | |
| 665 | |
| 666 | .. _inst-config-filenames: |
| 667 | |
| 668 | Location and names of config files |
| 669 | ---------------------------------- |
| 670 | |
| 671 | The names and locations of the configuration files vary slightly across |
| 672 | platforms. On Unix and Mac OS X, the three configuration files (in the order |
| 673 | they are processed) are: |
| 674 | |
| 675 | +--------------+----------------------------------------------------------+-------+ |
| 676 | | Type of file | Location and filename | Notes | |
| 677 | +==============+==========================================================+=======+ |
| 678 | | system | :file:`{prefix}/lib/python{ver}/distutils/distutils.cfg` | \(1) | |
| 679 | +--------------+----------------------------------------------------------+-------+ |
| 680 | | personal | :file:`$HOME/.pydistutils.cfg` | \(2) | |
| 681 | +--------------+----------------------------------------------------------+-------+ |
| 682 | | local | :file:`setup.cfg` | \(3) | |
| 683 | +--------------+----------------------------------------------------------+-------+ |
| 684 | |
| 685 | And on Windows, the configuration files are: |
| 686 | |
| 687 | +--------------+-------------------------------------------------+-------+ |
| 688 | | Type of file | Location and filename | Notes | |
| 689 | +==============+=================================================+=======+ |
| 690 | | system | :file:`{prefix}\\Lib\\distutils\\distutils.cfg` | \(4) | |
| 691 | +--------------+-------------------------------------------------+-------+ |
| 692 | | personal | :file:`%HOME%\\pydistutils.cfg` | \(5) | |
| 693 | +--------------+-------------------------------------------------+-------+ |
| 694 | | local | :file:`setup.cfg` | \(3) | |
| 695 | +--------------+-------------------------------------------------+-------+ |
| 696 | |
Tarek Ziadé | c7c71ff | 2009-10-27 23:12:01 +0000 | [diff] [blame] | 697 | On all platforms, the "personal" file can be temporarily disabled by |
| 698 | passing the `--no-user-cfg` option. |
| 699 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 700 | Notes: |
| 701 | |
| 702 | (1) |
| 703 | Strictly speaking, the system-wide configuration file lives in the directory |
| 704 | where the Distutils are installed; under Python 1.6 and later on Unix, this is |
| 705 | as shown. For Python 1.5.2, the Distutils will normally be installed to |
| 706 | :file:`{prefix}/lib/python1.5/site-packages/distutils`, so the system |
| 707 | configuration file should be put there under Python 1.5.2. |
| 708 | |
| 709 | (2) |
| 710 | On Unix, if the :envvar:`HOME` environment variable is not defined, the user's |
| 711 | home directory will be determined with the :func:`getpwuid` function from the |
Tarek Ziadé | f3b3322 | 2009-08-21 14:22:45 +0000 | [diff] [blame] | 712 | standard :mod:`pwd` module. This is done by the :func:`os.path.expanduser` |
| 713 | function used by Distutils. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 714 | |
| 715 | (3) |
| 716 | I.e., in the current directory (usually the location of the setup script). |
| 717 | |
| 718 | (4) |
| 719 | (See also note (1).) Under Python 1.6 and later, Python's default "installation |
| 720 | prefix" is :file:`C:\\Python`, so the system configuration file is normally |
| 721 | :file:`C:\\Python\\Lib\\distutils\\distutils.cfg`. Under Python 1.5.2, the |
| 722 | default prefix was :file:`C:\\Program Files\\Python`, and the Distutils were not |
| 723 | part of the standard library---so the system configuration file would be |
| 724 | :file:`C:\\Program Files\\Python\\distutils\\distutils.cfg` in a standard Python |
| 725 | 1.5.2 installation under Windows. |
| 726 | |
| 727 | (5) |
Tarek Ziadé | f3b3322 | 2009-08-21 14:22:45 +0000 | [diff] [blame] | 728 | On Windows, if the :envvar:`HOME` environment variable is not defined, |
| 729 | :envvar:`USERPROFILE` then :envvar:`HOMEDRIVE` and :envvar:`HOMEPATH` will |
| 730 | be tried. This is done by the :func:`os.path.expanduser` function used |
| 731 | by Distutils. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 732 | |
| 733 | |
| 734 | .. _inst-config-syntax: |
| 735 | |
| 736 | Syntax of config files |
| 737 | ---------------------- |
| 738 | |
| 739 | The Distutils configuration files all have the same syntax. The config files |
| 740 | are grouped into sections. There is one section for each Distutils command, |
| 741 | plus a ``global`` section for global options that affect every command. Each |
| 742 | section consists of one option per line, specified as ``option=value``. |
| 743 | |
| 744 | For example, the following is a complete config file that just forces all |
| 745 | commands to run quietly by default:: |
| 746 | |
| 747 | [global] |
| 748 | verbose=0 |
| 749 | |
| 750 | If this is installed as the system config file, it will affect all processing of |
| 751 | any Python module distribution by any user on the current system. If it is |
| 752 | installed as your personal config file (on systems that support them), it will |
| 753 | affect only module distributions processed by you. And if it is used as the |
| 754 | :file:`setup.cfg` for a particular module distribution, it affects only that |
| 755 | distribution. |
| 756 | |
| 757 | You could override the default "build base" directory and make the |
| 758 | :command:`build\*` commands always forcibly rebuild all files with the |
| 759 | following:: |
| 760 | |
| 761 | [build] |
| 762 | build-base=blib |
| 763 | force=1 |
| 764 | |
| 765 | which corresponds to the command-line arguments :: |
| 766 | |
| 767 | python setup.py build --build-base=blib --force |
| 768 | |
| 769 | except that including the :command:`build` command on the command-line means |
| 770 | that command will be run. Including a particular command in config files has no |
| 771 | such implication; it only means that if the command is run, the options in the |
| 772 | config file will apply. (Or if other commands that derive values from it are |
| 773 | run, they will use the values in the config file.) |
| 774 | |
| 775 | You can find out the complete list of options for any command using the |
| 776 | :option:`--help` option, e.g.:: |
| 777 | |
| 778 | python setup.py build --help |
| 779 | |
| 780 | and you can find out the complete list of global options by using |
| 781 | :option:`--help` without a command:: |
| 782 | |
| 783 | python setup.py --help |
| 784 | |
| 785 | See also the "Reference" section of the "Distributing Python Modules" manual. |
| 786 | |
| 787 | |
| 788 | .. _inst-building-ext: |
| 789 | |
| 790 | Building Extensions: Tips and Tricks |
| 791 | ==================================== |
| 792 | |
| 793 | Whenever possible, the Distutils try to use the configuration information made |
| 794 | available by the Python interpreter used to run the :file:`setup.py` script. |
| 795 | For example, the same compiler and linker flags used to compile Python will also |
| 796 | be used for compiling extensions. Usually this will work well, but in |
| 797 | complicated situations this might be inappropriate. This section discusses how |
| 798 | to override the usual Distutils behaviour. |
| 799 | |
| 800 | |
| 801 | .. _inst-tweak-flags: |
| 802 | |
| 803 | Tweaking compiler/linker flags |
| 804 | ------------------------------ |
| 805 | |
| 806 | Compiling a Python extension written in C or C++ will sometimes require |
| 807 | specifying custom flags for the compiler and linker in order to use a particular |
| 808 | library or produce a special kind of object code. This is especially true if the |
| 809 | extension hasn't been tested on your platform, or if you're trying to |
| 810 | cross-compile Python. |
| 811 | |
| 812 | In the most general case, the extension author might have foreseen that |
| 813 | compiling the extensions would be complicated, and provided a :file:`Setup` file |
| 814 | for you to edit. This will likely only be done if the module distribution |
| 815 | contains many separate extension modules, or if they often require elaborate |
| 816 | sets of compiler flags in order to work. |
| 817 | |
| 818 | A :file:`Setup` file, if present, is parsed in order to get a list of extensions |
| 819 | to build. Each line in a :file:`Setup` describes a single module. Lines have |
| 820 | the following structure:: |
| 821 | |
| 822 | module ... [sourcefile ...] [cpparg ...] [library ...] |
| 823 | |
| 824 | |
| 825 | Let's examine each of the fields in turn. |
| 826 | |
| 827 | * *module* is the name of the extension module to be built, and should be a |
| 828 | valid Python identifier. You can't just change this in order to rename a module |
| 829 | (edits to the source code would also be needed), so this should be left alone. |
| 830 | |
| 831 | * *sourcefile* is anything that's likely to be a source code file, at least |
| 832 | judging by the filename. Filenames ending in :file:`.c` are assumed to be |
| 833 | written in C, filenames ending in :file:`.C`, :file:`.cc`, and :file:`.c++` are |
| 834 | assumed to be C++, and filenames ending in :file:`.m` or :file:`.mm` are assumed |
| 835 | to be in Objective C. |
| 836 | |
| 837 | * *cpparg* is an argument for the C preprocessor, and is anything starting with |
| 838 | :option:`-I`, :option:`-D`, :option:`-U` or :option:`-C`. |
| 839 | |
| 840 | * *library* is anything ending in :file:`.a` or beginning with :option:`-l` or |
| 841 | :option:`-L`. |
| 842 | |
| 843 | If a particular platform requires a special library on your platform, you can |
| 844 | add it by editing the :file:`Setup` file and running ``python setup.py build``. |
| 845 | For example, if the module defined by the line :: |
| 846 | |
| 847 | foo foomodule.c |
| 848 | |
| 849 | must be linked with the math library :file:`libm.a` on your platform, simply add |
| 850 | :option:`-lm` to the line:: |
| 851 | |
| 852 | foo foomodule.c -lm |
| 853 | |
| 854 | Arbitrary switches intended for the compiler or the linker can be supplied with |
| 855 | the :option:`-Xcompiler` *arg* and :option:`-Xlinker` *arg* options:: |
| 856 | |
| 857 | foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm |
| 858 | |
| 859 | The next option after :option:`-Xcompiler` and :option:`-Xlinker` will be |
| 860 | appended to the proper command line, so in the above example the compiler will |
| 861 | be passed the :option:`-o32` option, and the linker will be passed |
| 862 | :option:`-shared`. If a compiler option requires an argument, you'll have to |
| 863 | supply multiple :option:`-Xcompiler` options; for example, to pass ``-x c++`` |
| 864 | the :file:`Setup` file would have to contain ``-Xcompiler -x -Xcompiler c++``. |
| 865 | |
| 866 | Compiler flags can also be supplied through setting the :envvar:`CFLAGS` |
| 867 | environment variable. If set, the contents of :envvar:`CFLAGS` will be added to |
| 868 | the compiler flags specified in the :file:`Setup` file. |
| 869 | |
| 870 | |
| 871 | .. _inst-non-ms-compilers: |
| 872 | |
| 873 | Using non-Microsoft compilers on Windows |
| 874 | ---------------------------------------- |
| 875 | |
| 876 | .. sectionauthor:: Rene Liebscher <R.Liebscher@gmx.de> |
| 877 | |
| 878 | |
| 879 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 880 | Borland/CodeGear C++ |
| 881 | ^^^^^^^^^^^^^^^^^^^^ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 882 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 883 | This subsection describes the necessary steps to use Distutils with the Borland |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 884 | C++ compiler version 5.5. First you have to know that Borland's object file |
| 885 | format (OMF) is different from the format used by the Python version you can |
| 886 | download from the Python or ActiveState Web site. (Python is built with |
| 887 | Microsoft Visual C++, which uses COFF as the object file format.) For this |
| 888 | reason you have to convert Python's library :file:`python25.lib` into the |
| 889 | Borland format. You can do this as follows: |
| 890 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 891 | .. Should we mention that users have to create cfg-files for the compiler? |
| 892 | .. see also http://community.borland.com/article/0,1410,21205,00.html |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 893 | |
| 894 | :: |
| 895 | |
| 896 | coff2omf python25.lib python25_bcpp.lib |
| 897 | |
| 898 | The :file:`coff2omf` program comes with the Borland compiler. The file |
| 899 | :file:`python25.lib` is in the :file:`Libs` directory of your Python |
| 900 | installation. If your extension uses other libraries (zlib, ...) you have to |
| 901 | convert them too. |
| 902 | |
| 903 | The converted files have to reside in the same directories as the normal |
| 904 | libraries. |
| 905 | |
| 906 | How does Distutils manage to use these libraries with their changed names? If |
| 907 | the extension needs a library (eg. :file:`foo`) Distutils checks first if it |
| 908 | finds a library with suffix :file:`_bcpp` (eg. :file:`foo_bcpp.lib`) and then |
| 909 | uses this library. In the case it doesn't find such a special library it uses |
| 910 | the default name (:file:`foo.lib`.) [#]_ |
| 911 | |
| 912 | To let Distutils compile your extension with Borland C++ you now have to type:: |
| 913 | |
| 914 | python setup.py build --compiler=bcpp |
| 915 | |
| 916 | If you want to use the Borland C++ compiler as the default, you could specify |
| 917 | this in your personal or system-wide configuration file for Distutils (see |
| 918 | section :ref:`inst-config-files`.) |
| 919 | |
| 920 | |
| 921 | .. seealso:: |
| 922 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 923 | `C++Builder Compiler <http://www.codegear.com/downloads/free/cppbuilder>`_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 924 | Information about the free C++ compiler from Borland, including links to the |
| 925 | download pages. |
| 926 | |
| 927 | `Creating Python Extensions Using Borland's Free Compiler <http://www.cyberus.ca/~g_will/pyExtenDL.shtml>`_ |
| 928 | Document describing how to use Borland's free command-line C++ compiler to build |
| 929 | Python. |
| 930 | |
| 931 | |
| 932 | GNU C / Cygwin / MinGW |
| 933 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 934 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 935 | This section describes the necessary steps to use Distutils with the GNU C/C++ |
| 936 | compilers in their Cygwin and MinGW distributions. [#]_ For a Python interpreter |
| 937 | that was built with Cygwin, everything should work without any of these |
| 938 | following steps. |
| 939 | |
Éric Araujo | 2d6bb12 | 2010-12-15 22:06:35 +0000 | [diff] [blame] | 940 | Not all extensions can be built with MinGW or Cygwin, but many can. Extensions |
| 941 | most likely to not work are those that use C++ or depend on Microsoft Visual C |
| 942 | extensions. |
| 943 | |
| 944 | To let Distutils compile your extension with Cygwin you have to type:: |
| 945 | |
| 946 | python setup.py build --compiler=cygwin |
| 947 | |
| 948 | and for Cygwin in no-cygwin mode [#]_ or for MinGW type:: |
| 949 | |
| 950 | python setup.py build --compiler=mingw32 |
| 951 | |
| 952 | If you want to use any of these options/compilers as default, you should |
| 953 | consider writing it in your personal or system-wide configuration file for |
| 954 | Distutils (see section :ref:`inst-config-files`.) |
| 955 | |
| 956 | Older Versions of Python and MinGW |
| 957 | """""""""""""""""""""""""""""""""" |
| 958 | The following instructions only apply if you're using a version of Python |
| 959 | inferior to 2.4.1 with a MinGW inferior to 3.0.0 (with |
| 960 | binutils-2.13.90-20030111-1). |
| 961 | |
| 962 | These compilers require some special libraries. This task is more complex than |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 963 | for Borland's C++, because there is no program to convert the library. First |
| 964 | you have to create a list of symbols which the Python DLL exports. (You can find |
Georg Brandl | 495f7b5 | 2009-10-27 15:28:25 +0000 | [diff] [blame] | 965 | a good program for this task at |
| 966 | http://www.emmestech.com/software/pexports-0.43/download_pexports.html). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 967 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 968 | .. I don't understand what the next line means. --amk |
| 969 | .. (inclusive the references on data structures.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 970 | |
| 971 | :: |
| 972 | |
| 973 | pexports python25.dll >python25.def |
| 974 | |
| 975 | The location of an installed :file:`python25.dll` will depend on the |
| 976 | installation options and the version and language of Windows. In a "just for |
| 977 | me" installation, it will appear in the root of the installation directory. In |
| 978 | a shared installation, it will be located in the system directory. |
| 979 | |
| 980 | Then you can create from these information an import library for gcc. :: |
| 981 | |
| 982 | /cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a |
| 983 | |
| 984 | The resulting library has to be placed in the same directory as |
| 985 | :file:`python25.lib`. (Should be the :file:`libs` directory under your Python |
| 986 | installation directory.) |
| 987 | |
| 988 | If your extension uses other libraries (zlib,...) you might have to convert |
| 989 | them too. The converted files have to reside in the same directories as the |
| 990 | normal libraries do. |
| 991 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 992 | |
| 993 | .. seealso:: |
| 994 | |
| 995 | `Building Python modules on MS Windows platform with MinGW <http://www.zope.org/Members/als/tips/win32_mingw_modules>`_ |
| 996 | Information about building the required libraries for the MinGW environment. |
| 997 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 998 | |
| 999 | .. rubric:: Footnotes |
| 1000 | |
| 1001 | .. [#] This also means you could replace all existing COFF-libraries with OMF-libraries |
| 1002 | of the same name. |
| 1003 | |
| 1004 | .. [#] Check http://sources.redhat.com/cygwin/ and http://www.mingw.org/ for more |
| 1005 | information |
| 1006 | |
| 1007 | .. [#] Then you have no POSIX emulation available, but you also don't need |
| 1008 | :file:`cygwin1.dll`. |