/Doc/distutils/sourcedist.rst
ReStructuredText | 209 lines | 151 code | 58 blank | 0 comment | 0 complexity | e0e5773937357e1387165f798bc91d65 MD5 | raw file
1.. _source-dist: 2 3****************************** 4Creating a Source Distribution 5****************************** 6 7As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command 8to 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 13or config file), :command:`sdist` creates the archive of the default format for 14the current platform. The default format is a gzip'ed tar file 15(:file:`.tar.gz`) on Unix, and ZIP file on Windows. 16 17You can specify as many formats as you like using the :option:`--formats` 18option, for example:: 19 20 python setup.py sdist --formats=gztar,zip 21 22to 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 41Notes: 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 60Specifying the files to distribute 61================================== 62 63If you don't supply an explicit list of files (or instructions on how to 64generate one), the :command:`sdist` command puts a minimal default set into the 65source 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 86Sometimes this is enough, but usually you will want to specify additional files 87to distribute. The typical way to do this is to write a *manifest template*, 88called :file:`MANIFEST.in` by default. The manifest template is just a list of 89instructions for how to generate your manifest file, :file:`MANIFEST`, which is 90the exact list of files to include in your source distribution. The 91:command:`sdist` command processes this template and generates a manifest based 92on its instructions and what it finds in the filesystem. 93 94If you prefer to roll your own manifest file, the format is simple: one filename 95per 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 97described above does not apply in this case. 98 99The manifest template has one command per line, where each command specifies a 100set of files to include or exclude from the source distribution. For an 101example, 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 107The meanings should be fairly clear: include all files in the distribution root 108matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory 109matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching 110:file:`examples/sample?/build`. All of this is done *after* the standard 111include set, so you can exclude files from the standard set with explicit 112instructions in the manifest template. (Or, you can use the 113:option:`--no-defaults` option to disable the standard set entirely.) There are 114several other commands available in the manifest template mini-language; see 115section :ref:`sdist-cmd`. 116 117The order of commands in the manifest template matters: initially, we have the 118list of default files as described above, and each command in the template adds 119to or removes from that list of files. Once we have fully processed the 120manifest template, we remove files that should not be included in the source 121distribution: 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 128Now we have our complete list of files, which is written to the manifest for 129future reference, and then used to build the source distribution archive(s). 130 131You can disable the default set of included files with the 132:option:`--no-defaults` option, and you can disable the standard exclude set 133with :option:`--no-prune`. 134 135Following the Distutils' own manifest template, let's trace how the 136:command:`sdist` command builds the list of files to include in the Distutils 137source 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 164Just like in the setup script, file and directory names in the manifest template 165should always be slash-separated; the Distutils will take care of converting 166them to the standard representation on your platform. That way, the manifest 167template is portable across operating systems. 168 169 170.. _manifest-options: 171 172Manifest-related options 173======================== 174 175The 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 190There 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 194Second, you might want to force the manifest to be regenerated---for example, if 195you have added or removed files or directories that match an existing pattern in 196the manifest template, you should regenerate the manifest:: 197 198 python setup.py sdist --force-manifest 199 200Or, you might just want to (re)generate the manifest, but not create a source 201distribution:: 202 203 python setup.py sdist --manifest-only 204 205:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a 206shortcut for :option:`--manifest-only`, and :option:`-f` for 207:option:`--force-manifest`. 208 209