MCCCS Towhee (Developer Manual)

Overview 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 towhee-bugs@lists.sourceforge.net 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 CVS repositories at SourceForge. If you are interested then you need to sign up for a free username at SourceForge (http://sourceforge.net/), and send an email indicating your interest to Marcus G. Martin. CVS Access In order to get started using CVS 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 CVS link from the Towhee SourceForge site. Make sure to follow the developer access directions, and not the anonymous access directions. You first need to set the CVS_RSH environment variable to ssh. Then you can checkout the code using cvs -z3 -d:ext:developername@towhee.cvs.sourceforge.net:/cvsroot/towhee co -P towhee where developername is replaced by your SourceForge user name. This command creates a directory named towhee that contains all of the Towhee files and directories. For a complete discussion of CVS see a resource like the Open Source Development with CVS. A few commands are especially useful and are mentioned here. cvs update checks your workbox copy of the code against the repository and attempts to reconcile the two copies by bringing your workbox version up to date. Pay special attention to any "conflict" messages during the update as these indicate a problem bringing the workbox up to date and a note indicating the conflict is placed into all files that contained a conflict. cvs commit is used to check your changes back into the repository. During this process you are given an opportunity to make some comments about your changes and it is helpful if you can summarize your changes in a couple of sentences. 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: December 14, 2006