~vishvananda/nova/network-refactor

<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>Twisted Documentation: Working from Twisted's Subversion repository</title>

</head>

<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">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">Committing and Post-commit Hooks</a></li><li><a href="#auto7">Emacs</a></li><li><a href="#auto8">Building Debian packages</a></li></ol></div>

<span/>

<p>If you're going to be doing development on Twisted itself, or if you want

to take advantage of bleeding-edge features (or bug fixes) that are not yet

available in a numbered release, you'll probably want to check out a tree from

the Twisted Subversion repository. The Trunk is where all current development

takes place.</p>

<p>This document lists some useful tips for working on this cutting

edge.</p>

<h2>Checkout<a name="auto0"/></h2>

<p>Subversion tutorials can be found elsewhere, see in particular <a href="http://subversion.tigris.org/" shape="rect">the Subversion homepage</a>. The relevant

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

</a>, and is as follows:</p>

$ svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk Twisted

</pre>

<h2>Alternate tree names<a name="auto1"/></h2>

<p>By using <code>svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk

otherdir</code>, you can put the workspace tree in a directory other than

<q>Twisted</q>. I do this (with a name like <q>Twisted-Subversion</q>) to

remind myself that this tree comes from Subversion and not from a released

version (like <q>Twisted-1.0.5</q>). This practice can cause a few problems,

because there are a few places in the Twisted tree that need to know where

the tree starts, so they can add it to <code>sys.path</code> without

requiring the user manually set their PYTHONPATH. These functions walk the

current directory up to the root, looking for a directory named

<q>Twisted</q> (sometimes exactly that, sometimes with a

<code>.startswith</code> test). Generally these are test scripts or other

administrative tools which expect to be launched from somewhere inside the

tree (but not necessarily from the top).</p>

<p>If you rename the tree to something other than <code>Twisted</code>, these

tools may wind up trying to use Twisted source files from /usr/lib/python2.5

or elsewhere on the default <code>sys.path</code>. Normally this won't

matter, but it is good to be aware of the issue in case you run into

problems.</p>

<p><code>twisted/test/process_twisted.py</code> is one of these programs.</p>

<h2>Combinator<a name="auto2"/></h2>

<p>In order to simplify the use of Subversion, we typically use

<a href="http://divmod.org/trac/wiki/DivmodCombinator" shape="rect">Divmod Combinator</a>.

You may find it to be useful, too. In particular, because Twisted uses

branches for almost all feature development, if you plan to contribute to

Twisted you will probably find Combinator very useful. For more details,

see the Combinator website, as well as the

UQDS</a> page.</p>

<h2>Compiling C extensions<a name="auto3"/></h2>

<p>

There are currently several C extension modules in Twisted:

twisted.protocols._c_urlarg, twisted.internet.cfsupport,

twisted.internet.iocpreactor._iocp, and twisted.python._epoll. These modules

are optional, but you'll have to compile them if you want to experience their

features, performance improvements, or bugs. There are two approaches.

</p>

<p>The first is to do a regular distutils <code>./setup.py build</code>, which

will create a directory under <code>build/</code> to hold both the generated

<code>.so</code> files as well as a copy of the 600-odd <code>.py</code> files

that make up Twisted. If you do this, you will need to set your PYTHONPATH to

something like <code>MyDir/Twisted/build/lib.linux-i686-2.5</code> in order to

run code against the Subversion twisted (as opposed to whatever's installed in

<code>/usr/lib/python2.5</code> or wherever python usually looks). In

addition, you will need to re-run the <code>build</code> command <em>every

time</em> you change a <code>.py</code> file. The <code>build/lib.foo</code>

directory is a copy of the main tree, and that copy is only updated when you

re-run <code>setup.py build</code>. It is easy to forget this and then wonder

why your code changes aren't being expressed.</p>

<p>The second technique is to build the C modules in place, and point your

PYTHONPATH at the top of the tree, like <code>MyDir/Twisted</code>. This way

you're using the .py files in place too, removing the confusion a forgotten

rebuild could cause with the separate build/ directory above. To build the C

modules in place, do <code>./setup.py build_ext -i</code>. You only need to

re-run this command when you change the C files. Note that

<code>setup.py</code> is not Make, it does not always get the dependencies

right (<code>.h</code> files in particular), so if you are hacking on the

cReactor you may need to manually delete the <code>.o</code> files before

doing a rebuild. Also note that doing a <code>setup.py clean</code> will

100

remove the <code>.o</code> files but not the final <code>.so</code> files,

101

they must be deleted by hand.</p>

102

103

104

<h2>Running tests<a name="auto4"/></h2>

105

106

<p>To run the full unit-test suite, do:</p>

107

108

<pre class="shell" xml:space="preserve">./bin/trial twisted</pre>

109

110

<p>To run a single test file (like <code>twisted/test/test_defer.py</code>),

111

do one of:</p>

112

113

<pre class="shell" xml:space="preserve">./bin/trial twisted.test.test_defer</pre>

114

115

116

117

<pre class="shell" xml:space="preserve">./bin/trial twisted/test/test_defer.py</pre>

118

119

<p>To run any tests that are related to a code file, like

120

<code>twisted/protocols/imap4.py</code>, do:</p>

121

122

<pre class="shell" xml:space="preserve">./bin/trial --testmodule twisted/mail/imap4.py</pre>

123

124

<p>This depends upon the <code>.py</code> file having an appropriate

125

<q>test-case-name</q> tag that indicates which test cases provide coverage.

126

See the <a href="test-standard.html" shape="rect">Test Standards</a> document for

127

details about using <q>test-case-name</q>. In this example, the

128

<code>twisted.mail.test.test_imap</code> test will be run.</p>

129

130

<p>Many tests create temporary files in /tmp or ./_trial_temp, but

131

everything in /tmp should be deleted when the test finishes. Sometimes these

132

cleanup calls are commented out by mistake, so if you see a stray

133

/tmp/@12345.1 directory, it is probably from test_dirdbm or test_popsicle.

134

Look for an <code>rmtree</code> that has been commented out and complain to

135

the last developer who touched that file.</p>

136

137

<h2>Building docs<a name="auto5"/></h2>

138

139

<p>Twisted documentation (not including the automatically-generated API docs)

140

is in <a href="http://twistedmatrix.com/trac/wiki/TwistedLore" shape="rect">Lore Format</a>.

141

These <code>.xhtml</code> files are translated into <code>.html</code> files by

142

the <q>bin/lore/lore</q> script, which can check the files for syntax problems

143

(hlint), process multiple files at once, insert the files into a template

144

before processing, and can also translate the files into LaTeX or PostScript

145

instead.</p>

146

147

<p>To build the HTML form of the howto/ docs, do the following. Note that

148

the index file will be placed in <code>doc/howto/index.html</code>.</p>

149

150

151

./bin/lore/lore -p --config template=doc/howto/template.tpl doc/howto/*.xhtml

152

</pre>

153

154

<p>To run hlint over a single Lore document, such as

155

<code>doc/development/policy/svn-dev.xhtml</code>, do the following. This is

156

useful because the HTML conversion may bail without a useful explanation if

157

it sees mismatched tags.</p>

158

159

160

./bin/lore/lore -n --output lint doc/development/policy/svn-dev.xhtml

161

</pre>

162

163

<p>To convert it to HTML (including markup, interpolation of examples,

164

footnote processing, etc), do the following. The results will be placed in

165

<code>doc/development/policy/svn-dev.html</code>:</p>

166

167

168

./bin/lore/lore -p --config template=doc/howto/template.tpl \

169

doc/development/policy/svn-dev.xhtml

170

</pre>

171

172

<p>Note that hyperlinks to other documents may not be quite right unless you

173

include a <q>-l</q> argument to <code>bin/lore/lore</code>. Links in the

174

.xhtml file are to .xhtml targets: when the .xhtml is turned into .html, the

175

link targets are supposed to be turned into .html also. In addition to this,

176

Lore markup of the form <code class="API"> is supposed to

177

turn into a link to the corresponding API reference page. These links will

178

probably be wrong unless the correct base URL is provided to Lore.</p>

179

180

<h2>Committing and Post-commit Hooks<a name="auto6"/></h2>

181

182

<p>Twisted uses a customized

183

184

trac-post-commit-hook</a> to enable ticket updates based on svn commit

185

logs. When making a branch for a ticket, the branch name should end

186

in <code>-<ticket number></code>, for

187

example <code>my-branch-9999</code>. This will add a ticket comment containing a

188

changeset link and branch name. To make your commit message show up as a comment

189

on a Trac ticket, add a <code>refs #<ticket number></code> line at the

190

bottom of your commit message. To automatically close a ticket on Trac

191

as <code>Fixed</code> and add a comment with the closing commit message, add

192

a <code>Fixes: #<ticket number></code> line to your commit message. In

193

general, a commit message closing a ticket looks like this:</p>

194

195

196

Merge my-branch-9999: A single-line summary.

197

198

Author: jesstess

199

Reviewers: exarkun, glyph

200

Fixes: #9999

201

202

My longer description of the changes made.

203

</pre>

204

205

<p>The <a href="coding-standard.html#commits" shape="rect">Twisted Coding Standard</a>

206

elaborates on commit messages and source control.</p>

207

208

<h2>Emacs<a name="auto7"/></h2>

209

210

<p>A minor mode for development with Twisted using Emacs is available. See

211

<code>emacs/twisted-dev.el</code> for several utility functions which make

212

it easier to grep for methods, run test cases, etc.</p>

213

214

<h2>Building Debian packages<a name="auto8"/></h2>

215

216

<p>Our support for building Debian packages has fallen into disrepair. We

217

would very much like to restore this functionality, but until we do so, if

218

you are interested in this, you are on your own. See

219

<a href="http://stdeb.python-hosting.com/" shape="rect">stdeb</a> for one possible approach

220

to this.</p>

221

222

</div>

223

224

<p><a href="../../howto/index.html">Index</a></p>

225

<span class="version">Version: 10.0.0</span>

226

</body>

227

</html>

b'\\ No newline at end of file'

Older »