1
<?xml version="1.0"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: Working from Twisted's Subversion repository</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Working from Twisted's Subversion repository</h1><div class="toc"><ol><li><a href="#auto0">Checkout</a></li><li><a href="#auto1">Alternate tree names</a></li><li><a href="#auto2">Compiling C extensions</a></li><li><a href="#auto3">Running tests</a></li><li><a href="#auto4">Admin scripts</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><div class="content"><span></span><p>If you're going to be doing development on Twisted itself, or if you want
3
to take advantage of bleeding-edge features (or bug fixes) that are not yet
4
available in a numbered release, you'll probably want to check out a tree from
5
the Twisted Subversion repository. The Trunk is where all current development
6
takes place.</p><p>This document lists some useful tips for working on this cutting
7
edge.</p><h2>Checkout<a name="auto0"></a></h2><p>Subversion tutorials can be found elsewhere, see in particular <a href="http://subversion.tigris.org/">the Subversion homepage</a>. The relevant
8
data you need to check out a copy of the Twisted tree is available on the <a href="http://twistedmatrix.com/developers/cvs">pserver page</a>, and is as
9
follows:</p><pre class="shell">
10
$ svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk Twisted
11
</pre><h2>Alternate tree names<a name="auto1"></a></h2><p>By using <code>svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk
12
otherdir</code>, you can put the workspace tree in a directory other than
13
<q>Twisted</q>. I do this (with a name like <q>Twisted-Subversion</q>) to
14
remind myself that this tree comes from Subversion and not from a released
15
version (like <q>Twisted-1.0.5</q>). This practice can cause a few problems,
16
because there are a few places in the Twisted tree that need to know where
17
the tree starts, so they can add it to <code>sys.path</code> without
18
requiring the user manually set their PYTHONPATH. These functions walk the
19
current directory up to the root, looking for a directory named
20
<q>Twisted</q> (sometimes exactly that, sometimes with a
21
<code>.startswith</code> test). Generally these are test scripts or other
22
administrative tools which expect to be launched from somewhere inside the
23
tree (but not necessarily from the top).</p><p>If you rename the tree to something other than <code>Twisted</code>, these
24
tools may wind up trying to use Twisted source files from /usr/lib/python2.2
25
or elsewhere on the default <code>sys.path</code>. Normally this won't
26
matter, but it is good to be aware of the issue in case you run into
27
problems.</p><p><code>twisted/test/process_twisted.py</code> is one of these programs.</p><h2>Compiling C extensions<a name="auto2"></a></h2><p>
28
There are currently several C extension modules in Twisted:
29
twisted.protocols._c_urlarg, twisted.internet.cfsupport,
30
twisted.internet.iocpreactor._iocp, and twisted.python._epoll. These modules
31
are optional, but you'll have to compile them if you want to experience their
32
features, performance improvements, or bugs. There are two approaches.
33
</p><p>The first is to do a regular distutils <code>./setup.py build</code>, which
34
will create a directory under <code>build/</code> to hold both the generated
35
<code>.so</code> files as well as a copy of the 600-odd <code>.py</code> files
36
that make up Twisted. If you do this, you will need to set your PYTHONPATH to
37
something like <code>MyDir/Twisted/build/lib.linux-i686-2.2</code> in order to
38
run code against the Subversion twisted (as opposed to whatever's installed in
39
<code>/usr/lib/python2.2</code> or wherever python usually looks). In
40
addition, you will need to re-run the <code>build</code> command <em>every
41
time</em> you change a <code>.py</code> file. The <code>build/lib.foo</code>
42
directory is a copy of the main tree, and that copy is only updated when you
43
re-run <code>setup.py build</code>. It is easy to forget this and then wonder
44
why your code changes aren't being expressed.</p><p>The second technique is to build the C modules in place, and point your
45
PYTHONPATH at the top of the tree, like <code>MyDir/Twisted</code>. This way
46
you're using the .py files in place too, removing the confusion a forgotten
47
rebuild could cause with the separate build/ directory above. To build the C
48
modules in place, do <code>./setup.py build_ext -i</code>. You only need to
49
re-run this command when you change the C files. Note that
50
<code>setup.py</code> is not Make, it does not always get the dependencies
51
right (<code>.h</code> files in particular), so if you are hacking on the
52
cReactor you may need to manually delete the <code>.o</code> files before
53
doing a rebuild. Also note that doing a <code>setup.py clean</code> will
54
remove the <code>.o</code> files but not the final <code>.so</code> files,
55
they must be deleted by hand.</p><h2>Running tests<a name="auto3"></a></h2><p>To run the full unit-test suite, do:</p><pre class="shell">./bin/trial -v twisted.test</pre><p>To run a single test file (like <code>twisted/test/test_defer.py</code>),
56
do one of:</p><pre class="shell">./bin/trial -v twisted.test.test_defer</pre><p>or</p><pre class="shell">./bin/trial -v twisted/test/test_defer.py</pre><p>To run any tests that are related to a code file, like
57
<code>twisted/protocols/imap4.py</code>, do:</p><pre class="shell">./bin/trial -v --testmodule twisted/protocols/imap4.py</pre><p>This depends upon the <code>.py</code> file having an appropriate
58
<q>test-case-name</q> tag that indicates which test cases provide coverage.
59
See the <a href="test-standard.html">Test Standards</a> document for
60
details about using <q>test-case-name</q>. In this example, the
61
<code>twisted.test.test_imap</code> test will be run.</p><p>Many tests create temporary files in /tmp or ./_trial_temp, but
62
everything in /tmp should be deleted when the test finishes. Sometimes these
63
cleanup calls are commented out by mistake, so if you see a stray
64
/tmp/@12345.1 directory, it is probably from test_dirdbm or test_popsicle.
65
Look for an <code>rmtree</code> that has been commented out and complain to
66
the last developer who touched that file.</p><h2>Admin scripts<a name="auto4"></a></h2><p>The <code>admin/</code> directory holds several administrative tools,
67
some of which are used when turning a Subversion checkout into a full numbered
68
release.</p><h2>Building docs<a name="auto5"></a></h2><p>Twisted documentation (not including the automatically-generated API docs)
69
is in <a href="http://twistedmatrix.com/projects/lore">Lore Format</a>. These
70
<code>.xhtml</code> files are translated into <code>.html</code> files by the
71
<q>bin/lore/lore</q> script, which can check the files for syntax problems
72
(hlint), process multiple files at once, insert the files into a template
73
before processing, and can also translate the files into LaTeX or PostScript
74
instead.</p><p>To generate the full documentation set, run the
75
<code>admin/process-docs</code> shell script. This will create processed
76
HTML, man pages, and 250-page <q>book.pdf</q> file containing all the docs
77
rolled into a single nicely-formatted volume. This script needs several
78
helper tools to handle the images and the LaTeX conversion: debian packages
79
<q>tetex-extra</q>, <q>netpbm</q>, and <q>gs-common</q> should be
80
sufficient. The docs-build process currently takes about 3 minutes on the
81
twistedmatrix.com build machine.</p><p>To build just the HTML form of the howto/ docs, do a subset of the work
82
done in <code>admin/process-docs</code>, such as the following. Note that
83
the index file will be placed in <code>doc/howto/index.html</code>.</p><pre class="shell">
84
./bin/lore/lore -p --config template=doc/howto/template.tpl doc/howto/*.xhtml
85
</pre><p>To run hlint over a single Lore document, such as
86
<code>doc/development/policy/svn-dev.xhtml</code>, do the following. This is
87
useful because the HTML conversion may bail without a useful explanation if
88
it sees mismatched tags.</p><pre class="shell">
89
./bin/lore/lore -n --output lint doc/development/policy/svn-dev.xhtml
90
</pre><p>To convert it to HTML (including markup, interpolation of examples,
91
footnote processing, etc), do the following. The results will be placed in
92
<code>doc/development/policy/svn-dev.html</code>:</p><pre class="shell">
93
./bin/lore/lore -p --config template=doc/howto/template.tpl \
94
doc/development/policy/svn-dev.xhtml
95
</pre><p>Note that hyperlinks to other documents may not be quite right unless you
96
include a <q>-l</q> argument to <code>bin/lore/lore</code>. Links in the
97
.xhtml file are to .xhtml targets: when the .xhtml is turned into .html, the
98
link targets are supposed to be turned into .html also. In addition to this,
99
Lore markup of the form <code class="API"> is supposed to
100
turn into a link to the corresponding API reference page. These links will
101
probably be wrong unless the correct base URL is provided to Lore.</p><h2>Emacs<a name="auto6"></a></h2><p>Check out the TwistedEmacs module, which lives in the same Subversion
102
repository (TODO this is not true), just do <q>cvs checkout TwistedEmacs</q>
103
instead of <q>cvs checkout Twisted</q>). <code>twisted-dev.el</code> has
104
several utility functions which make it easier to grep for methods, run test
105
cases, process Lore documents, etc.</p><h2>Building Debian packages<a name="auto7"></a></h2><p>Running <q>debuild -uc -us</q> from the top of the Subversion tree will
106
(hopefully) result in a collection of .deb packages in the tree's parent
107
directory. This requires other tools to be installed (devscripts for one),
108
and requires that <q>admin/process-docs</q> be run first. The .debs created
109
will have a version number based upon whatever is at the top of
110
<code>debian/changelog</code>, which is generally only updated when an
111
official release is made, so be careful that you don't create
112
confusingly-numbered package files.</p></div><p><a href="../howto/index.html">Index</a></p><span class="version">Version: 2.5.0</span></body></html>
b'\\ No newline at end of file'
added
removed
doc/development/policy/svn-dev.html
