Mercurial > cpython-lru_cache-weakref

annotate Doc/packaging/commandref.rst @ 73798:6cde416ef03b

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