Doc/distutils/sourcedist.rst

   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   See :ref:`distutils-installing-scripts`.
  78
  79 * anything that looks like a test script: :file:`test/test\*.py` (currently, the
  80   Distutils don't do anything with test scripts except include them in source
  81   distributions, but in the future there will be a standard for testing Python
  82   module distributions)
  83
  84 * :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever  you
  85   called your setup script), and :file:`setup.cfg`
  86
  87 * all files that matches the ``package_data`` metadata.
  88   See :ref:`distutils-installing-package-data`.
  89
  90 * all files that matches the ``data_files`` metadata.
  91   See :ref:`distutils-additional-files`.
  92
  93 Sometimes this is enough, but usually you will want to specify additional files
  94 to distribute.  The typical way to do this is to write a *manifest template*,
  95 called :file:`MANIFEST.in` by default.  The manifest template is just a list of
  96 instructions for how to generate your manifest file, :file:`MANIFEST`, which is
  97 the exact list of files to include in your source distribution.  The
  98 :command:`sdist` command processes this template and generates a manifest based
  99 on its instructions and what it finds in the filesystem.
 100
 101 If you prefer to roll your own manifest file, the format is simple: one filename
 102 per line, regular files (or symlinks to them) only.  If you do supply your own
 103 :file:`MANIFEST`, you must specify everything: the default set of files
 104 described above does not apply in this case.
 105
 106 The manifest template has one command per line, where each command specifies a
 107 set of files to include or exclude from the source distribution.  For an
 108 example, again we turn to the Distutils' own manifest template::
 109
 110    include *.txt
 111    recursive-include examples *.txt *.py
 112    prune examples/sample?/build
 113
 114 The meanings should be fairly clear: include all files in the distribution root
 115 matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory
 116 matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching
 117 :file:`examples/sample?/build`.  All of this is done *after* the standard
 118 include set, so you can exclude files from the standard set with explicit
 119 instructions in the manifest template.  (Or, you can use the
 120 :option:`--no-defaults` option to disable the standard set entirely.)  There are
 121 several other commands available in the manifest template mini-language; see
 122 section :ref:`sdist-cmd`.
 123
 124 The order of commands in the manifest template matters: initially, we have the
 125 list of default files as described above, and each command in the template adds
 126 to or removes from that list of files.  Once we have fully processed the
 127 manifest template, we remove files that should not be included in the source
 128 distribution:
 129
 130 * all files in the Distutils "build" tree (default :file:`build/`)
 131
 132 * all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`,
 133   :file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs`
 134
 135 Now we have our complete list of files, which is written to the manifest for
 136 future reference, and then used to build the source distribution archive(s).
 137
 138 You can disable the default set of included files with the
 139 :option:`--no-defaults` option, and you can disable the standard exclude set
 140 with :option:`--no-prune`.
 141
 142 Following the Distutils' own manifest template, let's trace how the
 143 :command:`sdist` command builds the list of files to include in the Distutils
 144 source distribution:
 145
 146 #. include all Python source files in the :file:`distutils` and
 147    :file:`distutils/command` subdirectories (because packages corresponding to
 148    those two directories were mentioned in the :option:`packages` option in the
 149    setup script---see section :ref:`setup-script`)
 150
 151 #. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard
 152    files)
 153
 154 #. include :file:`test/test\*.py` (standard files)
 155
 156 #. include :file:`\*.txt` in the distribution root (this will find
 157    :file:`README.txt` a second time, but such redundancies are weeded out later)
 158
 159 #. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree
 160    under :file:`examples`,
 161
 162 #. exclude all files in the sub-trees starting at directories matching
 163    :file:`examples/sample?/build`\ ---this may exclude files included by the
 164    previous two steps, so it's important that the ``prune`` command in the manifest
 165    template comes after the ``recursive-include`` command
 166
 167 #. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`,
 168    :file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs`
 169    directories
 170
 171 Just like in the setup script, file and directory names in the manifest template
 172 should always be slash-separated; the Distutils will take care of converting
 173 them to the standard representation on your platform. That way, the manifest
 174 template is portable across operating systems.
 175
 176
 177 .. _manifest-options:
 178
 179 Manifest-related options
 180 ========================
 181
 182 The normal course of operations for the :command:`sdist` command is as follows:
 183
 184 * if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in`
 185   and create the manifest
 186
 187 * if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
 188   with just the default file set
 189
 190 * if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
 191   recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
 192   :file:`MANIFEST.in`
 193
 194 * use the list of files now in :file:`MANIFEST` (either just generated or read
 195   in) to create the source distribution archive(s)
 196
 197 There are a couple of options that modify this behaviour.  First, use the
 198 :option:`--no-defaults` and :option:`--no-prune` to disable the standard
 199 "include" and "exclude" sets.
 200
 201 Second, you might want to force the manifest to be regenerated---for example, if
 202 you have added or removed files or directories that match an existing pattern in
 203 the manifest template, you should regenerate the manifest::
 204
 205    python setup.py sdist --force-manifest
 206
 207 Or, you might just want to (re)generate the manifest, but not create a source
 208 distribution::
 209
 210    python setup.py sdist --manifest-only
 211
 212 :option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a
 213 shortcut for :option:`--manifest-only`, and :option:`-f` for
 214 :option:`--force-manifest`.
 215
 216