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>There are currently 3 C extension modules in Twisted:
28
twisted.internet.cReactor, twisted.runner.portmap, and twisted.spread.cBanana
29
. These modules are optional, but you'll have to compile them if you want to
30
experience their features, performance improvements, or bugs. There are two
31
approaches.</p><p>The first is to do a regular distutils <code>./setup.py build</code>, which
32
will create a directory under <code>build/</code> to hold both the generated
33
<code>.so</code> files as well as a copy of the 600-odd <code>.py</code> files
34
that make up Twisted. If you do this, you will need to set your PYTHONPATH to
35
something like <code>MyDir/Twisted/build/lib.linux-i686-2.2</code> in order to
36
run code against the Subversion twisted (as opposed to whatever's installed in
37
<code>/usr/lib/python2.2</code> or wherever python usually looks). In
38
addition, you will need to re-run the <code>build</code> command <em>every
39
time</em> you change a <code>.py</code> file. The <code>build/lib.foo</code>
40
directory is a copy of the main tree, and that copy is only updated when you
41
re-run <code>setup.py build</code>. It is easy to forget this and then wonder
42
why your code changes aren't being expressed.</p><p>The second technique is to build the C modules in place, and point your
43
PYTHONPATH at the top of the tree, like <code>MyDir/Twisted</code>. This way
44
you're using the .py files in place too, removing the confusion a forgotten
45
rebuild could cause with the separate build/ directory above. To build the C
46
modules in place, do <code>./setup.py build_ext -i</code>. You only need to
47
re-run this command when you change the C files. Note that
48
<code>setup.py</code> is not Make, it does not always get the dependencies
49
right (<code>.h</code> files in particular), so if you are hacking on the
50
cReactor you may need to manually delete the <code>.o</code> files before
51
doing a rebuild. Also note that doing a <code>setup.py clean</code> will
52
remove the <code>.o</code> files but not the final <code>.so</code> files,
53
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>),
54
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
55
<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
56
<q>test-case-name</q> tag that indicates which test cases provide coverage.
57
See the <a href="test-standard.html">Test Standards</a> document for
58
details about using <q>test-case-name</q>. In this example, the
59
<code>twisted.test.test_imap</code> test will be run.</p><p>Many tests create temporary files in /tmp or ./_trial_temp, but
60
everything in /tmp should be deleted when the test finishes. Sometimes these
61
cleanup calls are commented out by mistake, so if you see a stray
62
/tmp/@12345.1 directory, it is probably from test_dirdbm or test_popsicle.
63
Look for an <code>rmtree</code> that has been commented out and complain to
64
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,
65
some of which are used when turning a Subversion checkout into a full numbered
66
release.</p><h2>Building docs<a name="auto5"></a></h2><p>Twisted documentation (not including the automatically-generated API docs)
67
is in <a href="http://twistedmatrix.com/projects/lore">Lore Format</a>. These
68
<code>.xhtml</code> files are translated into <code>.html</code> files by the
69
<q>bin/lore/lore</q> script, which can check the files for syntax problems
70
(hlint), process multiple files at once, insert the files into a template
71
before processing, and can also translate the files into LaTeX or PostScript
72
instead.</p><p>To generate the full documentation set, run the
73
<code>admin/process-docs</code> shell script. This will create processed
74
HTML, man pages, and 250-page <q>book.pdf</q> file containing all the docs
75
rolled into a single nicely-formatted volume. This script needs several
76
helper tools to handle the images and the LaTeX conversion: debian packages
77
<q>tetex-extra</q>, <q>netpbm</q>, and <q>gs-common</q> should be
78
sufficient. The docs-build process currently takes about 3 minutes on the
79
twistedmatrix.com build machine.</p><p>To build just the HTML form of the howto/ docs, do a subset of the work
80
done in <code>admin/process-docs</code>, such as the following. Note that
81
the index file will be placed in <code>doc/howto/index.html</code>.</p><pre class="shell">
82
./bin/lore/lore -p --config template=doc/howto/template.tpl doc/howto/*.xhtml
83
</pre><p>To run hlint over a single Lore document, such as
84
<code>doc/howto/policy/svn-dev.xhtml</code>, do the following. This is useful
85
because the HTML conversion may bail without a useful explanation if it sees
86
mismatched tags.</p><pre class="shell">./bin/lore/lore -n --output lint doc/howto/policy/svn-dev.xhtml</pre><p>To convert it to HTML (including markup, interpolation of examples,
87
footnote processing, etc), do the following. The results will be placed in
88
<code>doc/howto/policy/svn-dev.html</code>:</p><pre class="shell">
89
./bin/lore/lore -p --config template=doc/howto/template.tpl \
90
doc/howto/policy/svn-dev.xhtml
91
</pre><p>Note that hyperlinks to other documents may not be quite right unless you
92
include a <q>-l</q> argument to <code>bin/lore/lore</code>. Links in the
93
.xhtml file are to .xhtml targets: when the .xhtml is turned into .html, the
94
link targets are supposed to be turned into .html also. In addition to this,
95
Lore markup of the form <code class="API"> is supposed to
96
turn into a link to the corresponding API reference page. These links will
97
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
98
repository (TODO this is not true), just do <q>cvs checkout TwistedEmacs</q>
99
instead of <q>cvs checkout Twisted</q>). <code>twisted-dev.el</code> has
100
several utility functions which make it easier to grep for methods, run test
101
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
102
(hopefully) result in a collection of .deb packages in the tree's parent
103
directory. This requires other tools to be installed (devscripts for one),
104
and requires that <q>admin/process-docs</q> be run first. The .debs created
105
will have a version number based upon whatever is at the top of
106
<code>debian/changelog</code>, which is generally only updated when an
107
official release is made, so be careful that you don't create
108
confusingly-numbered package files.</p></div><p><a href="../../howto/index.html">Index</a></p><span class="version">Version: 2.4.0</span></body></html>
b'\\ No newline at end of file'
added
removed
doc/howto/policy/svn-dev.html
