1 .. _distutils-intro: 2 3 **************************** 4 An Introduction to Distutils 5 **************************** 6 7 This document covers using the Distutils to distribute your Python modules, 8 concentrating on the role of developer/distributor: if you're looking for 9 information on installing Python modules, you should refer to the 10 :ref:`install-index` chapter. 11 12 13 .. _distutils-concepts: 14 15 Concepts & Terminology 16 ====================== 17 18 Using the Distutils is quite simple, both for module developers and for 19 users/administrators installing third-party modules. As a developer, your 20 responsibilities (apart from writing solid, well-documented and well-tested 21 code, of course!) are: 22 23 * write a setup script (:file:`setup.py` by convention) 24 25 * (optional) write a setup configuration file 26 27 * create a source distribution 28 29 * (optional) create one or more built (binary) distributions 30 31 Each of these tasks is covered in this document. 32 33 Not all module developers have access to a multitude of platforms, so it's not 34 always feasible to expect them to create a multitude of built distributions. It 35 is hoped that a class of intermediaries, called *packagers*, will arise to 36 address this need. Packagers will take source distributions released by module 37 developers, build them on one or more platforms, and release the resulting built 38 distributions. Thus, users on the most popular platforms will be able to 39 install most popular Python module distributions in the most natural way for 40 their platform, without having to run a single setup script or compile a line of 41 code. 42 43 44 .. _distutils-simple-example: 45 46 A Simple Example 47 ================ 48 49 The setup script is usually quite simple, although since it's written in Python, 50 there are no arbitrary limits to what you can do with it, though you should be 51 careful about putting arbitrarily expensive operations in your setup script. 52 Unlike, say, Autoconf-style configure scripts, the setup script may be run 53 multiple times in the course of building and installing your module 54 distribution. 55 56 If all you want to do is distribute a module called :mod:`foo`, contained in a 57 file :file:`foo.py`, then your setup script can be as simple as this:: 58 59 from distutils.core import setup 60 setup(name='foo', 61 version='1.0', 62 py_modules=['foo'], 63 ) 64 65 Some observations: 66 67 * most information that you supply to the Distutils is supplied as keyword 68 arguments to the :func:`setup` function 69 70 * those keyword arguments fall into two categories: package metadata (name, 71 version number) and information about what's in the package (a list of pure 72 Python modules, in this case) 73 74 * modules are specified by module name, not filename (the same will hold true 75 for packages and extensions) 76 77 * it's recommended that you supply a little more metadata, in particular your 78 name, email address and a URL for the project (see section :ref:`setup-script` 79 for an example) 80 81 To create a source distribution for this module, you would create a setup 82 script, :file:`setup.py`, containing the above code, and run this command from a 83 terminal:: 84 85 python setup.py sdist 86 87 For Windows, open a command prompt window (:menuselection:`Start --> 88 Accessories`) and change the command to:: 89 90 setup.py sdist 91 92 :command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows) 93 containing your setup script :file:`setup.py`, and your module :file:`foo.py`. 94 The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and 95 will unpack into a directory :file:`foo-1.0`. 96 97 If an end-user wishes to install your :mod:`foo` module, all they have to do is 98 download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the 99 :file:`foo-1.0` directory---run :: 100 101 python setup.py install 102 103 which will ultimately copy :file:`foo.py` to the appropriate directory for 104 third-party modules in their Python installation. 105 106 This simple example demonstrates some fundamental concepts of the Distutils. 107 First, both developers and installers have the same basic user interface, i.e. 108 the setup script. The difference is which Distutils *commands* they use: the 109 :command:`sdist` command is almost exclusively for module developers, while 110 :command:`install` is more often for installers (although most developers will 111 want to install their own code occasionally). 112 113 If you want to make things really easy for your users, you can create one or 114 more built distributions for them. For instance, if you are running on a 115 Windows machine, and want to make things easy for other Windows users, you can 116 create an executable installer (the most appropriate type of built distribution 117 for this platform) with the :command:`bdist_wininst` command. For example:: 118 119 python setup.py bdist_wininst 120 121 will create an executable installer, :file:`foo-1.0.win32.exe`, in the current 122 directory. 123 124 Other useful built distribution formats are RPM, implemented by the 125 :command:`bdist_rpm` command, Solaris :program:`pkgtool` 126 (:command:`bdist_pkgtool`), and HP-UX :program:`swinstall` 127 (:command:`bdist_sdux`). For example, the following command will create an RPM 128 file called :file:`foo-1.0.noarch.rpm`:: 129 130 python setup.py bdist_rpm 131 132 (The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore 133 this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or 134 Mandrake Linux.) 135 136 You can find out what distribution formats are available at any time by running 137 :: 138 139 python setup.py bdist --help-formats 140 141 142 .. _python-terms: 143 144 General Python terminology 145 ========================== 146 147 If you're reading this document, you probably have a good idea of what modules, 148 extensions, and so forth are. Nevertheless, just to be sure that everyone is 149 operating from a common starting point, we offer the following glossary of 150 common Python terms: 151 152 module 153 the basic unit of code reusability in Python: a block of code imported by some 154 other code. Three types of modules concern us here: pure Python modules, 155 extension modules, and packages. 156 157 pure Python module 158 a module written in Python and contained in a single :file:`.py` file (and 159 possibly associated :file:`.pyc` files). Sometimes referred to as a 160 "pure module." 161 162 extension module 163 a module written in the low-level language of the Python implementation: C/C++ 164 for Python, Java for Jython. Typically contained in a single dynamically 165 loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python 166 extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python 167 extensions on Windows, or a Java class file for Jython extensions. (Note that 168 currently, the Distutils only handles C/C++ extensions for Python.) 169 170 package 171 a module that contains other modules; typically contained in a directory in the 172 filesystem and distinguished from other directories by the presence of a file 173 :file:`__init__.py`. 174 175 root package 176 the root of the hierarchy of packages. (This isn't really a package, since it 177 doesn't have an :file:`__init__.py` file. But we have to call it something.) 178 The vast majority of the standard library is in the root package, as are many 179 small, standalone third-party modules that don't belong to a larger module 180 collection. Unlike regular packages, modules in the root package can be found in 181 many directories: in fact, every directory listed in ``sys.path`` contributes 182 modules to the root package. 183 184 185 .. _distutils-term: 186 187 Distutils-specific terminology 188 ============================== 189 190 The following terms apply more specifically to the domain of distributing Python 191 modules using the Distutils: 192 193 module distribution 194 a collection of Python modules distributed together as a single downloadable 195 resource and meant to be installed *en masse*. Examples of some well-known 196 module distributions are NumPy, SciPy, Pillow, 197 or mxBase. (This would be called a *package*, except that term is 198 already taken in the Python context: a single module distribution may contain 199 zero, one, or many Python packages.) 200 201 pure module distribution 202 a module distribution that contains only pure Python modules and packages. 203 Sometimes referred to as a "pure distribution." 204 205 non-pure module distribution 206 a module distribution that contains at least one extension module. Sometimes 207 referred to as a "non-pure distribution." 208 209 distribution root 210 the top-level directory of your source tree (or source distribution); the 211 directory where :file:`setup.py` exists. Generally :file:`setup.py` will be 212 run from this directory. 213
