WHAT
----

BRU (Backup and Restore Utility) is an advanced UNIX file archiving
utility, with significant enhancements over other more common
utilities such as "tar", "cpio", "volcopy", and "dd".

WHERE
-----

This is the root node of the BRU distribution directory tree.
Subdirectories and their uses are:

	src	=>	Program sources.  Binary distributions
			include only the files src/unix/bru,
			which is the executable program, and
			src/unix/autoconfig.h, which is the
			configuration file.

	doc	=>	Documentation such as manual page,
			implementation description, etc.

	notes	=>	Miscellaneous "random" thoughts that give
			some insight into why things were done a
			particular way.

	test	=>	Tests to probe device capabilities, bru
			functionality, etc.  This section will probably
			be greatly expanded in a future release when
			automated testing and verification is implemented.


HOW
---

To install BRU on a new machine from the source distribution:

	(1)	Make the bru documentation and executable on a unix machine:

			make -f bru.mk

		Note that there is an autoconfiguration script, called
		config in src/unix, which make will attempt to run if
		there is no autoconfig.h, or autoconfig.h is out of date
		with respect to the autoconfiguration script.  There
		is also another environment setting script called "make.sh"
		which make will attempt to run if it is invoked without
		an explicit target to build.  In general, make.sh and config
		will properly configure your make environment for the host
		machine.  If this fails, you will probably need to
		invoke make.sh with an appropriate existing argument
		(like "make.sh -sun3" for example) or define a new
		known environment using one of the existing ones as
		a model.  As a last resort, you can also edit autoconfig.h
		to explicitly set the desired environment dependent defines.

	(2)	This version of bru now contains a loadable device
		table. In early versions of bru, the table had to be
		initialized prior to compilation.

		If you are in a hurry to get a functional version up
		and running you can skip this step for now and just
		guess at the appropriate parameters or use someone
		else's.  Note however, that optimum performance is
		only obtained with a correct table entry.

		One of the easiest ways to discover the correct errno
		numbers for brutab fields like "fwerr", "wperr", etc
		is to compile a special test version of bru with
		the macro based debugger enabled (make.sh -dbug) and
		then run this version with conditions sufficient to
		trigger error recovery (like inserting an unformatted
		floppy) using the command line argument "-#d,fault".
		When run, you should see a line that looks something like:

			errno from original error = 5

		You can then use this literal numeric value in the
		appropriate brutab field, or translate it to a symbolic
		value (preferred) as found in /usr/include/sys/errno.h.

		Use the information about each system device to modify the
		loadable device table data file template (./brutab) and
		install the brutab file in /etc/brutab.

			edit brutab
			cp brutab /etc/brutab
			
		Note that the environment variable BRUTAB can be set
		to the pathname of an alternate file to load for
		testing purposes.


MISC NOTES
----------

	(1)	If you regularly use an archive device which accepts
		media of variable size, but the sizes come in only
		two or three values, then rather than having one
		brutab entry with a "size=0" field (since the actual
		size is not fixed, hence unknown), you can make several
		different names in /dev, with each one linked to the
		original device name.

		For example, if you have a streaming tape drive that
		is accessed via /dev/st0, for which you commonly
		use either 40Mb or 60Mb cartridges, then you can
		create /dev/st0.40 and /dev/st0.60 as links to
		/dev/st0, and clone the /dev/st0 brutab entry to
		produce entries for /dev/st0.40 and /dev/st0.60, with
		"size=40M" and "size=60M" fields, respectively.

		When using 40Mb cartridges, you would tell bru to
		use the /dev/st0.40 device.  You could also simply
		remember to use the -s option and invoke bru with
		the "-s40M" command line option.  Whenever possible,
		if you know the actual capacity of the media, you
		should convey this information to bru.  Correct
		error recovery is greatly aided by knowing the
		actual media size.

	(2)	On systems with System V style shared memory, which
		is used to support double buffering via the -D option,
		some experimentation may be necessary to determine
		the best values to use for the size and number of
		shared memory segments to use.  Basically, bru will
		attempt to get by with whatever segments it can
		create.  However, the defaults may either be smaller
		than the optimum for greatest throughput, or larger
		than necessary, thus tying up valuable memory
		resources and potentially slowing down the entire 
		system.  For further discussion and tuning hints,
		look in the notes/shm-tuning file.

		
