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) | 30 | | (:file:`.tar.gz`) | | 31 +-----------+-------------------------+---------+ 32 | ``bztar`` | bzip2'ed tar file | | 33 | | (:file:`.tar.bz2`) | | 34 +-----------+-------------------------+---------+ 35 | ``xztar`` | xz'ed tar file | | 36 | | (:file:`.tar.xz`) | | 37 +-----------+-------------------------+---------+ 38 | ``ztar`` | compressed tar file | \(4) | 39 | | (:file:`.tar.Z`) | | 40 +-----------+-------------------------+---------+ 41 | ``tar`` | tar file (:file:`.tar`) | | 42 +-----------+-------------------------+---------+ 43 44 .. versionchanged:: 3.5 45 Added support for the ``xztar`` format. 46 47 Notes: 48 49 (1) 50 default on Windows 51 52 (2) 53 default on Unix 54 55 (3) 56 requires either external :program:`zip` utility or :mod:`zipfile` module (part 57 of the standard Python library since Python 1.6) 58 59 (4) 60 requires the :program:`compress` program. Notice that this format is now 61 pending for deprecation and will be removed in the future versions of Python. 62 63 When using any ``tar`` format (``gztar``, ``bztar``, ``xztar``, ``ztar`` or 64 ``tar``), under Unix you can specify the ``owner`` and ``group`` names 65 that will be set for each member of the archive. 66 67 For example, if you want all files of the archive to be owned by root:: 68 69 python setup.py sdist --owner=root --group=root 70 71 72 .. _manifest: 73 74 Specifying the files to distribute 75 ================================== 76 77 If you don't supply an explicit list of files (or instructions on how to 78 generate one), the :command:`sdist` command puts a minimal default set into the 79 source distribution: 80 81 * all Python source files implied by the ``py_modules`` and 82 ``packages`` options 83 84 * all C source files mentioned in the ``ext_modules`` or 85 ``libraries`` options 86 87 .. XXX getting C library sources currently broken---no 88 :meth:`get_source_files` method in :file:`build_clib.py`! 89 90 * scripts identified by the ``scripts`` option 91 See :ref:`distutils-installing-scripts`. 92 93 * anything that looks like a test script: :file:`test/test\*.py` (currently, the 94 Distutils don't do anything with test scripts except include them in source 95 distributions, but in the future there will be a standard for testing Python 96 module distributions) 97 98 * :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever you 99 called your setup script), and :file:`setup.cfg` 100 101 * all files that matches the ``package_data`` metadata. 102 See :ref:`distutils-installing-package-data`. 103 104 * all files that matches the ``data_files`` metadata. 105 See :ref:`distutils-additional-files`. 106 107 Sometimes this is enough, but usually you will want to specify additional files 108 to distribute. The typical way to do this is to write a *manifest template*, 109 called :file:`MANIFEST.in` by default. The manifest template is just a list of 110 instructions for how to generate your manifest file, :file:`MANIFEST`, which is 111 the exact list of files to include in your source distribution. The 112 :command:`sdist` command processes this template and generates a manifest based 113 on its instructions and what it finds in the filesystem. 114 115 If you prefer to roll your own manifest file, the format is simple: one filename 116 per line, regular files (or symlinks to them) only. If you do supply your own 117 :file:`MANIFEST`, you must specify everything: the default set of files 118 described above does not apply in this case. 119 120 .. versionchanged:: 3.1 121 An existing generated :file:`MANIFEST` will be regenerated without 122 :command:`sdist` comparing its modification time to the one of 123 :file:`MANIFEST.in` or :file:`setup.py`. 124 125 .. versionchanged:: 3.1.3 126 :file:`MANIFEST` files start with a comment indicating they are generated. 127 Files without this comment are not overwritten or removed. 128 129 .. versionchanged:: 3.2.2 130 :command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in` 131 exists, like it used to do. 132 133 134 The manifest template has one command per line, where each command specifies a 135 set of files to include or exclude from the source distribution. For an 136 example, again we turn to the Distutils' own manifest template: 137 138 .. code-block:: none 139 140 include *.txt 141 recursive-include examples *.txt *.py 142 prune examples/sample?/build 143 144 The meanings should be fairly clear: include all files in the distribution root 145 matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory 146 matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching 147 :file:`examples/sample?/build`. All of this is done *after* the standard 148 include set, so you can exclude files from the standard set with explicit 149 instructions in the manifest template. (Or, you can use the 150 :option:`!--no-defaults` option to disable the standard set entirely.) There are 151 several other commands available in the manifest template mini-language; see 152 section :ref:`sdist-cmd`. 153 154 The order of commands in the manifest template matters: initially, we have the 155 list of default files as described above, and each command in the template adds 156 to or removes from that list of files. Once we have fully processed the 157 manifest template, we remove files that should not be included in the source 158 distribution: 159 160 * all files in the Distutils "build" tree (default :file:`build/`) 161 162 * all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`, 163 :file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs` 164 165 Now we have our complete list of files, which is written to the manifest for 166 future reference, and then used to build the source distribution archive(s). 167 168 You can disable the default set of included files with the 169 :option:`!--no-defaults` option, and you can disable the standard exclude set 170 with :option:`!--no-prune`. 171 172 Following the Distutils' own manifest template, let's trace how the 173 :command:`sdist` command builds the list of files to include in the Distutils 174 source distribution: 175 176 #. include all Python source files in the :file:`distutils` and 177 :file:`distutils/command` subdirectories (because packages corresponding to 178 those two directories were mentioned in the ``packages`` option in the 179 setup script---see section :ref:`setup-script`) 180 181 #. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard 182 files) 183 184 #. include :file:`test/test\*.py` (standard files) 185 186 #. include :file:`\*.txt` in the distribution root (this will find 187 :file:`README.txt` a second time, but such redundancies are weeded out later) 188 189 #. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree 190 under :file:`examples`, 191 192 #. exclude all files in the sub-trees starting at directories matching 193 :file:`examples/sample?/build`\ ---this may exclude files included by the 194 previous two steps, so it's important that the ``prune`` command in the manifest 195 template comes after the ``recursive-include`` command 196 197 #. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`, 198 :file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs` 199 directories 200 201 Just like in the setup script, file and directory names in the manifest template 202 should always be slash-separated; the Distutils will take care of converting 203 them to the standard representation on your platform. That way, the manifest 204 template is portable across operating systems. 205 206 207 .. _manifest-options: 208 209 Manifest-related options 210 ======================== 211 212 The normal course of operations for the :command:`sdist` command is as follows: 213 214 * if the manifest file (:file:`MANIFEST` by default) exists and the first line 215 does not have a comment indicating it is generated from :file:`MANIFEST.in`, 216 then it is used as is, unaltered 217 218 * if the manifest file doesn't exist or has been previously automatically 219 generated, read :file:`MANIFEST.in` and create the manifest 220 221 * if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest 222 with just the default file set 223 224 * use the list of files now in :file:`MANIFEST` (either just generated or read 225 in) to create the source distribution archive(s) 226 227 There are a couple of options that modify this behaviour. First, use the 228 :option:`!--no-defaults` and :option:`!--no-prune` to disable the standard 229 "include" and "exclude" sets. 230 231 Second, you might just want to (re)generate the manifest, but not create a source 232 distribution:: 233 234 python setup.py sdist --manifest-only 235 236 :option:`!-o` is a shortcut for :option:`!--manifest-only`. 237
