Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 1 | .. _packaging-command-reference: |
| 2 | |
| 3 | ***************** |
| 4 | Command Reference |
| 5 | ***************** |
| 6 | |
| 7 | This reference briefly documents all standard Packaging commands and some of |
| 8 | their options. |
| 9 | |
| 10 | .. FIXME does not work: Use pysetup run --help-commands to list all |
| 11 | standard and extra commands availavble on your system, with their |
| 12 | description. Use pysetup run <command> --help to get help about the options |
| 13 | of one command. |
| 14 | |
| 15 | |
| 16 | Preparing distributions |
| 17 | ======================= |
| 18 | |
| 19 | :command:`check` |
| 20 | ---------------- |
| 21 | |
| 22 | Perform some tests on the metadata of a distribution. |
| 23 | |
| 24 | For example, it verifies that all required metadata fields are provided in the |
| 25 | :file:`setup.cfg` file. |
| 26 | |
| 27 | .. TODO document reST checks |
| 28 | |
| 29 | |
| 30 | :command:`test` |
| 31 | --------------- |
| 32 | |
| 33 | Run a test suite. |
| 34 | |
| 35 | When doing test-driven development, or running automated builds that need |
| 36 | testing before they are installed for downloading or use, it's often useful to |
| 37 | be able to run a project's unit tests without actually installing the project |
| 38 | anywhere. The :command:`test` command runs project's unit tests without |
| 39 | actually installing it, by temporarily putting the project's source on |
| 40 | :data:`sys.path`, after first running :command:`build_ext -i` to ensure that any |
| 41 | C extensions are built. |
| 42 | |
| 43 | You can use this command in one of two ways: either by specifying a |
| 44 | unittest-compatible test suite for your project (or any callable that returns |
| 45 | it) or by passing a test runner function that will run your tests and display |
| 46 | results in the console. Both options take a Python dotted name in the form |
| 47 | ``package.module.callable`` to specify the object to use. |
| 48 | |
| 49 | If none of these options are specified, Packaging will try to perform test |
| 50 | discovery using either unittest (for Python 3.2 and higher) or unittest2 (for |
| 51 | older versions, if installed). |
| 52 | |
| 53 | .. this is a pseudo-command name used to disambiguate the options in indexes and |
| 54 | links |
| 55 | .. program:: packaging test |
| 56 | |
| 57 | .. cmdoption:: --suite=NAME, -s NAME |
| 58 | |
| 59 | Specify the test suite (or module, class, or method) to be run. The default |
Georg Brandl | d3b41c6 | 2011-07-09 11:48:50 +0200 | [diff] [blame] | 60 | for this option can be set by in the project's :file:`setup.cfg` file: |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 61 | |
| 62 | .. code-block:: cfg |
| 63 | |
| 64 | [test] |
| 65 | suite = mypackage.tests.get_all_tests |
| 66 | |
| 67 | .. cmdoption:: --runner=NAME, -r NAME |
| 68 | |
| 69 | Specify the test runner to be called. |
| 70 | |
| 71 | |
| 72 | :command:`config` |
| 73 | ----------------- |
| 74 | |
| 75 | Perform distribution configuration. |
| 76 | |
| 77 | |
| 78 | The build step |
| 79 | ============== |
| 80 | |
| 81 | This step is mainly useful to compile C/C++ libraries or extension modules. The |
| 82 | build commands can be run manually to check for syntax errors or packaging |
| 83 | issues (for example if the addition of a new source file was forgotten in the |
| 84 | :file:`setup.cfg` file), and is also run automatically by commands which need |
| 85 | it. Packaging checks the mtime of source and built files to avoid re-building |
| 86 | if it's not necessary. |
| 87 | |
| 88 | |
| 89 | :command:`build` |
| 90 | ---------------- |
| 91 | |
| 92 | Build all files of a distribution, delegating to the other :command:`build_*` |
| 93 | commands to do the work. |
| 94 | |
| 95 | |
| 96 | :command:`build_clib` |
| 97 | --------------------- |
| 98 | |
| 99 | Build C libraries. |
| 100 | |
| 101 | |
| 102 | :command:`build_ext` |
| 103 | -------------------- |
| 104 | |
| 105 | Build C/C++ extension modules. |
| 106 | |
| 107 | |
| 108 | :command:`build_py` |
| 109 | ------------------- |
| 110 | |
| 111 | Build the Python modules (just copy them to the build directory) and |
| 112 | byte-compile them to .pyc files. |
| 113 | |
| 114 | |
| 115 | :command:`build_scripts` |
| 116 | ------------------------ |
| 117 | Build the scripts (just copy them to the build directory and adjust their |
| 118 | shebang if they're Python scripts). |
| 119 | |
| 120 | |
| 121 | :command:`clean` |
| 122 | ---------------- |
| 123 | |
| 124 | Clean the build tree of the release. |
| 125 | |
| 126 | .. program:: packaging clean |
| 127 | |
| 128 | .. cmdoption:: --all, -a |
| 129 | |
| 130 | Remove build directories for modules, scripts, etc., not only temporary build |
| 131 | by-products. |
| 132 | |
| 133 | |
| 134 | Creating source and built distributions |
| 135 | ======================================= |
| 136 | |
| 137 | :command:`sdist` |
| 138 | ---------------- |
| 139 | |
| 140 | Build a source distribution for a release. |
| 141 | |
| 142 | It is recommended that you always build and upload a source distribution. Users |
| 143 | of OSes with easy access to compilers and users of advanced packaging tools will |
| 144 | prefer to compile from source rather than using pre-built distributions. For |
| 145 | Windows users, providing a binary installer is also recommended practice. |
| 146 | |
| 147 | |
| 148 | :command:`bdist` |
| 149 | ---------------- |
| 150 | |
| 151 | Build a binary distribution for a release. |
| 152 | |
| 153 | This command will call other :command:`bdist_*` commands to create one or more |
| 154 | distributions depending on the options given. The default is to create a |
| 155 | .tar.gz archive on Unix and a zip archive on Windows or OS/2. |
| 156 | |
| 157 | .. program:: packaging bdist |
| 158 | |
| 159 | .. cmdoption:: --formats |
| 160 | |
| 161 | Binary formats to build (comma-separated list). |
| 162 | |
| 163 | .. cmdoption:: --show-formats |
| 164 | |
| 165 | Dump list of available formats. |
| 166 | |
| 167 | |
| 168 | :command:`bdist_dumb` |
| 169 | --------------------- |
| 170 | |
| 171 | Build a "dumb" installer, a simple archive of files that could be unpacked under |
| 172 | ``$prefix`` or ``$exec_prefix``. |
| 173 | |
| 174 | |
| 175 | :command:`bdist_wininst` |
| 176 | ------------------------ |
| 177 | |
| 178 | Build a Windows installer. |
| 179 | |
| 180 | |
| 181 | :command:`bdist_msi` |
| 182 | -------------------- |
| 183 | |
| 184 | Build a `Microsoft Installer`_ (.msi) file. |
| 185 | |
| 186 | .. _Microsoft Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx |
| 187 | |
| 188 | In most cases, the :command:`bdist_msi` installer is a better choice than the |
| 189 | :command:`bdist_wininst` installer, because it provides better support for Win64 |
| 190 | platforms, allows administrators to perform non-interactive installations, and |
| 191 | allows installation through group policies. |
| 192 | |
| 193 | |
| 194 | Publishing distributions |
| 195 | ======================== |
| 196 | |
| 197 | :command:`register` |
| 198 | ------------------- |
| 199 | |
| 200 | This command registers the current release with the Python Package Index. This |
| 201 | is described in more detail in :PEP:`301`. |
| 202 | |
| 203 | .. TODO explain user and project registration with the web UI |
| 204 | |
| 205 | |
| 206 | :command:`upload` |
| 207 | ----------------- |
| 208 | |
| 209 | Upload source and/or binary distributions to PyPI. |
| 210 | |
| 211 | The distributions have to be built on the same command line as the |
| 212 | :command:`upload` command; see :ref:`packaging-package-upload` for more info. |
| 213 | |
| 214 | .. program:: packaging upload |
| 215 | |
| 216 | .. cmdoption:: --sign, -s |
| 217 | |
| 218 | Sign each uploaded file using GPG (GNU Privacy Guard). The ``gpg`` program |
| 219 | must be available for execution on the system ``PATH``. |
| 220 | |
| 221 | .. cmdoption:: --identity=NAME, -i NAME |
| 222 | |
| 223 | Specify the identity or key name for GPG to use when signing. The value of |
| 224 | this option will be passed through the ``--local-user`` option of the |
| 225 | ``gpg`` program. |
| 226 | |
| 227 | .. cmdoption:: --show-response |
| 228 | |
| 229 | Display the full response text from server; this is useful for debugging |
| 230 | PyPI problems. |
| 231 | |
| 232 | .. cmdoption:: --repository=URL, -r URL |
| 233 | |
| 234 | The URL of the repository to upload to. Defaults to |
| 235 | http://pypi.python.org/pypi (i.e., the main PyPI installation). |
| 236 | |
| 237 | .. cmdoption:: --upload-docs |
| 238 | |
| 239 | Also run :command:`upload_docs`. Mainly useful as a default value in |
| 240 | :file:`setup.cfg` (on the command line, it's shorter to just type both |
| 241 | commands). |
| 242 | |
| 243 | |
| 244 | :command:`upload_docs` |
| 245 | ---------------------- |
| 246 | |
| 247 | Upload HTML documentation to PyPI. |
| 248 | |
| 249 | PyPI now supports publishing project documentation at a URI of the form |
| 250 | ``http://packages.python.org/<project>``. :command:`upload_docs` will create |
| 251 | the necessary zip file out of a documentation directory and will post to the |
| 252 | repository. |
| 253 | |
| 254 | Note that to upload the documentation of a project, the corresponding version |
| 255 | must already be registered with PyPI, using the :command:`register` command --- |
| 256 | just like with :command:`upload`. |
| 257 | |
| 258 | Assuming there is an ``Example`` project with documentation in the subdirectory |
| 259 | :file:`docs`, for example:: |
| 260 | |
| 261 | Example/ |
| 262 | example.py |
| 263 | setup.cfg |
| 264 | docs/ |
| 265 | build/ |
| 266 | html/ |
| 267 | index.html |
| 268 | tips_tricks.html |
| 269 | conf.py |
| 270 | index.txt |
| 271 | tips_tricks.txt |
| 272 | |
| 273 | You can simply specify the directory with the HTML files in your |
| 274 | :file:`setup.cfg` file: |
| 275 | |
| 276 | .. code-block:: cfg |
| 277 | |
| 278 | [upload_docs] |
| 279 | upload-dir = docs/build/html |
| 280 | |
| 281 | |
| 282 | .. program:: packaging upload_docs |
| 283 | |
| 284 | .. cmdoption:: --upload-dir |
| 285 | |
| 286 | The directory to be uploaded to the repository. By default documentation |
| 287 | is searched for in ``docs`` (or ``doc``) directory in project root. |
| 288 | |
| 289 | .. cmdoption:: --show-response |
| 290 | |
| 291 | Display the full response text from server; this is useful for debugging |
| 292 | PyPI problems. |
| 293 | |
| 294 | .. cmdoption:: --repository=URL, -r URL |
| 295 | |
| 296 | The URL of the repository to upload to. Defaults to |
| 297 | http://pypi.python.org/pypi (i.e., the main PyPI installation). |
| 298 | |
| 299 | |
| 300 | The install step |
| 301 | ================ |
| 302 | |
| 303 | These commands are used by end-users of a project using :program:`pysetup` or |
| 304 | another compatible installer. Each command will run the corresponding |
| 305 | :command:`build_*` command and then move the built files to their destination on |
| 306 | the target system. |
| 307 | |
| 308 | |
| 309 | :command:`install_dist` |
| 310 | ----------------------- |
| 311 | |
| 312 | Install a distribution, delegating to the other :command:`install_*` commands to |
| 313 | do the work. |
| 314 | |
| 315 | .. program:: packaging install_dist |
| 316 | |
| 317 | .. cmdoption:: --user |
| 318 | |
| 319 | Install in user site-packages directory (see :PEP:`370`). |
| 320 | |
| 321 | |
| 322 | :command:`install_data` |
| 323 | ----------------------- |
| 324 | |
| 325 | Install data files. |
| 326 | |
| 327 | |
| 328 | :command:`install_distinfo` |
| 329 | --------------------------- |
| 330 | |
| 331 | Install files recording details of the installation as specified in :PEP:`376`. |
| 332 | |
| 333 | |
| 334 | :command:`install_headers` |
| 335 | -------------------------- |
| 336 | |
| 337 | Install C/C++ header files. |
| 338 | |
| 339 | |
| 340 | :command:`install_lib` |
| 341 | ---------------------- |
| 342 | |
| 343 | Install C library files. |
| 344 | |
| 345 | |
| 346 | :command:`install_scripts` |
| 347 | -------------------------- |
| 348 | |
| 349 | Install scripts. |