'''
使用Twisted的SVN仓库（Working from Twisted's Subversion repository）
'''

<<TableOfContents>>


  如果你想自己开发Twisted，或者你想利用Twisted最新版本（通常是开发版本，而不是release版本）中的一些特性，又或是你想为Twisted修复bug，你可能都需要从Twisted的代码树中check out出一份代码－－一个子版本。这个子版本就是我们要使用的开发代码。（Twisted中使用SVN对代码进行管理）

  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.

  本文列出了一些有用的提示。

  This document lists some useful tips for working on this cutting edge.

= 从代码仓库中check out（Checkout） =

  你可以在其他的地方找到SVN的使用教程，例如：SVN的主页上（http://subversion.tigris.org/ ）。你可以在这里（http://twistedmatrix.com/developers/cvs ）找到你要check out的Twisted的代码树的服务器，可以使用下面的命令来check out代码：

  Subversion tutorials can be found elsewhere, see in particular the Subversion homepage. The relevant data you need to check out a copy of the Twisted tree is available on the pserver page, and is as follows:
{{{
  $ svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk Twisted
}}}

= 替换代码树的名称（Alternate tree names） =

  使用cvs checkout -d foo Twisted这个命令可以修改Twisted代码树的工作目录。我就一直这么干－－通常给新的目录命名为Twisted-Subversion来提醒我自己“这份代码是一个开发子版本，不是release版本的代码”。这么作可能会导致一些小问题，因为Twisted代码树中有一些地方需要知道当前的代码树是从那个目录开始的，这样，不需要用户手动设定PYTHONPATH就可以在sys.path里添加当前的路径。这些函数会从当前的目录一直向上寻找主干（找到根目录为止），力图找到一个名为Twisted的目录（通常用startwith方法来测试）。这就是一些常见的测试脚本和管理工具实现代码可以在不同位置正确运行的方法（如果代码位于代码树的最上层，就无需这种技巧了）。

  By using cvs checkout -d foo Twisted, you can put the workspace tree in a directory other than Twisted. I do this (with a name like Twisted-Subversion) to remind myself that this tree comes from Subversion and not from a released version (like Twisted-1.0.5). 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 sys.path without requiring the user manually set their PYTHONPATH. These functions walk the current directory up to the root, looking for a directory named Twisted (sometimes exactly that, sometimes with a .startswith 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).

  如果你重命名了代码树的根节点（不是Twisted了），这些脚本或是工具可能会使用sys.path中指定的一些目录下面的Twisted的源码，例如/usr/lib/python2.2。通常来说，这不会又什么问题，但是一旦出了问题，你应该知道这回事儿。

  If you rename the tree to something other than Twisted, these tools may wind up trying to use Twisted source files from /usr/lib/python2.2 or elsewhere on the default sys.path. Normally this won't matter, but it is good to be aware of the issue in case you run into problems.

  twisted/test/process_twisted.py就是这样一个程序。

  twisted/test/process_twisted.py is one of these programs.

= 编译C扩展模块（Compiling C extensions） =

  现在的Twisted中有3个C的扩展模块：twisted.internet.cReactor、twisted.runner.portmap和twisted.spread.cBanana。这些模块是可选的，如果想要使用这些模块，你需要自己去编译他们。下面列出了两种方法：

  There are currently 3 C extension modules in Twisted: twisted.internet.cReactor, twisted.runner.portmap, and twisted.spread.cBanana . 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.

  第一个方法是执行distutils ./setup.py build命令，该命令会在build目录下建立一个新目录来保存编译出来的.so文件和组成Twisted的600多个.py文件。如果想正常执行上面的命令，必须设定PYTHONPATH环境变量（例如：MyDir/Twisted/build/lib.linux-i686-2.2），用来防止其他的twisted版本影响编译程序。此外，每当你修改了一个.py文件，你就得重新运行上面的编译命令。build/lib.foo目录中保存着主代码树的副本，只有当你重新运行setup.py build命令时才会更新。经常会发生忘记重新编译代码的事儿，这时候你可能正在奇怪为什么你对代码的修改完全没有效果，-_-!。

  The first is to do a regular distutils ./setup.py build, which will create a directory under build/ to hold both the generated .so files as well as a copy of the 600-odd .py files that make up Twisted. If you do this, you will need to set your PYTHONPATH to something like MyDir/Twisted/build/lib.linux-i686-2.2 in order to run code against the Subversion twisted (as opposed to whatever's installed in /usr/lib/python2.2 or wherever python usually looks). In addition, you will need to re-run the build command every time you change a .py file. The build/lib.foo directory is a copy of the main tree, and that copy is only updated when you re-run setup.py build. It is easy to forget this and then wonder why your code changes aren't being expressed.

  第二种方法是C的扩展模块in place编译，然后将PYTHONPATH指向代码树的顶端，例如：MyDir/Twisted。这种in place编译的方法可以消除上述使用单独build目录而导致忘记重编译所造成的混淆。为了能够实现C模块的in place编译，需要执行./setup.py build_ext -i这个命令。这样，只有当你修改了c文件的时候，才需要重新执行上面的命令。注意：setup.py不是make程序，它无法保证一定能够正确的获取所的文件依赖关系（尤其是.h文件），因此，如果你正在修改cReactor这个模块，你最好在重编译之前手动删除所有的.o文件。类似的，执行setup.py clean命令只会删除.o文件，而不会删除上次编译最终产生的.so文件，这些.so文件也得手动删除。

  The second technique is to build the C modules in place, and point your PYTHONPATH at the top of the tree, like MyDir/Twisted. 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 ./setup.py build_ext -i. You only need to re-run this command when you change the C files. Note that setup.py is not Make, it does not always get the dependencies right (.h files in particular), so if you are hacking on the cReactor you may need to manually delete the .o files before doing a rebuild. Also note that doing a setup.py clean will remove the .o files but not the final .so files, they must be deleted by hand.

= 运行测试（Running tests） =

  为了执行整个单元测试集，需要执行：

  To run the full unit-test suite, do:

  ./bin/trial -v twisted.test

  为了执行一个单独的测试文件（例如：twisted/test/test_defer.py），可以这样作：

  To run a single test file (like twisted/test/test_defer.py), do one of:

  ./bin/trial -v twisted.test.test_defer

  或是这样：

  or

  ./bin/trial -v twisted/test/test_defer.py

  为了执行所有与某个特定代码文件有关的所有测试（例如：twisted/protocols/imap4.py），可以这样作：

  To run any tests that are related to a code file, like twisted/protocols/imap4.py, do:

  ./bin/trial -v --testmodule twisted/protocols/imap4.py

  上诉测试的正确执行要依赖于每个.py文件都包含正确的test-case-name标签，这个标签指名那些测试可以覆盖这个文件。对于使用test-case-name标签的具体内容可以参考测试标准部分的文档。在这个例子中，将会执行twisted.test.test_imap这个测试程序。

  This depends upon the .py file having an appropriate test-case-name tag that indicates which test cases provide coverage. See the Test Standards document for details about using test-case-name. In this example, the twisted.test.test_imap test will be run.

  许多测试程序都会在tmp或是_trial_temp目录下建立一些临时的文件，当测试结束的时候，tmp目录下的所有文件都应该删除。有些时候，这些清除临时文件的代码可能会被错误的注释掉，因此如果你发现一个类似于/tmp/@12345.1这样的一个目录，它大概就是test_dirdbm或是test_popsicle测试程序忘记删除的临时文件。打开对应的测试程序，找到被错误注释掉的代码，然后你就可以向最后一个修改代码的开发者喋喋不休的抱怨了。

  Many tests create temporary files in /tmp or ./_trial_temp, but everything in /tmp should be deleted when the test finishes. Sometimes these cleanup calls are commented out by mistake, so if you see a stray /tmp/@12345.1 directory, it is probably from test_dirdbm or test_popsicle. Look for an rmtree that has been commented out and complain to the last developer who touched that file.

= 管理性脚本（Admin scripts） =

  admin目录下有一些管理性的工具，其中一些是在“将一个checkout出来的开发子版本转化为一个release版本”时使用的。

  The admin/ directory holds several administrative tools, some of which are used when turning a Subversion checkout into a full numbered release.

= 编译文档（Building docs） =

  Twisted的文档（不包括那些自动产生的API文档）使用Lore格式。这些.html文件通过bin/lore脚本转换为xhtml文件－－这些脚本能够检查文件中的语法错误（使用hlint），一次处理多个文件，在处理前将文件插入一个模板中；它们也能将.html文件转换为LaTex或是PostScript文件。

  Twisted documentation (not including the automatically-generated API docs) is in Lore Format. These .html files are translated into .xhtml files by the bin/lore script, which can check the files for syntax problems (hlint), process multiple files at once, insert the files into a template before processing, and can also translate the files into LaTeX or PostScript instead.

  为了生成整个文档集，需要运行admin/process-docs这个shell脚本。这样就可以生成处理过的HTML文档，man page手册，还有一个250页的book.pdf文件（这里面包含了所有的文档，格式已经排好）。这个脚本需要一些辅助工具来处理图像和LaTex文档的转换：debian包里的tetex-extra，netpbm和gs-common应该就足够了。在twistedmatrix.com专用编译机器上执行当前的文档编译过程大概需要3分钟。

  To generate the full documentation set, run the admin/process-docs shell script. This will create processed HTML, man pages, and 250-page book.pdf file containing all the docs rolled into a single nicely-formatted volume. This script needs several helper tools to handle the images and the LaTeX conversion: debian packages tetex-extra, netpbm, and gs-common should be sufficient. The docs-build process currently takes about 3 minutes on the twistedmatrix.com build machine.

  为了只编译HTML格式的howto/文档，可以只执行admin/process-doc中的一个子集，例如：（注意生成的index文件将放在doc/howto/index.xhtml中）

  To build just the HTML form of the howto/ docs, do a subset of the work done in admin/process-docs, such as the following. Note that the index file will be placed in doc/howto/index.xhtml.

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

  为了在一个单个的Lore文档上运行hlint，例如doc/howto/cvs-dev.html，可以按下面的方法去做。这种能力是很重要的，因为HTML文档的转换可能会由于一个无法匹配的tag标签而导致hlint失败。

  To run hlint over a single Lore document, such as doc/howto/cvs-dev.html, do the following. This is useful because the HTML conversion may bail without a useful explanation if it sees mismatched tags.

  ./bin/lore -n --output lint doc/howto/cvs-dev.html

  为了将Lore文档转换为HTML格式（包括所有的markup，对例子的修改，脚注的处理等等），可以按下面的方法做。转换的结果保存在doc/howto/cvs-dev.xhtml中：

  To convert it to HTML (including markup, interpolation of examples, footnote processing, etc), do the following. The results will be placed in doc/howto/cvs-dev.xhtml:

  ./bin/lore -p --config template=doc/howto/template.tpl doc/howto/cvs-dev.html

  注意：指向其他文档的超连接可能会出错，除非你为bin/lore命令加上-l参数。当.html文档转换为.xhtml文档的时候，原来.html文档中指向.html文档的链接也会自动指向新的.xhtml文档。此外，Lore中型如<code class="API">的标签也可以转换为指向对应的API参考中的链接。除非为Lore提供正确的URL基地址，否则自动产生的链接地址可能会出错。

  Note that hyperlinks to other documents may not be quite right unless you include a -l argument to bin/lore. Links in the .html file are to .html targets: when the .html is turned into .xhtml, the link targets are supposed to be turned into .xhtml also. In addition to this, Lore markup of the form <code class="API"> is supposed to turn into a link to the corresponding API reference page. These links will probably be wrong unless the correct base URL is provided to Lore.

= Emacs编辑器（Emacs） =

  可以从SVN的代码仓库中check out到TwistedEmacs模块（和你check out上面提到的Twisted的一个子版本一样，区别只在于cvs checkout TwistedEmacs代替cvs checkout Twisted）。twisted-dev.el有许多有用的功能，例如它可以方便的grep某个函数，运行测试用例或是处理Lore文档等。

  Check out the TwistedEmacs module (which lives in the same Subversion repository, just do cvs checkout TwistedEmacs instead of cvs checkout Twisted). twisted-dev.el has several utility functions which make it easier to grep for methods, run test cases, process Lore documents, etc.
{{{这里面怎么会有 cvs checkout，是不是写文档的人编错了？
-- xyb }}}

= 编译Debian包（Building Debian packages） =

  从子版本代码树的顶层目录运行debuild -uc -us命令会在代码树的父目录中生成一组.deb的包。要执行上面的命令，必须先安装其他的工具（例如：devscripts），还要先运行admin/process-docs。这些.deb的包会有一个版本号，这个版本号基于debian/change-log文件中开始部分的内容，通常来说这部分内容只会在新发行官方release版本时才会更新，因此请小心不要生成一个带有错误版本号的.deb包文件。

  Running debuild -uc -us from the top of the Subversion tree will (hopefully) result in a collection of .deb packages in the tree's parent directory. This requires other tools to be installed (devscripts for one), and requires that admin/process-docs be run first. The .debs created will have a version number based upon whatever is at the top of debian/changelog, which is generally only updated when an official release is made, so be careful that you don't create confusingly-numbered package files.


Version: 1.3.0

<< 返回（PyTwisted/WorkingOnTheTwistedCodeBase）


by bigbaboon

2004-09-12