summaryrefslogtreecommitdiffstats
path: root/Doc/packaging/commandref.rst
blob: 5fe802f95d33321a725db1097c5e06fb53185890 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
.. _packaging-command-reference:

*****************
Command Reference
*****************

This reference briefly documents all standard Packaging commands and some of
their options.

.. FIXME does not work: Use pysetup run --help-commands to list all
   standard and extra commands availavble on your system, with their
   description.  Use pysetup run <command> --help to get help about the options
   of one command.


Preparing distributions
=======================

:command:`check`
----------------

Perform some tests on the metadata of a distribution.

For example, it verifies that all required metadata fields are provided in the
:file:`setup.cfg` file.

.. TODO document reST checks


:command:`test`
---------------

Run a test suite.

When doing test-driven development, or running automated builds that need
testing before they are installed for downloading or use, it's often useful to
be able to run a project's unit tests without actually installing the project
anywhere.  The :command:`test` command runs project's unit tests without
actually installing it, by temporarily putting the project's source on
:data:`sys.path`, after first running :command:`build_ext -i` to ensure that any
C extensions are built.

You can use this command in one of two ways: either by specifying a
unittest-compatible test suite for your project (or any callable that returns
it) or by passing a test runner function that will run your tests and display
results in the console.  Both options take a Python dotted name in the form
``package.module.callable`` to specify the object to use.

If none of these options are specified, Packaging will try to perform test
discovery using either unittest (for Python 3.2 and higher) or unittest2 (for
older versions, if installed).

.. this is a pseudo-command name used to disambiguate the options in indexes and
   links
.. program:: packaging test

.. cmdoption:: --suite=NAME, -s NAME

   Specify the test suite (or module, class, or method) to be run.  The default
   for this option can be set by in the project's :file:`setup.cfg` file:

   .. code-block:: cfg

      [test]
      suite = mypackage.tests.get_all_tests

.. cmdoption:: --runner=NAME, -r NAME

   Specify the test runner to be called.


:command:`config`
-----------------

Perform distribution configuration.


The build step
==============

This step is mainly useful to compile C/C++ libraries or extension modules.  The
build commands can be run manually to check for syntax errors or packaging
issues (for example if the addition of a new source file was forgotten in the
:file:`setup.cfg` file), and is also run automatically by commands which need
it.  Packaging checks the mtime of source and built files to avoid re-building
if it's not necessary.


:command:`build`
----------------

Build all files of a distribution, delegating to the other :command:`build_*`
commands to do the work.


:command:`build_clib`
---------------------

Build C libraries.


:command:`build_ext`
--------------------

Build C/C++ extension modules.


:command:`build_py`
-------------------

Build the Python modules (just copy them to the build directory) and
byte-compile them to .pyc files.


:command:`build_scripts`
------------------------
Build the scripts (just copy them to the build directory and adjust their
shebang if they're Python scripts).


:command:`clean`
----------------

Clean the build tree of the release.

.. program:: packaging clean

.. cmdoption:: --all, -a

   Remove build directories for modules, scripts, etc., not only temporary build
   by-products.


Creating source and built distributions
=======================================

:command:`sdist`
----------------

Build a source distribution for a release.

It is recommended that you always build and upload a source distribution.  Users
of OSes with easy access to compilers and users of advanced packaging tools will
prefer to compile from source rather than using pre-built distributions.  For
Windows users, providing a binary installer is also recommended practice.


:command:`bdist`
----------------

Build a binary distribution for a release.

This command will call other :command:`bdist_*` commands to create one or more
distributions depending on the options given.  The default is to create a
.tar.gz archive on Unix and a zip archive on Windows or OS/2.

.. program:: packaging bdist

.. cmdoption:: --formats

   Binary formats to build (comma-separated list).

.. cmdoption:: --show-formats

   Dump list of available formats.


:command:`bdist_dumb`
---------------------

Build a "dumb" installer, a simple archive of files that could be unpacked under
``$prefix`` or ``$exec_prefix``.


:command:`bdist_wininst`
------------------------

Build a Windows installer.


:command:`bdist_msi`
--------------------

Build a `Microsoft Installer`_ (.msi) file.

.. _Microsoft Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx

In most cases, the :command:`bdist_msi` installer is a better choice than the
:command:`bdist_wininst` installer, because it provides better support for Win64
platforms, allows administrators to perform non-interactive installations, and
allows installation through group policies.


Publishing distributions
========================

:command:`register`
-------------------

This command registers the current release with the Python Package Index.  This
is described in more detail in :PEP:`301`.

.. TODO explain user and project registration with the web UI


:command:`upload`
-----------------

Upload source and/or binary distributions to PyPI.

The distributions have to be built on the same command line as the
:command:`upload` command; see :ref:`packaging-package-upload` for more info.

.. program:: packaging upload

.. cmdoption:: --sign, -s

   Sign each uploaded file using GPG (GNU Privacy Guard).  The ``gpg`` program
   must be available for execution on the system ``PATH``.

.. cmdoption:: --identity=NAME, -i NAME

   Specify the identity or key name for GPG to use when signing.  The value of
   this option will be passed through the ``--local-user`` option of the
   ``gpg`` program.

.. cmdoption:: --show-response

   Display the full response text from server; this is useful for debugging
   PyPI problems.

.. cmdoption:: --repository=URL, -r URL

   The URL of the repository to upload to.  Defaults to
   http://pypi.python.org/pypi (i.e., the main PyPI installation).

.. cmdoption:: --upload-docs

   Also run :command:`upload_docs`.  Mainly useful as a default value in
   :file:`setup.cfg` (on the command line, it's shorter to just type both
   commands).


:command:`upload_docs`
----------------------

Upload HTML documentation to PyPI.

PyPI now supports publishing project documentation at a URI of the form
``http://packages.python.org/<project>``.  :command:`upload_docs`  will create
the necessary zip file out of a documentation directory and will post to the
repository.

Note that to upload the documentation of a project, the corresponding version
must already be registered with PyPI, using the :command:`register` command ---
just like with :command:`upload`.

Assuming there is an ``Example`` project with documentation in the subdirectory
:file:`docs`, for example::

   Example/
      example.py
      setup.cfg
      docs/
         build/
            html/
               index.html
               tips_tricks.html
         conf.py
         index.txt
         tips_tricks.txt

You can simply specify the directory with the HTML files in your
:file:`setup.cfg` file:

.. code-block:: cfg

   [upload_docs]
   upload-dir = docs/build/html


.. program:: packaging upload_docs

.. cmdoption:: --upload-dir

   The directory to be uploaded to the repository. By default documentation
   is searched for in ``docs`` (or ``doc``) directory in project root.

.. cmdoption:: --show-response

   Display the full response text from server; this is useful for debugging
   PyPI problems.

.. cmdoption:: --repository=URL, -r URL

   The URL of the repository to upload to.  Defaults to
   http://pypi.python.org/pypi (i.e., the main PyPI installation).


The install step
================

These commands are used by end-users of a project using :program:`pysetup` or
another compatible installer.  Each command will run the corresponding
:command:`build_*` command and then move the built files to their destination on
the target system.


:command:`install_dist`
-----------------------

Install a distribution, delegating to the other :command:`install_*` commands to
do the work.

.. program:: packaging install_dist

.. cmdoption:: --user

   Install in user site-packages directory (see :PEP:`370`).


:command:`install_data`
-----------------------

Install data files.


:command:`install_distinfo`
---------------------------

Install files recording details of the installation as specified in :PEP:`376`.


:command:`install_headers`
--------------------------

Install C/C++ header files.


:command:`install_lib`
----------------------

Install C library files.


:command:`install_scripts`
--------------------------

Install scripts.