diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/setuptools.txt | 96 |
1 files changed, 35 insertions, 61 deletions
diff --git a/docs/setuptools.txt b/docs/setuptools.txt index 610a0e61..d267bf29 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -258,10 +258,9 @@ unless you need the associated ``setuptools`` feature. ``include_package_data`` If set to ``True``, this tells ``setuptools`` to automatically include any - data files it finds inside your package directories, that are either under - CVS or Subversion control, or which are specified by your ``MANIFEST.in`` - file. For more information, see the section below on `Including Data - Files`_. + data files it finds inside your package directories that are specified by + your ``MANIFEST.in`` file. For more information, see the section below on + `Including Data Files`_. ``exclude_package_data`` A dictionary mapping package names to lists of glob patterns that should @@ -785,17 +784,15 @@ e.g.:: ) This tells setuptools to install any data files it finds in your packages. -The data files must be under CVS or Subversion control, or else they must be -specified via the distutils' ``MANIFEST.in`` file. (They can also be tracked -by another revision control system, using an appropriate plugin. See the -section below on `Adding Support for Other Revision Control Systems`_ for -information on how to write such plugins.) - -If the data files are not under version control, or are not in a supported -version control system, or if you want finer-grained control over what files -are included (for example, if you have documentation files in your package -directories and want to exclude them from installation), then you can also use -the ``package_data`` keyword, e.g.:: +The data files must be specified via the distutils' ``MANIFEST.in`` file. +(They can also be tracked by a revision control system, using an appropriate +plugin. See the section below on `Adding Support for Revision Control +Systems`_ for information on how to write such plugins.) + +If you want finer-grained control over what files are included (for example, +if you have documentation files in your package directories and want to exclude +them from installation), then you can also use the ``package_data`` keyword, +e.g.:: from setuptools import setup, find_packages setup( @@ -853,8 +850,7 @@ converts slashes to appropriate platform-specific separators at build time. Python 2.4; there is `some documentation for the feature`__ available on the python.org website. If using the setuptools-specific ``include_package_data`` argument, files specified by ``package_data`` will *not* be automatically -added to the manifest unless they are tracked by a supported version control -system, or are listed in the MANIFEST.in file.) +added to the manifest unless they are listed in the MANIFEST.in file.) __ http://docs.python.org/dist/node11.html @@ -887,8 +883,7 @@ included as a result of using ``include_package_data``. In summary, the three options allow you to: ``include_package_data`` - Accept all data files and directories matched by ``MANIFEST.in`` or found - in source control. + Accept all data files and directories matched by ``MANIFEST.in``. ``package_data`` Specify additional patterns to match files and directories that may or may @@ -1231,15 +1226,14 @@ Your Project's Dependencies target audience isn't able to compile packages (e.g. most Windows users) and your package or some of its dependencies include C code. -Subversion or CVS Users and Co-Developers +Revision Control System Users and Co-Developers Users and co-developers who are tracking your in-development code using - CVS, Subversion, or some other revision control system should probably read - this manual's sections regarding such development. Alternately, you may - wish to create a quick-reference guide containing the tips from this manual - that apply to your particular situation. For example, if you recommend - that people use ``setup.py develop`` when tracking your in-development - code, you should let them know that this needs to be run after every update - or commit. + a revision control system should probably read this manual's sections + regarding such development. Alternately, you may wish to create a + quick-reference guide containing the tips from this manual that apply to + your particular situation. For example, if you recommend that people use + ``setup.py develop`` when tracking your in-development code, you should let + them know that this needs to be run after every update or commit. Similarly, if you remove modules or data files from your project, you should remind them to run ``setup.py clean --all`` and delete any obsolete @@ -1467,25 +1461,10 @@ use the appropriate defaults.) Generating Source Distributions ------------------------------- -``setuptools`` enhances the distutils' default algorithm for source file -selection, so that all files managed by CVS or Subversion in your project tree -are included in any source distribution you build. This is a big improvement -over having to manually write a ``MANIFEST.in`` file and try to keep it in -sync with your project. So, if you are using CVS or Subversion, and your -source distributions only need to include files that you're tracking in -revision control, don't create a ``MANIFEST.in`` file for your project. -(And, if you already have one, you might consider deleting it the next time -you would otherwise have to change it.) - -(NOTE: other revision control systems besides CVS and Subversion can be -supported using plugins; see the section below on `Adding Support for Other -Revision Control Systems`_ for information on how to write such plugins.) - -If you need to include automatically generated files, or files that are kept in -an unsupported revision control system, you'll need to create a ``MANIFEST.in`` -file to specify any files that the default file location algorithm doesn't -catch. See the distutils documentation for more information on the format of -the ``MANIFEST.in`` file. +If you need to include automatically generated files, you'll need to create a +``MANIFEST.in`` file to specify any files that the default file location +algorithm doesn't catch. See the distutils documentation for more information +on the format of the ``MANIFEST.in`` file. But, be sure to ignore any part of the distutils documentation that deals with ``MANIFEST`` or how it's generated from ``MANIFEST.in``; setuptools shields you @@ -1501,12 +1480,6 @@ the options that the distutils' more complex ``sdist`` process requires. For all practical purposes, you'll probably use only the ``--formats`` option, if you use any option at all. -(By the way, if you're using some other revision control system, you might -consider creating and publishing a `revision control plugin for setuptools`_.) - - -.. _revision control plugin for setuptools: `Adding Support for Other Revision Control Systems`_ - Making your package available for EasyInstall --------------------------------------------- @@ -1687,9 +1660,10 @@ Of course, for this to work, your source distributions must include the C code generated by Pyrex, as well as your original ``.pyx`` files. This means that you will probably want to include current ``.c`` files in your revision control system, rebuilding them whenever you check changes in for the ``.pyx`` -source files. This will ensure that people tracking your project in CVS or -Subversion will be able to build it even if they don't have Pyrex installed, -and that your source releases will be similarly usable with or without Pyrex. +source files. This will ensure that people tracking your project in a revision +control system will be able to build it even if they don't have Pyrex +installed, and that your source releases will be similarly usable with or +without Pyrex. ----------------- @@ -2569,15 +2543,15 @@ the ``cmd`` object's ``write_file()``, ``delete_file()``, and those methods' docstrings for more details. -Adding Support for Other Revision Control Systems +Adding Support for Revision Control Systems ------------------------------------------------- If you would like to create a plugin for ``setuptools`` to find files in -source control systems, you can do so by adding an -entry point to the ``setuptools.file_finders`` group. The entry point should -be a function accepting a single directory name, and should yield -all the filenames within that directory (and any subdirectories thereof) that -are under revision control. +source control systems, you can do so by adding an entry point to the +``setuptools.file_finders`` group. The entry point should be a function +accepting a single directory name, and should yield all the filenames within +that directory (and any subdirectories thereof) that are under revision +control. For example, if you were going to create a plugin for a revision control system called "foobar", you would write a function something like this: |