MCCCS Towhee (Developer Manual)



    This section covers the basic information that is required in order to become a Towhee developer and also some suggested practices and overall guidelines for working with the Towhee development team.

Becoming a Developer
    Towhee is an open-source project so anyone is welcome to download the package, including all of the source code, and start modifying it for their own purposes. Here we are concerned with people who want to develop Towhee in conjunction with the current team of developers. One way to help is to report any problems you discover in the code to the developers via the mailing list. This is also a great way to communicate minor code changes, especially those that fix bugs, to the developers for them to include in the next release.

    Those wishing to make substantial changes to the code, such as implementing new algorithms, are better served by joining the Towhee developer team in order to gain full access to the code repositories at SourceForge. If you are interested then you need to sign up for a free username at SourceForge (, and send an email indicating your interest to Marcus G. Martin.

Subversion Access
    In order to get started using Subersion (svn) you will need to checkout the current version of the code into a workspace on one of your machines. Directions for checking out the code are found by following the "Code" and "SVN" links from the Towhee SourceForge site. Make sure to follow the developer access directions, and not the anonymous access directions. Then you can checkout the code using
      svn co towhee
    This command creates a directory named towhee that contains all of the Towhee files and directories.

Test Suite
    The Towhee example manual also doubles as the test suite for the code. Before you commit changes to the repository you should build the towhee executable, using the --enable-safe-compare configure flag and run it through the test suite in order to make sure you have not caused any unintentional damage to the rest of the code while implementing your new features. This is done using the ./run_serial_test command in the Examples directory. This sequentially works through the examples producing files named answer_new in each of the directories. At the conclusion of the script it creates a file named test_report that contains the Unix diff of all of the answer_new files with their respective answer_current files. Once you are satisfied that the differences between the files are an obvious and intended result of your changes then you can copy all of the answer_new files to answer_current files using the ./reset_new_to_current script in the Examples directory.

    If you are working on parallel programming features of Towhee then you will also want to run the ./run_para_test script in the Examples directory. This script then called the ./execute_parallel script that is in the Parallel_Test directory. The ./execute_parallel script is no longer included in the distribution because it is a machine specific script that executes a parallel job in that directory. If you are on a machine that allows direct submission of parallel jobs then your ./execute_parallel script would look something like
      mpirun -np 2 /towheebase/Source/towhee
    This will execute a job that utilizes the towhee_parallel file in the Parallel_Test directory to run a jobfarm that executes the test suite jobs to produce output files named par_answer_current. Running the ./run_para_diff script in the Examples directory produces the para_test_report file that contains the diffs from all of the par_answer_current and their respective answer_current files. These files should be identical so the para_test_report file should only contain the directory names of the test suite.


Return to the main towhee web page

Send comments to: Marcus G. Martin

Last updated: February 02, 2011