|
1 .. _source-dist: |
|
2 |
|
3 ****************************** |
|
4 Creating a Source Distribution |
|
5 ****************************** |
|
6 |
|
7 As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command |
|
8 to create a source distribution. In the simplest case, :: |
|
9 |
|
10 python setup.py sdist |
|
11 |
|
12 (assuming you haven't specified any :command:`sdist` options in the setup script |
|
13 or config file), :command:`sdist` creates the archive of the default format for |
|
14 the current platform. The default format is a gzip'ed tar file |
|
15 (:file:`.tar.gz`) on Unix, and ZIP file on Windows. |
|
16 |
|
17 You can specify as many formats as you like using the :option:`--formats` |
|
18 option, for example:: |
|
19 |
|
20 python setup.py sdist --formats=gztar,zip |
|
21 |
|
22 to create a gzipped tarball and a zip file. The available formats are: |
|
23 |
|
24 +-----------+-------------------------+---------+ |
|
25 | Format | Description | Notes | |
|
26 +===========+=========================+=========+ |
|
27 | ``zip`` | zip file (:file:`.zip`) | (1),(3) | |
|
28 +-----------+-------------------------+---------+ |
|
29 | ``gztar`` | gzip'ed tar file | (2),(4) | |
|
30 | | (:file:`.tar.gz`) | | |
|
31 +-----------+-------------------------+---------+ |
|
32 | ``bztar`` | bzip2'ed tar file | \(4) | |
|
33 | | (:file:`.tar.bz2`) | | |
|
34 +-----------+-------------------------+---------+ |
|
35 | ``ztar`` | compressed tar file | \(4) | |
|
36 | | (:file:`.tar.Z`) | | |
|
37 +-----------+-------------------------+---------+ |
|
38 | ``tar`` | tar file (:file:`.tar`) | \(4) | |
|
39 +-----------+-------------------------+---------+ |
|
40 |
|
41 Notes: |
|
42 |
|
43 (1) |
|
44 default on Windows |
|
45 |
|
46 (2) |
|
47 default on Unix |
|
48 |
|
49 (3) |
|
50 requires either external :program:`zip` utility or :mod:`zipfile` module (part |
|
51 of the standard Python library since Python 1.6) |
|
52 |
|
53 (4) |
|
54 requires external utilities: :program:`tar` and possibly one of :program:`gzip`, |
|
55 :program:`bzip2`, or :program:`compress` |
|
56 |
|
57 |
|
58 .. _manifest: |
|
59 |
|
60 Specifying the files to distribute |
|
61 ================================== |
|
62 |
|
63 If you don't supply an explicit list of files (or instructions on how to |
|
64 generate one), the :command:`sdist` command puts a minimal default set into the |
|
65 source distribution: |
|
66 |
|
67 * all Python source files implied by the :option:`py_modules` and |
|
68 :option:`packages` options |
|
69 |
|
70 * all C source files mentioned in the :option:`ext_modules` or |
|
71 :option:`libraries` options ( |
|
72 |
|
73 **\*\*** getting C library sources currently broken---no |
|
74 :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***) |
|
75 |
|
76 * scripts identified by the :option:`scripts` option |
|
77 |
|
78 * anything that looks like a test script: :file:`test/test\*.py` (currently, the |
|
79 Distutils don't do anything with test scripts except include them in source |
|
80 distributions, but in the future there will be a standard for testing Python |
|
81 module distributions) |
|
82 |
|
83 * :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever you |
|
84 called your setup script), and :file:`setup.cfg` |
|
85 |
|
86 Sometimes this is enough, but usually you will want to specify additional files |
|
87 to distribute. The typical way to do this is to write a *manifest template*, |
|
88 called :file:`MANIFEST.in` by default. The manifest template is just a list of |
|
89 instructions for how to generate your manifest file, :file:`MANIFEST`, which is |
|
90 the exact list of files to include in your source distribution. The |
|
91 :command:`sdist` command processes this template and generates a manifest based |
|
92 on its instructions and what it finds in the filesystem. |
|
93 |
|
94 If you prefer to roll your own manifest file, the format is simple: one filename |
|
95 per line, regular files (or symlinks to them) only. If you do supply your own |
|
96 :file:`MANIFEST`, you must specify everything: the default set of files |
|
97 described above does not apply in this case. |
|
98 |
|
99 The manifest template has one command per line, where each command specifies a |
|
100 set of files to include or exclude from the source distribution. For an |
|
101 example, again we turn to the Distutils' own manifest template:: |
|
102 |
|
103 include *.txt |
|
104 recursive-include examples *.txt *.py |
|
105 prune examples/sample?/build |
|
106 |
|
107 The meanings should be fairly clear: include all files in the distribution root |
|
108 matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory |
|
109 matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching |
|
110 :file:`examples/sample?/build`. All of this is done *after* the standard |
|
111 include set, so you can exclude files from the standard set with explicit |
|
112 instructions in the manifest template. (Or, you can use the |
|
113 :option:`--no-defaults` option to disable the standard set entirely.) There are |
|
114 several other commands available in the manifest template mini-language; see |
|
115 section :ref:`sdist-cmd`. |
|
116 |
|
117 The order of commands in the manifest template matters: initially, we have the |
|
118 list of default files as described above, and each command in the template adds |
|
119 to or removes from that list of files. Once we have fully processed the |
|
120 manifest template, we remove files that should not be included in the source |
|
121 distribution: |
|
122 |
|
123 * all files in the Distutils "build" tree (default :file:`build/`) |
|
124 |
|
125 * all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`, |
|
126 :file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs` |
|
127 |
|
128 Now we have our complete list of files, which is written to the manifest for |
|
129 future reference, and then used to build the source distribution archive(s). |
|
130 |
|
131 You can disable the default set of included files with the |
|
132 :option:`--no-defaults` option, and you can disable the standard exclude set |
|
133 with :option:`--no-prune`. |
|
134 |
|
135 Following the Distutils' own manifest template, let's trace how the |
|
136 :command:`sdist` command builds the list of files to include in the Distutils |
|
137 source distribution: |
|
138 |
|
139 #. include all Python source files in the :file:`distutils` and |
|
140 :file:`distutils/command` subdirectories (because packages corresponding to |
|
141 those two directories were mentioned in the :option:`packages` option in the |
|
142 setup script---see section :ref:`setup-script`) |
|
143 |
|
144 #. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard |
|
145 files) |
|
146 |
|
147 #. include :file:`test/test\*.py` (standard files) |
|
148 |
|
149 #. include :file:`\*.txt` in the distribution root (this will find |
|
150 :file:`README.txt` a second time, but such redundancies are weeded out later) |
|
151 |
|
152 #. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree |
|
153 under :file:`examples`, |
|
154 |
|
155 #. exclude all files in the sub-trees starting at directories matching |
|
156 :file:`examples/sample?/build`\ ---this may exclude files included by the |
|
157 previous two steps, so it's important that the ``prune`` command in the manifest |
|
158 template comes after the ``recursive-include`` command |
|
159 |
|
160 #. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`, |
|
161 :file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs` |
|
162 directories |
|
163 |
|
164 Just like in the setup script, file and directory names in the manifest template |
|
165 should always be slash-separated; the Distutils will take care of converting |
|
166 them to the standard representation on your platform. That way, the manifest |
|
167 template is portable across operating systems. |
|
168 |
|
169 |
|
170 .. _manifest-options: |
|
171 |
|
172 Manifest-related options |
|
173 ======================== |
|
174 |
|
175 The normal course of operations for the :command:`sdist` command is as follows: |
|
176 |
|
177 * if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` |
|
178 and create the manifest |
|
179 |
|
180 * if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest |
|
181 with just the default file set |
|
182 |
|
183 * if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more |
|
184 recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading |
|
185 :file:`MANIFEST.in` |
|
186 |
|
187 * use the list of files now in :file:`MANIFEST` (either just generated or read |
|
188 in) to create the source distribution archive(s) |
|
189 |
|
190 There are a couple of options that modify this behaviour. First, use the |
|
191 :option:`--no-defaults` and :option:`--no-prune` to disable the standard |
|
192 "include" and "exclude" sets. |
|
193 |
|
194 Second, you might want to force the manifest to be regenerated---for example, if |
|
195 you have added or removed files or directories that match an existing pattern in |
|
196 the manifest template, you should regenerate the manifest:: |
|
197 |
|
198 python setup.py sdist --force-manifest |
|
199 |
|
200 Or, you might just want to (re)generate the manifest, but not create a source |
|
201 distribution:: |
|
202 |
|
203 python setup.py sdist --manifest-only |
|
204 |
|
205 :option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a |
|
206 shortcut for :option:`--manifest-only`, and :option:`-f` for |
|
207 :option:`--force-manifest`. |
|
208 |
|
209 |