release/zero CVS

[Eddie Kohler]

I've rearranged our CVS repository for better configurability and stuff. Do
you like it less? Please let me know.

SUMMARY OF THIS EMAIL
---------------------
1. startup
2. faction collections
3. CVS and other stuff

1. STARTUP
--------------
It is in the release/zero CVS repository. To get it, do

	% cvs -d /home/butt/click/cvsroot co -d LOCALDIR release/zero

where LOCALDIR is a directory you want the sources to be in.

You will need to do a couple things before you can type `make':

	% cd LOCALDIR
	% autoheader
	% autoconf
	% ./configure

`./configure' will figure out whether your kernel has Robert's changes and
other neat stuff, and generate Makefiles.

The build directories are `linuxmodule' and `userlevel', as before. Generic
source is in `lib' (faction.cc, vector.hh, etc.).

2. FACTION COLLECTIONS
----------------------
You can give options to `./configure' to turn on or off collections of
factions. The selectable collections are standard, ethernet, ip,
etherswitch, ipsec, radio. Use `--enable-COLLECTION' or
`--disable-COLLECTION' to turn a collection on or off. For instance:

	% ./configure --disable-etherswitch --enable-ipsec
	# don't compile etherswitch factions, do compile IPsec factions

All collections are on by default, except for ipsec.

Collections are represented as subdirectories of `factions'. All new
factions should be placed under `factions'. If you add a new subdirectory,
change `configure.in' to add a new `--enable' argument. This is easy; look
for FACTIONS_ARG_ENABLE.

The `mkfaclist.sh' shell automatically adds faction .o files to the
Makefiles, and creates C++ code to add the selected factions to the lexer.
So you don't have to worry about that any more. You do have to add code to
the factions' .cc files to tell `mkfaclist.sh' what factions are created.
Look at any faction source file; basically, you add one or more
EXPORT_FACTION macros:

	EXPORT_FACTION(SimpleRED)
	EXPORT_FACTION(FullRED)

EXPORT_FACTION must be at the beginning of a line, by itself.

You can use FACTION_REQUIRE to say that a particular .cc file can only be
compiled in the presence of some requirements. For instance, RED doesn't
make sense without Queues, so red.cc says

	FACTION_REQUIRE(Queue)

And the BIM faction from the radio collection can't be compiled in the
kernel, so bim.cc says

	FACTION_REQUIRE(!linuxmodule)

`mkfaclist.sh' will warn about any factions it can't compile because of
requirements failures.

The list of .c and .cc files that `mkfaclist.sh' uses is stored in the 

3. DEALING WITH CVS
-------------------
ADDING TO CVS ... Put new factions in a subdirectory under `factions'. If
you create a new subdirectory, or delete an old one, change the
`FACTIONS_ARG_ENABLE' calls in `configure.in'.

UPDATING FROM CVS ... After you do a cvs update, it's probably a good idea
to change into the top-level directory and type `make faclist'. This jumps
through hoops to make sure your setup is current -- running autoconf,
autoheader, and ./configure if you need to, and then generating new faction
lists (in case people have added new factions to the repository).

INSTANCES OF VECTOR AND HASHMAP ... If your faction needs a particular
instance of Vector or HashMap, don't put it in `hashmapi.cc' or
`vectori.cc' any more. Put it at the end of the faction .cc file instead.
See `classifier.cc' and `snooptcp.cc' for examples.

VPATH ... You can use ./configure and VPATH to create object files in a
different place than the source tree.

	% cd BUILDDIR
	% SOURCEDIR/configure
	% make

Warning: This will fail annoyingly (link error message: `no such .o file')
if you have object files in your SOURCEDIR tree.

THE SOURCES ... were current as of yesterday. If you've checked stuff in
since then, check them in to the release as well. We should only work on
the release from now on.

love,
ed