/Doc/distutils/sourcedist.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 209 lines · 151 code · 58 blank · 0 comment · 0 complexity · e0e5773937357e1387165f798bc91d65 MD5 · raw file

  1. .. _source-dist:
  2. ******************************
  3. Creating a Source Distribution
  4. ******************************
  5. As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command
  6. to create a source distribution. In the simplest case, ::
  7. python setup.py sdist
  8. (assuming you haven't specified any :command:`sdist` options in the setup script
  9. or config file), :command:`sdist` creates the archive of the default format for
  10. the current platform. The default format is a gzip'ed tar file
  11. (:file:`.tar.gz`) on Unix, and ZIP file on Windows.
  12. You can specify as many formats as you like using the :option:`--formats`
  13. option, for example::
  14. python setup.py sdist --formats=gztar,zip
  15. to create a gzipped tarball and a zip file. The available formats are:
  16. +-----------+-------------------------+---------+
  17. | Format | Description | Notes |
  18. +===========+=========================+=========+
  19. | ``zip`` | zip file (:file:`.zip`) | (1),(3) |
  20. +-----------+-------------------------+---------+
  21. | ``gztar`` | gzip'ed tar file | (2),(4) |
  22. | | (:file:`.tar.gz`) | |
  23. +-----------+-------------------------+---------+
  24. | ``bztar`` | bzip2'ed tar file | \(4) |
  25. | | (:file:`.tar.bz2`) | |
  26. +-----------+-------------------------+---------+
  27. | ``ztar`` | compressed tar file | \(4) |
  28. | | (:file:`.tar.Z`) | |
  29. +-----------+-------------------------+---------+
  30. | ``tar`` | tar file (:file:`.tar`) | \(4) |
  31. +-----------+-------------------------+---------+
  32. Notes:
  33. (1)
  34. default on Windows
  35. (2)
  36. default on Unix
  37. (3)
  38. requires either external :program:`zip` utility or :mod:`zipfile` module (part
  39. of the standard Python library since Python 1.6)
  40. (4)
  41. requires external utilities: :program:`tar` and possibly one of :program:`gzip`,
  42. :program:`bzip2`, or :program:`compress`
  43. .. _manifest:
  44. Specifying the files to distribute
  45. ==================================
  46. If you don't supply an explicit list of files (or instructions on how to
  47. generate one), the :command:`sdist` command puts a minimal default set into the
  48. source distribution:
  49. * all Python source files implied by the :option:`py_modules` and
  50. :option:`packages` options
  51. * all C source files mentioned in the :option:`ext_modules` or
  52. :option:`libraries` options (
  53. **\*\*** getting C library sources currently broken---no
  54. :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***)
  55. * scripts identified by the :option:`scripts` option
  56. * anything that looks like a test script: :file:`test/test\*.py` (currently, the
  57. Distutils don't do anything with test scripts except include them in source
  58. distributions, but in the future there will be a standard for testing Python
  59. module distributions)
  60. * :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever you
  61. called your setup script), and :file:`setup.cfg`
  62. Sometimes this is enough, but usually you will want to specify additional files
  63. to distribute. The typical way to do this is to write a *manifest template*,
  64. called :file:`MANIFEST.in` by default. The manifest template is just a list of
  65. instructions for how to generate your manifest file, :file:`MANIFEST`, which is
  66. the exact list of files to include in your source distribution. The
  67. :command:`sdist` command processes this template and generates a manifest based
  68. on its instructions and what it finds in the filesystem.
  69. If you prefer to roll your own manifest file, the format is simple: one filename
  70. per line, regular files (or symlinks to them) only. If you do supply your own
  71. :file:`MANIFEST`, you must specify everything: the default set of files
  72. described above does not apply in this case.
  73. The manifest template has one command per line, where each command specifies a
  74. set of files to include or exclude from the source distribution. For an
  75. example, again we turn to the Distutils' own manifest template::
  76. include *.txt
  77. recursive-include examples *.txt *.py
  78. prune examples/sample?/build
  79. The meanings should be fairly clear: include all files in the distribution root
  80. matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory
  81. matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching
  82. :file:`examples/sample?/build`. All of this is done *after* the standard
  83. include set, so you can exclude files from the standard set with explicit
  84. instructions in the manifest template. (Or, you can use the
  85. :option:`--no-defaults` option to disable the standard set entirely.) There are
  86. several other commands available in the manifest template mini-language; see
  87. section :ref:`sdist-cmd`.
  88. The order of commands in the manifest template matters: initially, we have the
  89. list of default files as described above, and each command in the template adds
  90. to or removes from that list of files. Once we have fully processed the
  91. manifest template, we remove files that should not be included in the source
  92. distribution:
  93. * all files in the Distutils "build" tree (default :file:`build/`)
  94. * all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`,
  95. :file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs`
  96. Now we have our complete list of files, which is written to the manifest for
  97. future reference, and then used to build the source distribution archive(s).
  98. You can disable the default set of included files with the
  99. :option:`--no-defaults` option, and you can disable the standard exclude set
  100. with :option:`--no-prune`.
  101. Following the Distutils' own manifest template, let's trace how the
  102. :command:`sdist` command builds the list of files to include in the Distutils
  103. source distribution:
  104. #. include all Python source files in the :file:`distutils` and
  105. :file:`distutils/command` subdirectories (because packages corresponding to
  106. those two directories were mentioned in the :option:`packages` option in the
  107. setup script---see section :ref:`setup-script`)
  108. #. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard
  109. files)
  110. #. include :file:`test/test\*.py` (standard files)
  111. #. include :file:`\*.txt` in the distribution root (this will find
  112. :file:`README.txt` a second time, but such redundancies are weeded out later)
  113. #. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree
  114. under :file:`examples`,
  115. #. exclude all files in the sub-trees starting at directories matching
  116. :file:`examples/sample?/build`\ ---this may exclude files included by the
  117. previous two steps, so it's important that the ``prune`` command in the manifest
  118. template comes after the ``recursive-include`` command
  119. #. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`,
  120. :file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs`
  121. directories
  122. Just like in the setup script, file and directory names in the manifest template
  123. should always be slash-separated; the Distutils will take care of converting
  124. them to the standard representation on your platform. That way, the manifest
  125. template is portable across operating systems.
  126. .. _manifest-options:
  127. Manifest-related options
  128. ========================
  129. The normal course of operations for the :command:`sdist` command is as follows:
  130. * if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in`
  131. and create the manifest
  132. * if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
  133. with just the default file set
  134. * if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
  135. recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
  136. :file:`MANIFEST.in`
  137. * use the list of files now in :file:`MANIFEST` (either just generated or read
  138. in) to create the source distribution archive(s)
  139. There are a couple of options that modify this behaviour. First, use the
  140. :option:`--no-defaults` and :option:`--no-prune` to disable the standard
  141. "include" and "exclude" sets.
  142. Second, you might want to force the manifest to be regenerated---for example, if
  143. you have added or removed files or directories that match an existing pattern in
  144. the manifest template, you should regenerate the manifest::
  145. python setup.py sdist --force-manifest
  146. Or, you might just want to (re)generate the manifest, but not create a source
  147. distribution::
  148. python setup.py sdist --manifest-only
  149. :option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a
  150. shortcut for :option:`--manifest-only`, and :option:`-f` for
  151. :option:`--force-manifest`.