/Doc/distutils/sourcedist.rst

  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