Mercurial > cpython-lru_cache-weakref
annotate Doc/packaging/commandref.rst @ 73323:dad02a080bbc
Improve byte-compilation in packaging to be independent of -O or -B.
The code I fixed to comply with PEP 3147 still had one bug: When run
under python -O, some paths for pyc files would be pyo, because I called
imp.cache_from_source without explicit debug_override argument in some
places, and under -O that would return .pyo (this is well explained in
the imp docs). Now all code (util.byte_compile, build_py, install_lib)
can create .pyo files according to options given by users,
without interference from the calling Python’s own optimize mode.
On a related topic, I also removed the code that prevented byte
compilation under python -B. The rationale is that packaging gives
control over the creation of pyc files to the user with its own explicit
option, and the behavior should not be changed if the calling Python
happens to run with -B for whatever reason. I will argue that this is a
bug fix and ask to be allowed to backport this change to distutils.
Finally, I moved one nugget of information about the --compile and
--optimize options from the source into the doc. It clears up a
misunderstanding that I (and maybe other people) had.
| author | Éric Araujo <merwok@netwok.org> |
|---|---|
| date | Thu, 03 Nov 2011 05:08:28 +0100 |
| parents | d354802a637d |
| children |
| 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. |
