1. How to get more information about Tra

Here's an edited excerpt from the original announcement on the
Tra-Announce mailing list (tra-announce@eecs.harvard.edu):

There are two Tra-related mailing lists, the announcement list,
tra-announce@eecs.harvard.edu, which is very low volume and moderated.
Archives of this list may be found on the web at:

	https://list.eecs.harvard.edu/mailman/listinfo/tra-announce

There is also a Tra users mailing list which is intended to be
useful for generic chatter about using Tra. If you have questions,
please consider signing up for the list and asking them there, where
questions and answers will be preserved for posterity:

	https://list.eecs.harvard.edu/mailman/listinfo/tra

Instructions for using Tra are at 

	http://pdos.lcs.mit.edu/~rsc/tra/

and

	http://www.eecs.harvard.edu/~wkj/Software/tra/

Tra is currently distributed only in source form, via anonymous CVS
to :pserver:cvs.pdos.lcs.mit.edu:/cvs, module name ``tra''.  The
anonymous CVS repository is a copy of our working repository, and only
updated when we believe Tra is in a particularly stable state.

Tra has been ported to Plan 9, FreeBSD, NetBSD, Linux, and Solaris.
Ports are underway for Mac OS X and Digital Unix/OSF1.  The OpenBSD
port is believed to work, but our only OpenBSD boxes are running
kernels too old to run Tra (they need to support sharing the file
descriptor set across fork).

The repository also contains manual pages, which are reproduced in PDF
form on the web site.

Please back up your files before placing them under Tra's control.
Minisync's -n flag is also quite useful.

Some known issues:

 - Tra doesn't see symbolic links at all.  Proper support
   for symbolic links will be added eventually, though
   probably not before the fall.
 - There's only a simple text interface at the moment.
   Eventually we plan to have a GUI, but we're not
   there yet.

Finally, the CS research community doesn't know anything about how
people use user-level file system synchronizers.  We would like to
address this by collecting traces of synchronization activity.  The
end of the tra(1) manual page explains how you can contribute traces
of your own activity.

Thanks for your help, and enjoy!

Russ Cox
William Josephson

2. Supported Platforms

The currently supported platforms are:

 - FreeBSD
	386 only
	alpha support underway

 - Linux
	386 only
	sparc v8 port underway

 - NetBSD
	386 only
	requires NetBSD 1.6 (aka NetBSD-CURRENT, currently)

 - OpenBSD
	386 only
	requires kernel with support for shared-fd fork

 - Plan 9
	4th ed. only
	386 only, though other architectures are trivial to add

Less well tested or incomplete ports include:

 - Digital Unix
	not yet tested extensively

 - Mac OS X
	passes threading tests, but not tested further
	case insensitive file system will cause trouble (see below)

 - Solaris
	assembler stubs are for v8; not very well tested

The included c/libc/pool.c (the heart of malloc) has a few
lingering incompatibilities when running on 64-bit platforms.
If you want to run on a 64-bit platform (e.g., Digital Unix), for
now replace c/libc/malloc.c with calls to the underlying
malloc, which must be thread safe.

3. Compiling and Installing Tra

To build on Unix:

- set $systype to one of Darwin (MacOS X), FreeBSD, Linux, NetBSD,
  OpenBSD, OSF1, or SunOS.
- set $objtype to one of 386, alpha, power, or sparc.
- make all

If you have the Unix port of the Plan 9 shell rc installed,
you can run the regression test by doing:

	rc
	. testsetup
	make test

To install the binaries and man pages:

	make install-sys

You may want to edit the rules for ``make install-sys'' to fit
your local system.

To build on Plan 9, just type mk.  To build for objtypes other than
the 386, you need to create initcxt$objtype.c and jmp$objtype.c, which
can be lifted from Plan 9's libthread and libc.

4. Porting Tra to a new system

Porting Tra to new systems or architechtures should be a relatively
straightforward process.  If you are porting to yet another Unix
clone, one of the existing ports is a good place to start.  Pieces of
implementation (even architecture-dependent ones) that are likely to
be common to many Unix clones are kept in libunix.

Porting Tra involves writing a subset of the following files, described
in turn below.  For most, the Unix implementation is a good reference.

	ctime.c - format an integer as a local time
	errstr.c - set and retrieve the system error string
	exits.c - exit the program
	fdbuf.c - fork i/o slaves
	fsync.c - force a file onto disk
	ftruncate.c - truncate a file
	initctxt$objtype.c - initialize a thread context
	jmp$objtype.s - setlabel and gotolabel, like setjmp and longjmp
	nonotes.c - insulate self from signals
	repl.c - open a pipe to a new program
	srv.c - file system-dependent service routines
	tas$objtype.s - atomic test-and-set locking primitive

- ctime.c

Provide a routine called sysctime(long), which is like ctime(time_t*) but
is passed the actual time rather than a pointer to it.

- errstr.c

Provide routines rerrstr and werrstr, which read and write the
system error string.  An additional routine errstr should swap the
passed buffer with the system error buffer.  On systems that do not
permit setting the system error string (or have no such concept),
this is usually simulated appropriately.  See c/libunix/errstr.c for
an example.

- exits.c

Provide a routine exits that exits the program.  Exits is exit with
a string status on systems that support it.  On systems that use integer
status, exit with 0 status iff the string is 0 or '\0'.

- fdbuf.c

In order to implement openfdbuf, the host system must provide a
mechanism for creating new processes that can block in system calls
independently from the caller but share the caller's memory space and
file descriptor set.  POSIX pthreads are often sufficient, although
using the underlying mechanism is often cleaner; the Mac OS X and
Digital Unix ports use pthreads.

- fsync.c, ftruncate.c

These are only needed on non-Unix systems and should provide the
traditional Unix semantics.  Ftruncate MUST truncate the file when
passed a zero length.  In other cases, ftruncate is allowed to be a
no-op (as it is on some Plan 9 file servers).  Fsync MUST NOT return
until all data associated with the fd is flushed to disk.  The
correctness and recovery of the database routines rely on this.

- initctxt$objtype.c, jmp$objtype.s

Tra uses its own threading library.  Because of this, porting Tra to a
new platform requires writing assembly code to provide an atomic
test-and-set routine as well as simple context switching routines akin
to setjmp and longjmp.  You will need to provide an implementation of
setlabel, gotolabel, and initctxt.  To test setlabel, gotolabel, and
initctxt, try to run testjump.c.  If that succeeds, move on to running
tprimes.c.  That that succeeds, you got most of the pieces in the
right place.

All threads run on the main stack; stacks are switched via memmove,
so that all stack data can be considered per-thread storage.
The current thread implementation (in c/copythread.c) assumes
that the stack grows downward.  If the stack grows upward you
will need to edit the definition of swtch1.

- nonotes.c

Insulate the calling program from user interrupts (e.g., control-break
or control-c or delete).  Trasrv uses this to make sure it gets a
chance to shut down cleanly.  It is acceptable if this is a no-op.

- repl.c

Dialreplica runs a new program and returns a connection to it.
Unrooted names of replicas are usually interpreted relative to a
personal Tra directory, $home/lib/tra on Plan 9 and $HOME/.tra on
Unix.

- srv.c

Provide basic file system operations used by trasrv.  Most are
self-explanatory.  Typically the only time-consuming part is
translating between Tra's common mode bit format and the
system-specific mode bits and other flag words.

- tas$objtype.s or tas$objtype.c

Provide a routine _tas(void*) that does an atomic test and set on a
machine word.  If the value is set already, it should remain set and
_tas should return non-zero.  If the value is not set, it should be
set and _tas should return zero.  On the 386 this is implemented by
atomically exchanging the value with 0xdeadead and returning the old
value.  RISC machines typically use LL/SC.

- other notes

The current implementation uses sbrk in its malloc implementation
(c/libc/malloc.c).  It would be easy to accomodate the use of mmap if
needed.

We have all the code for a Windows port but have not put it together
because it is fragile without better support for case-insensitive file
system semantics.  We have not yet grappled with how to handle this
during synchronization.  It will require some sweeping changes.  This
is a fairly high priority, but probably below the GUI. The Mac OS X
port suffers from the same problem.  You could use Tra to do
unidirectional backups from a case-insensitive system, but writing to
a case-insensitive system is asking for trouble at the moment.