2 setuptools_darcs Manual
3 =======================
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`.
13 A distribution here refers to a package that you create using
17 python setup.py bdist_egg
18 python setup.py bdist_rpm
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.
30 easy_install setuptools_darcs
32 Alternative manual installation:
34 tar -zxvf setuptools_darcs-X.Y.Z.tar.gz
35 cd setuptools_darcs-X.Y.Z
36 python setup.py install
38 Where X.Y.Z is a version number.
40 Alternative to make a specific package use setuptools_darcs without
41 installing setuptools_darcs into the system:
43 Put "setup_requires=['setuptools_darcs']" in the call to setup() in
44 the package's setup.py file.
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
54 http://docs.python.org/dist/dist.html
56 To use setuptools instead of distutils, just edit `setup.py` and
59 from distutils.core import setup
63 from setuptools import setup
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
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()`:
74 include_package_data=True,
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.
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:
87 exclude .darcs-boringfile
88 recursive-exclude images *.xcf *.blend
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.
94 Alternatively, files to exclude from the package can be listed in the
98 exclude_package_data = {'': ['.darcs-boringfile'],
99 'images': ['*.xcf', '*.blend']},
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.
113 You can make sure that anyone who uses your setup.py file has this
114 plugin by adding a `setup_requires` argument.
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
121 # http://pypi.python.org/pypi/setuptools_darcs
122 setup_requires.append('setuptools_darcs >= 1.1.0')
125 setup_requires = setup_requires,
132 How to distribute Python modules with Distutils:
134 http://docs.python.org/dist/dist.html
137 Setuptools complete manual:
139 http://peak.telecommunity.com/DevCenter/setuptools
142 Thanks to Yannick Gingras for providing the prototype for this