
**************************************************************************
* WARNING: Running the 'testbox' script in this directory WILL erase one *
* of your harddisks.  Unless this is what you want, do NOT run it.       *
**************************************************************************

TESTBOX V0.1    1998/09/21


The contents of this directory is used for creating pre-configured
harddisks with FreeBSD.  This README file is used for getting confused
and getting an impression of a rambling lunatic (me, eivind@freebsd.org).


To set up a testbox, I do the following:
1. I connect a scratch IDE drive to the secondary controller of my
   machine.
2. I reboot from my SCSI drive (you can boot from an IDE drive, too,
   just not the one you're going to do 'testboxing' on).  If you have
   an old BIOS, you can do this by disabling one or more controllers,
   and letting FreeBSD probe them (which is usually independent of the
   BIOS).
3. I use the 'testbox' script with a suitable configuration file to
   fill the disk with data.  Example:
	cd /usr/src/release/testbox
	./testbox wd2 ROVER
   (Complex, wasn't it?  The detail is that you need a completed
   'buildworld' in your sourcedir, for the time being)
4. I disconnect the drive (without shutting down my computer), and put
   it into my testbox.  Said testbox boot from the disk, and do
   whatever I wanted to test.
5. If that leads me to need a new setup on the testbox, I re-connect
   the disk and repeat step 3. and 4. :-)

However, there are a number of gotcha's here:
* Do NOT type the wrong diskname.
* Don't connect the disk power together with the power for another
  disk - use a separate powerlead from the powersupply.
* Don't connect other disks to the same IDE or SCSI-cable as the drive
  you're hot-plugging.  You _will_ get corrupt data at some point if
  you break this rule.
* Disconnect the power first, the bus (IDE/SCSI) second.
* Don't get a short when hot-plugging - ie, be a little bit careful to
  insert the connectors straight.  (This is not difficult to follow).
* Don't access the disk while it is disconnected.
* Don't hot-plug the disk while it is mounted.

If you follow the rules, you are unlikely to see any problems.  I've
been doing this several times daily for over a year without breaking
anything (except that I've had a couple of non-fatal problems when
breaking the above rules).



Anticipated uses for the supplied technology:
1. Creating testboxes for checking kernel modifications.  The 'ROVER'
   configuration file is an example of this - it will run a series of
   kernels, running through a 'make buildworld' with each of them.
   This allow you to do pretty precise measurements of how a kernel
   change impact performance (variation on good hardware should be
   less than 1/2 percent).
2. Creating embedded systems or other special FreeBSD configurations
   which are replicated many times with the same customizations.  No
   examples included.


Relevant files:
README    This file.
ROVER     Example configuration file for running multiple kernels with
          the same load (for measurements).
testbox   Perl script to fill a harddisk with the results of a
          configuration.  THIS SCRIPT ERASE A HARDDISK!

Irrelevant files:
labeledit.pl - Helper script for 'testbox'.  Used during labelling.
boxbuild/    - Default location for mount of the new disk during filling.


CONFIG FILES

Comments are introduced by the pound sign (#).  Commands are done as
"command-type: <parameters>".  The parameters are separated by spaces,
and can in some cases have quotes (sorry - this is an ad-hoc parser at
the moment).

The places which take input filenames can also take here-documents,
using the familiar << EOF\n <lines> EOF\n syntax.  Note that to make
this generic, the next line after EOF (or whatever you call the
separator) will be included as part of the previous command line.  Ie,
the entire sequence is pulled together to a single token, including
the trailing newline.  This make it possible to use here-documents
inside an argument list.


Commands (active):
override-file <destination filename> <source>
	Install a replacement file on the created machine.  There can
	be many of these, and all will be done.
kernel <destination filename> <architecture> <config name> <source config>
	Build a kernel based on this specific configuration, and
	install it somewhere.  The kernel will be built in a specially
	symlinked source tree.

Commands (passive):
config-name <name>
	Name of this config.  Defaults to the name of the file.
source-dir <directory>
	Location of source tree.  Defaults to `pwd`/../.. (to support
	the testbox tree in src/release/testbox).
boot1
	Location of boot1.  Defaults to /usr/mdec/boot1
boot2
	Location of boot2.  Defaults to /usr/mdec/boot2
labeller
	Tool to use to edit the disklabel.  Defaults to the supplied
	labeledit.pl script.  You probably don't want to override this.


TODO
* Make this build kernels automatically. (In progress)
* Make this built config(8) (or use it from an underlying buildworld).
  Same for cc/make.
* Fix perl code to automatically check /usr/bin/perl5 or /usr/local/bin/perl5
* Add support for SUBDIR_CHANGE, to be able to change how the system
  in general is built.
* Add support for modifying the kernel config system (conf/options,
  conf/files, architecture-specific versions of same, add directories,
  and override files) for the kernels built in a testbox script.
* Add checks for whether buildworld and kernel builds needs to be done
  or not.
* Better error checking
* Ability to do full rebuilds (which needs to erase old stuff)
* Support OBJDIR.
* Allow override of make.conf for builds
* Allow tweaking of bootblocks for build (to be able to use different
  baudrates)

If you do anything to these scripts, please send the patches to me -
eivind@freebsd.org.  I'll try to be timely in integration (though I
can't guarantee anything).  It would be nice if you had patches
against the latest version, but this isn't a strict requirement.

Please report if you find anything unclear/wrong in the docs, too.

Eivind.
