1
<?xml version="1.0" encoding="utf-8"?>
3
PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'
4
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
5
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
7
<title>Twisted Documentation: Working from Twisted's Subversion repository</title>
8
<link href="../../howto/stylesheet.css" rel="stylesheet" type="text/css"/>
11
<body bgcolor="white">
12
<h1 class="title">Working from Twisted's Subversion repository</h1>
13
<div class="toc"><ol><li><a href="#auto0">Checkout</a></li><li><a href="#auto1">Alternate tree names</a></li><li><a href="#auto2">Combinator</a></li><li><a href="#auto3">Compiling C extensions</a></li><li><a href="#auto4">Running tests</a></li><li><a href="#auto5">Building docs</a></li><li><a href="#auto6">Emacs</a></li><li><a href="#auto7">Building Debian packages</a></li></ol></div>
17
<p>If you're going to be doing development on Twisted itself, or if you want
18
to take advantage of bleeding-edge features (or bug fixes) that are not yet
19
available in a numbered release, you'll probably want to check out a tree from
20
the Twisted Subversion repository. The Trunk is where all current development
23
<p>This document lists some useful tips for working on this cutting
26
<h2>Checkout<a name="auto0"/></h2>
28
<p>Subversion tutorials can be found elsewhere, see in particular <a href="http://subversion.tigris.org/" shape="rect">the Subversion homepage</a>. The relevant
29
data you need to check out a copy of the Twisted tree is available on the <a href="http://twistedmatrix.com/trac/wiki/TwistedDevelopment" shape="rect">development page
30
</a>, and is as follows:</p>
32
<pre class="shell" xml:space="preserve">
33
$ svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk Twisted
36
<h2>Alternate tree names<a name="auto1"/></h2>
38
<p>By using <code>svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk
39
otherdir</code>, you can put the workspace tree in a directory other than
40
<q>Twisted</q>. I do this (with a name like <q>Twisted-Subversion</q>) to
41
remind myself that this tree comes from Subversion and not from a released
42
version (like <q>Twisted-1.0.5</q>). This practice can cause a few problems,
43
because there are a few places in the Twisted tree that need to know where
44
the tree starts, so they can add it to <code>sys.path</code> without
45
requiring the user manually set their PYTHONPATH. These functions walk the
46
current directory up to the root, looking for a directory named
47
<q>Twisted</q> (sometimes exactly that, sometimes with a
48
<code>.startswith</code> test). Generally these are test scripts or other
49
administrative tools which expect to be launched from somewhere inside the
50
tree (but not necessarily from the top).</p>
52
<p>If you rename the tree to something other than <code>Twisted</code>, these
53
tools may wind up trying to use Twisted source files from /usr/lib/python2.5
54
or elsewhere on the default <code>sys.path</code>. Normally this won't
55
matter, but it is good to be aware of the issue in case you run into
58
<p><code>twisted/test/process_twisted.py</code> is one of these programs.</p>
60
<h2>Combinator<a name="auto2"/></h2>
62
<p>In order to simplify the use of Subversion, we typically use
63
<a href="http://divmod.org/trac/wiki/DivmodCombinator" shape="rect">Divmod Combinator</a>.
64
You may find it to be useful, too. In particular, because Twisted uses
65
branches for almost all feature development, if you plan to contribute to
66
Twisted you will probably find Combinator very useful. For more details,
67
see the Combinator website, as well as the
68
<a href="http://divmod.org/trac/wiki/UltimateQualityDevelopmentSystem" shape="rect">
71
<h2>Compiling C extensions<a name="auto3"/></h2>
74
There are currently several C extension modules in Twisted:
75
twisted.protocols._c_urlarg, twisted.internet.cfsupport,
76
twisted.internet.iocpreactor._iocp, and twisted.python._epoll. These modules
77
are optional, but you'll have to compile them if you want to experience their
78
features, performance improvements, or bugs. There are two approaches.
81
<p>The first is to do a regular distutils <code>./setup.py build</code>, which
82
will create a directory under <code>build/</code> to hold both the generated
83
<code>.so</code> files as well as a copy of the 600-odd <code>.py</code> files
84
that make up Twisted. If you do this, you will need to set your PYTHONPATH to
85
something like <code>MyDir/Twisted/build/lib.linux-i686-2.5</code> in order to
86
run code against the Subversion twisted (as opposed to whatever's installed in
87
<code>/usr/lib/python2.5</code> or wherever python usually looks). In
88
addition, you will need to re-run the <code>build</code> command <em>every
89
time</em> you change a <code>.py</code> file. The <code>build/lib.foo</code>
90
directory is a copy of the main tree, and that copy is only updated when you
91
re-run <code>setup.py build</code>. It is easy to forget this and then wonder
92
why your code changes aren't being expressed.</p>
94
<p>The second technique is to build the C modules in place, and point your
95
PYTHONPATH at the top of the tree, like <code>MyDir/Twisted</code>. This way
96
you're using the .py files in place too, removing the confusion a forgotten
97
rebuild could cause with the separate build/ directory above. To build the C
98
modules in place, do <code>./setup.py build_ext -i</code>. You only need to
99
re-run this command when you change the C files. Note that
100
<code>setup.py</code> is not Make, it does not always get the dependencies
101
right (<code>.h</code> files in particular), so if you are hacking on the
102
cReactor you may need to manually delete the <code>.o</code> files before
103
doing a rebuild. Also note that doing a <code>setup.py clean</code> will
104
remove the <code>.o</code> files but not the final <code>.so</code> files,
105
they must be deleted by hand.</p>
108
<h2>Running tests<a name="auto4"/></h2>
110
<p>To run the full unit-test suite, do:</p>
112
<pre class="shell" xml:space="preserve">./bin/trial twisted</pre>
114
<p>To run a single test file (like <code>twisted/test/test_defer.py</code>),
117
<pre class="shell" xml:space="preserve">./bin/trial twisted.test.test_defer</pre>
121
<pre class="shell" xml:space="preserve">./bin/trial twisted/test/test_defer.py</pre>
123
<p>To run any tests that are related to a code file, like
124
<code>twisted/protocols/imap4.py</code>, do:</p>
126
<pre class="shell" xml:space="preserve">./bin/trial --testmodule twisted/mail/imap4.py</pre>
128
<p>This depends upon the <code>.py</code> file having an appropriate
129
<q>test-case-name</q> tag that indicates which test cases provide coverage.
130
See the <a href="test-standard.html" shape="rect">Test Standards</a> document for
131
details about using <q>test-case-name</q>. In this example, the
132
<code>twisted.mail.test.test_imap</code> test will be run.</p>
134
<p>Many tests create temporary files in /tmp or ./_trial_temp, but
135
everything in /tmp should be deleted when the test finishes. Sometimes these
136
cleanup calls are commented out by mistake, so if you see a stray
137
/tmp/@12345.1 directory, it is probably from test_dirdbm or test_popsicle.
138
Look for an <code>rmtree</code> that has been commented out and complain to
139
the last developer who touched that file.</p>
141
<h2>Building docs<a name="auto5"/></h2>
143
<p>Twisted documentation (not including the automatically-generated API docs)
144
is in <a href="http://twistedmatrix.com/trac/wiki/TwistedLore" shape="rect">Lore Format</a>.
145
These <code>.xhtml</code> files are translated into <code>.html</code> files by
146
the <q>bin/lore/lore</q> script, which can check the files for syntax problems
147
(hlint), process multiple files at once, insert the files into a template
148
before processing, and can also translate the files into LaTeX or PostScript
151
<p>To build the HTML form of the howto/ docs, do the following. Note that
152
the index file will be placed in <code>doc/howto/index.html</code>.</p>
154
<pre class="shell" xml:space="preserve">
155
./bin/lore/lore -p --config template=doc/howto/template.tpl doc/howto/*.xhtml
158
<p>To run hlint over a single Lore document, such as
159
<code>doc/development/policy/svn-dev.xhtml</code>, do the following. This is
160
useful because the HTML conversion may bail without a useful explanation if
161
it sees mismatched tags.</p>
163
<pre class="shell" xml:space="preserve">
164
./bin/lore/lore -n --output lint doc/development/policy/svn-dev.xhtml
167
<p>To convert it to HTML (including markup, interpolation of examples,
168
footnote processing, etc), do the following. The results will be placed in
169
<code>doc/development/policy/svn-dev.html</code>:</p>
171
<pre class="shell" xml:space="preserve">
172
./bin/lore/lore -p --config template=doc/howto/template.tpl \
173
doc/development/policy/svn-dev.xhtml
176
<p>Note that hyperlinks to other documents may not be quite right unless you
177
include a <q>-l</q> argument to <code>bin/lore/lore</code>. Links in the
178
.xhtml file are to .xhtml targets: when the .xhtml is turned into .html, the
179
link targets are supposed to be turned into .html also. In addition to this,
180
Lore markup of the form <code class="API"> is supposed to
181
turn into a link to the corresponding API reference page. These links will
182
probably be wrong unless the correct base URL is provided to Lore.</p>
184
<h2>Emacs<a name="auto6"/></h2>
186
<p>A minor mode for development with Twisted using Emacs is available. See
187
<code>emacs/twisted-dev.el</code> for several utility functions which make
188
it easier to grep for methods, run test cases, etc.</p>
190
<h2>Building Debian packages<a name="auto7"/></h2>
192
<p>Our support for building Debian packages has fallen into disrepair. We
193
would very much like to restore this functionality, but until we do so, if
194
you are interested in this, you are on your own. See
195
<a href="http://stdeb.python-hosting.com/" shape="rect">stdeb</a> for one possible approach
200
<p><a href="../../howto/index.html">Index</a></p>
201
<span class="version">Version: 9.0.0</span>
b'\\ No newline at end of file'