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
  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