doc/core/development/policy/svn-dev.html

   1 <?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">
   2   <head>
   3 <title>Twisted Documentation: Working from Twisted's Subversion repository</title>
   4 <link href="../../howto/stylesheet.css" rel="stylesheet" type="text/css"/>
   5   </head>
   6
   7   <body bgcolor="white">
   8     <h1 class="title">Working from Twisted's Subversion repository</h1>
   9     <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>
  10     <div class="content">
  11 <span/>
  12
  13 <p>If you're going to be doing development on Twisted itself, or if you want
  14 to take advantage of bleeding-edge features (or bug fixes) that are not yet
  15 available in a numbered release, you'll probably want to check out a tree from
  16 the Twisted Subversion repository. The Trunk is where all current development
  17 takes place.</p>
  18
  19 <p>This document lists some useful tips for working on this cutting
  20 edge.</p>
  21
  22 <h2>Checkout<a name="auto0"/></h2>
  23
  24 <p>Subversion tutorials can be found elsewhere, see in particular
  25 <a href="http://subversion.apache.org/" shape="rect">the Subversion homepage</a>. The
  26 relevant data you need to check out a copy of the Twisted tree is available on
  27 the <a href="http://twistedmatrix.com/trac/wiki/TwistedDevelopment" shape="rect">development
  28 page</a>, and is as follows:</p>
  29
  30 <pre class="shell" xml:space="preserve">
  31 $ svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk Twisted
  32 </pre>
  33
  34 <h2>Alternate tree names<a name="auto1"/></h2>
  35
  36 <p>By using <code>svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk
  37 otherdir</code>, you can put the workspace tree in a directory other than
  38 <q>Twisted</q>. I do this (with a name like <q>Twisted-Subversion</q>) to
  39 remind myself that this tree comes from Subversion and not from a released
  40 version (like <q>Twisted-1.0.5</q>). This practice can cause a few problems,
  41 because there are a few places in the Twisted tree that need to know where
  42 the tree starts, so they can add it to <code>sys.path</code> without
  43 requiring the user manually set their PYTHONPATH. These functions walk the
  44 current directory up to the root, looking for a directory named
  45 <q>Twisted</q> (sometimes exactly that, sometimes with a
  46 <code>.startswith</code> test). Generally these are test scripts or other
  47 administrative tools which expect to be launched from somewhere inside the
  48 tree (but not necessarily from the top).</p>
  49
  50 <p>If you rename the tree to something other than <code>Twisted</code>, these
  51 tools may wind up trying to use Twisted source files from /usr/lib/python2.5
  52 or elsewhere on the default <code>sys.path</code>.  Normally this won't
  53 matter, but it is good to be aware of the issue in case you run into
  54 problems.</p>
  55
  56 <p><code>twisted/test/process_twisted.py</code> is one of these programs.</p>
  57
  58 <h2>Combinator<a name="auto2"/></h2>
  59
  60 <p>In order to simplify the use of Subversion, we typically use
  61 <a href="http://twistedmatrix.com/trac/wiki/Combinator" shape="rect">Divmod Combinator</a>.
  62 You may find it to be useful, too.  In particular, because Twisted uses
  63 branches for almost all feature development, if you plan to contribute to
  64 Twisted you will probably find Combinator very useful.  For more details,
  65 see the Combinator website, as well as the
  66 <a href="http://twistedmatrix.com/trac/wiki/UltimateQualityDevelopmentSystem" shape="rect">
  67 UQDS</a> page.</p>
  68
  69 <h2>Compiling C extensions<a name="auto3"/></h2>
  70
  71 <p>
  72 There are currently several C extension modules in Twisted:
  73 <code class="python">twisted.internet.cfsupport</code>,
  74 <code class="python">twisted.internet.iocpreactor._iocp</code>,
  75 and <code class="python">twisted.python._epoll</code>.  These modules
  76 are optional, but you'll have to compile them if you want to experience their
  77 features, performance improvements, or bugs. There are two approaches.
  78 </p>
  79
  80 <p>The first is to do a regular distutils <code>./setup.py build</code>, which
  81 will create a directory under <code>build/</code> to hold both the generated
  82 <code>.so</code> files as well as a copy of the 600-odd <code>.py</code> files
  83 that make up Twisted. If you do this, you will need to set your PYTHONPATH to
  84 something like <code>MyDir/Twisted/build/lib.linux-i686-2.5</code> in order to
  85 run code against the Subversion twisted (as opposed to whatever's installed in
  86 <code>/usr/lib/python2.5</code> or wherever python usually looks). In
  87 addition, you will need to re-run the <code>build</code> command <em>every
  88 time</em> you change a <code>.py</code> file. The <code>build/lib.foo</code>
  89 directory is a copy of the main tree, and that copy is only updated when you
  90 re-run <code>setup.py build</code>. It is easy to forget this and then wonder
  91 why your code changes aren't being expressed.</p>
  92
  93 <p>The second technique is to build the C modules in place, and point your
  94 PYTHONPATH at the top of the tree, like <code>MyDir/Twisted</code>. This way
  95 you're using the .py files in place too, removing the confusion a forgotten
  96 rebuild could cause with the separate build/ directory above. To build the C
  97 modules in place, do <code>./setup.py build_ext -i</code>. You only need to
  98 re-run this command when you change the C files. Note that
  99 <code>setup.py</code> is not Make, it does not always get the dependencies
 100 right (<code>.h</code> files in particular), so if you are hacking on the
 101 cReactor you may need to manually delete the <code>.o</code> files before
 102 doing a rebuild. Also note that doing a <code>setup.py clean</code> will
 103 remove the <code>.o</code> files but not the final <code>.so</code> files,
 104 they must be deleted by hand.</p>
 105
 106
 107 <h2>Running tests<a name="auto4"/></h2>
 108
 109 <p>To run the full unit-test suite, do:</p>
 110
 111 <pre class="shell" xml:space="preserve">./bin/trial twisted</pre>
 112
 113 <p>To run a single test file (like <code>twisted/test/test_defer.py</code>),
 114 do one of:</p>
 115
 116 <pre class="shell" xml:space="preserve">./bin/trial twisted.test.test_defer</pre>
 117
 118 <p>or</p>
 119
 120 <pre class="shell" xml:space="preserve">./bin/trial twisted/test/test_defer.py</pre>
 121
 122 <p>To run any tests that are related to a code file, like
 123 <code>twisted/protocols/imap4.py</code>, do:</p>
 124
 125 <pre class="shell" xml:space="preserve">./bin/trial --testmodule twisted/mail/imap4.py</pre>
 126
 127 <p>This depends upon the <code>.py</code> file having an appropriate
 128 <q>test-case-name</q> tag that indicates which test cases provide coverage.
 129 See the <a href="test-standard.html" shape="rect">Test Standards</a> document for
 130 details about using <q>test-case-name</q>. In this example, the
 131 <code>twisted.mail.test.test_imap</code> test will be run.</p>
 132
 133 <p>Many tests create temporary files in /tmp or ./_trial_temp, but
 134 everything in /tmp should be deleted when the test finishes. Sometimes these
 135 cleanup calls are commented out by mistake, so if you see a stray
 136 <code>/tmp/@12345.1</code> directory, it is probably from <code>test_dirdbm</code> or <code>test_popsicle</code>.
 137 Look for an <code>rmtree</code> that has been commented out and complain to
 138 the last developer who touched that file.</p>
 139
 140 <h2>Building docs<a name="auto5"/></h2>
 141
 142 <p>Twisted documentation (not including the automatically-generated API docs)
 143 is in <a href="http://twistedmatrix.com/trac/wiki/TwistedLore" shape="rect">Lore Format</a>.
 144 These <code>.xhtml</code> files are translated into <code>.html</code> files by
 145 the <q>bin/lore/lore</q> script, which can check the files for syntax problems
 146 (hlint), process multiple files at once, insert the files into a template
 147 before processing, and can also translate the files into LaTeX or PostScript
 148 instead.</p>
 149
 150 <p>To build the HTML form of the howto/ docs, do the following. Note that
 151 the index file will be placed in <code>doc/core/howto/index.html</code>.</p>
 152
 153 <pre class="shell" xml:space="preserve">
 154 ./bin/lore/lore -p --config template=doc/core/howto/template.tpl doc/core/howto/*.xhtml
 155 </pre>
 156
 157 <p>To run hlint over a single Lore document, such as
 158 <code>doc/development/policy/svn-dev.xhtml</code>, do the following. This is
 159 useful because the HTML conversion may bail without a useful explanation if
 160 it sees mismatched tags.</p>
 161
 162 <pre class="shell" xml:space="preserve">
 163 ./bin/lore/lore -n --output lint doc/development/policy/svn-dev.xhtml
 164 </pre>
 165
 166 <p>To convert it to HTML (including markup, interpolation of examples,
 167 footnote processing, etc), do the following. The results will be placed in
 168 <code>doc/development/policy/svn-dev.html</code>:</p>
 169
 170 <pre class="shell" xml:space="preserve">
 171 ./bin/lore/lore -p --config template=doc/core/howto/template.tpl \
 172    doc/development/policy/svn-dev.xhtml
 173 </pre>
 174
 175 <p>Note that hyperlinks to other documents may not be quite right unless you
 176 include a <q>-l</q> argument to <code>bin/lore/lore</code>. Links in the
 177 .xhtml file are to .xhtml targets: when the .xhtml is turned into .html, the
 178 link targets are supposed to be turned into .html also. In addition to this,
 179 Lore markup of the form <code>&lt;code class=&quot;API&quot;&gt;</code> is supposed to
 180 turn into a link to the corresponding API reference page. These links will
 181 probably be wrong unless the correct base URL is provided to Lore.</p>
 182
 183 <h2>Committing and Post-commit Hooks<a name="auto6"/></h2>
 184
 185 <p>Twisted uses a customized
 186 <a href="http://bazaar.launchpad.net/~exarkun/twisted-trac-integration/trunk/annotate/head%3A/trac-hooks/trac-post-commit-hook" shape="rect">
 187 trac-post-commit-hook</a> to enable ticket updates based on svn commit
 188 logs. When making a branch for a ticket, the branch name should end
 189 in <code>-&lt;ticket number&gt;</code>, for
 190 example <code>my-branch-9999</code>. This will add a ticket comment containing a
 191 changeset link and branch name. To make your commit message show up as a comment
 192 on a Trac ticket, add a <code>refs #&lt;ticket number&gt;</code> line at the
 193 bottom of your commit message. To automatically close a ticket on Trac
 194 as <code>Fixed</code> and add a comment with the closing commit message, add
 195 a <code>Fixes: #&lt;ticket number&gt;</code> line to your commit message. In
 196 general, a commit message closing a ticket looks like this:</p>
 197
 198 <pre xml:space="preserve">
 199 Merge my-branch-9999: A single-line summary.
 200
 201 Author: jesstess
 202 Reviewers: exarkun, glyph
 203 Fixes: #9999
 204
 205 My longer description of the changes made.
 206 </pre>
 207
 208 <p>The <a href="coding-standard.html" shape="rect">Twisted Coding Standard</a>
 209 elaborates on commit messages and source control.</p>
 210
 211 <h2>Emacs<a name="auto7"/></h2>
 212
 213 <p>A minor mode for development with Twisted using Emacs is available.  See
 214 <code>twisted-dev.el</code>, provided by <a href="http://launchpad.net/twisted-emacs" shape="rect">twisted-emacs</a>,
 215 for several utility functions which make it easier to grep for methods, run test cases, etc.</p>
 216
 217 <h2>Building Debian packages<a name="auto8"/></h2>
 218
 219 <p>Our support for building Debian packages has fallen into disrepair.  We
 220 would very much like to restore this functionality, but until we do so, if
 221 you are interested in this, you are on your own.  See
 222 <a href="http://github.com/astraw/stdeb" shape="rect">stdeb</a> for one possible approach to
 223 this.</p>
 224
 225 </div>
 226
 227     <p><a href="../../howto/index.html">Index</a></p>
 228     <span class="version">Version: 12.1.0</span>
 229   </body>
 230 </html>