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