= TCUP : TCP over UDP Repy Library =
----
This Library implements the TCP protocol on top of UDP sockets exposed in Repy.  Hence, TC-p-U-d-P or TCUP (pronounced teacup). For where to get the code, and 
instructions on how to use TCUP see below. For recent activity, see the [TopSecret project wiki]. 
----
[[TOC]]

[[Image(tcup.jpg)]]
----

== Getting the Code ==
The latest TCUP release is '''0.0.1'''  released on February 19, 2009.

At the online [https://seattle.cs.washington.edu/wiki/TopSecretReadme Readme] page, you can click and download:
 * [https://seattle.cs.washington.edu/raw-attachment/wiki/TopSecretReadme/tcp.repy tcp.repy] - single file version
 * [https://seattle.cs.washington.edu/raw-attachment/wiki/TopSecretReadme/tcp.tgz tcp.tgz] - our sub folder in the Seattle project svn

You can also checkout the latest code anonymously directly from SVN:
{{{
#!sh
svn co http://seattle.cs.washington.edu/svn/seattle/trunk/ # get whole Seattle
cd trunk/repy/apps/tcp/ # goto root of library
}}}

== Manifest ==
The code has the following layout:
 * *.repy - Classes.
 * examples - Holds example Repy applications.
 * Makefile - Runs test suite and generates distributation versions of the library.
 * tests/ - The files here are test file-folders, classes, resources, and scripts.
  * *.txt - Input files to test sending large amounts of data.
  * * build.sh - Pre-processes test files in folder through Repypp.
  * restrictions.default - All tests run through Repy with this.
  * run_tests.py - Seattle's test runner slightly modified.
  * functionals/ - testing how functions of a single class interact
  * integrations/ - testing how classes interact
  * units/ - testing how each function of a class works in isolation

== Using the Library ==
If you want to use the [https://seattle.cs.washington.edu/raw-attachment/wiki/TopSecretReadme/tcp.repy single file]:
{{{
#!sh
# 1. Get the single file version, '''tcp.repy'''
wget https://seattle.cs.washington.edu/raw-attachment/wiki/TopSecretReadme/tcp.repy
# 2. Add ''include tcp.repy'' to the top of your Repy file
emacs file.repy
# 3. Pre-process your Repy file:
python repypp.py file.repy file.out
# 4. Excute your script locally with Repy:
python repy.py restictions.file file.out
}}}

If you downloaded the [https://seattle.cs.washington.edu/raw-attachment/wiki/TopSecretReadme/tcp.tgz tarball] or
checked out the SVN, here's some basic steps to follow if your starting from a clean directory:
{{{
#!sh
# 1. Create a single file of the library to include in an application:
make image # link the library into a single file
# 2. Move the image to the folder with a Repy file that uses the library:
cp image/tcp.repy $APPLICATION_DIR
# 3. Add the line "include tcp.repy" to your Repy file.
cd $APPLICATION_DIR && emacs file.repy
# 4. Pre-process your Repy file:
python repypp.py file.repy file.out
# 5. Excute your script locally with Repy:
python repy.py restictions.file file.out
}}}
See the [StudentsPage Students page] for more details on Repypp and links to help pages for Repy.
See the [RepyTutorial Repy Tutorial] for an introduction to Repy.

== Example ==
{{{
#!python
  # A hello world application
  include tcp.repy

  if callfunc == 'initialize':
    conn = Connection()
    conn.bind(getmyip(), 12345)

    conn.connect(getmyip(), 12345)
    conn.send("hello world!")
    message = conn.recv(4096)
    conn.disconnect()

    print message
    exitall()
}}}

You can run this example by typing:
{{{
#!sh
make example
}}}

== Testing == 
To run the test suite do: 
{{{
#!sh
make
}}}
See the Makefile for other options.
     
=== Unit test files ===
Unit test files may be in the format '''z_test_<classname>_<function_name>.repy'''.  
These unit test files just test a single class function.  For example, a unit test 
file of Connection.bind would be in the file '''z_test_connection_bind.repy'''.  Each 
such unit test file contains test functions. Each test function tests a condition 
(ex. if branch) of a class function.

=== Functional test files ===
A functional test file may exist for a class.  A functional test file tests how the 
different functions in a single class interact.  Name a functional test file like 
'''z_test_<classname>.repy'''.  For example, a functional test file of Connection 
would be in the file '''z_test_connection.repy'''.  A functional test file contains 
test functions.  Each test function calls multiple related class functions and makes 
sure they interact correctly.

=== Integration test files ===
Integration test files include all of the library. Integration tests test interaction 
between multiple classes.  The have names like '''z_test_<description>.repy'''.  Each
integration file uses only public interface methods.  The file is an example application
using the library.

== Distributing == 
To pack up the current library from source into a tarball do: 
{{{
#!sh
make dist
}}}

