setuptools_darcs-1.2.12.egg/share/doc/python-setuptools_darcs/README.txt

   1
   2 setuptools_darcs Manual
   3 =======================
   4
   5 About
   6 -----
   7
   8 This is a plugin for setuptools that integrates darcs.  Once
   9 installed, Setuptools can be told to include in a package distribution
  10 all the files tracked by darcs.  This is an alternative to explicit
  11 inclusion specifications with `MANIFEST.in`.
  12
  13 A distribution here refers to a package that you create using
  14 setup.py, ex:
  15
  16   python setup.py sdist
  17   python setup.py bdist_egg
  18   python setup.py bdist_rpm
  19
  20 This package was formerly known as setuptools_darcs_plugin.  The name
  21 change is the result of an agreement by the setuptools plugin
  22 developers to provide a uniform naming convention.
  23
  24
  25 Installation
  26 ------------
  27
  28 With easy_install:
  29
  30   easy_install setuptools_darcs
  31
  32 Alternative manual installation:
  33
  34   tar -zxvf setuptools_darcs-X.Y.Z.tar.gz
  35   cd setuptools_darcs-X.Y.Z
  36   python setup.py install
  37
  38 Where X.Y.Z is a version number.
  39
  40 Alternative to make a specific package use setuptools_darcs without
  41 installing setuptools_darcs into the system:
  42
  43   Put "setup_requires=['setuptools_darcs']" in the call to setup() in
  44   the package's setup.py file.
  45
  46
  47 Usage
  48 -----
  49
  50 To use this plugin, you must first package your python module with
  51 `setup.py` and use setuptools.  The former is well documented in the
  52 distutils manual:
  53
  54   http://docs.python.org/dist/dist.html
  55
  56 To use setuptools instead of distutils, just edit `setup.py` and
  57 change
  58
  59   from distutils.core import setup
  60
  61 to
  62
  63   from setuptools import setup
  64
  65 When setuptools builds a source package, it always includes all files
  66 tracked by your revision control system, if it knows how to learn what
  67 those files are.
  68
  69 When setuptools builds a binary package, you can ask it to include all
  70 files tracked by your revision control system, by adding this argument
  71 to your invocation of `setup()`:
  72
  73   setup(...,
  74     include_package_data=True,
  75     ...)
  76
  77 This plugin lets setuptools know what files are tracked by your darcs
  78 revision control tool.  setuptools ships with support for cvs and
  79 subversion.  Other plugins like this one are available for bzr, git,
  80 monotone, and mercurial, at least.
  81
  82 It might happen that you track files with your revision control system
  83 that you don't want to include in your packages.  In that case, you
  84 can prevent setuptools from packaging those files with a directive in
  85 your `MANIFEST.in`, ex:
  86
  87   exclude .darcs-boringfile
  88   recursive-exclude images *.xcf *.blend
  89
  90 In this example, we prevent setuptools from packaging
  91 `.darcs-boringfile` and the Gimp and Blender source files found under
  92 the `images` directory.
  93
  94 Alternatively, files to exclude from the package can be listed in the
  95 `setup()` directive:
  96
  97   setup(...,
  98     exclude_package_data = {'': ['.darcs-boringfile'],
  99                             'images': ['*.xcf', '*.blend']},
 100     ...)
 101
 102
 103 Gotchas
 104 -------
 105
 106 If someone clones your darcs repository using darcs but does not
 107 install this plugin, then when they run a package building command
 108 they will not get all the right files.  On the other hand if someone
 109 gets a source distribution that was created by "./setup.py sdist",
 110 then it will come with a list of all files, so they will not need
 111 darcs in order to build a distribution themselves.
 112
 113 You can make sure that anyone who uses your setup.py file has this
 114 plugin by adding a `setup_requires` argument.
 115
 116   setup_requires=[]
 117   # setuptools_darcs is required to produce complete distributions (such as with
 118   # "sdist" or "bdist_egg"), unless there is a ${PKG}.egg-info/SOURCES.txt file
 119   # present which contains a complete list of files that should be included in
 120   # distributions.
 121   # http://pypi.python.org/pypi/setuptools_darcs
 122   setup_requires.append('setuptools_darcs >= 1.1.0')
 123
 124   setup(...,
 125     setup_requires = setup_requires,
 126     ...)
 127
 128
 129 References
 130 ----------
 131
 132 How to distribute Python modules with Distutils:
 133
 134   http://docs.python.org/dist/dist.html
 135
 136
 137 Setuptools complete manual:
 138
 139   http://peak.telecommunity.com/DevCenter/setuptools
 140
 141
 142 Thanks to Yannick Gingras for providing the prototype for this
 143 README.txt.