============================
Coda Release 
============================

version: 4.0.5
Linux alpha
date: 6/16/97


These are partial instructions how to setup, build and configure the
Coda file system. Refer to the manual in doc.  Use RPMS to install on Linux. 

Contents
========
I. Configuring and Building Coda
1. Configuration
2. Usage
3. What gets build
4. Building coda

II. Information about our Makefile setup

III. Building on Mach (for CMU)

LICENSE:
======== 
READ THE FILE COPYING 

========
WARNING: 
========

CODA IS NOT READY FOR REAL USE, PARTICULARLY ON LINUX. THIS RELEASE IS
JUST FOR THOSE INTERESTED IN PLAYINT WITH THOSE FEATURES WHICH
WORK. IT CONTAINS KERNEL CODE, AND SERVERS RUNNING WITH ROOT
PRIVILIGES, AND COULD LEAD TO DATA LOSS.


I. Installing and configuring Coda.
===================================

0.  Changes: there have been numerous 


1.  Configuration
	a) on a client run the script linux-utils/venus-setup.
	     venus-setup comma,separated,hosts cachesizeinkb
           By default you are talking to testserver.coda.cs.cmu.edu
	   I strongly recommend you try that first.

        b) Servers: this is a bit more work. Also note that running
           a server seriously dips into your virtual memory. Running a 
           server _and_ a client and X11 I have needed slightly over
           64M of available VM. The command free gives information.

           Then run 
              vice-server-setup 
           Answer the questions. This sets up a default server, with 
           a single volume.  In due course we will have scripts to add
	   replication servers and more flexibility.
           
           NOTE: you must mount a filesystem on /vicepa in this
              preliminary release.  Don't panic if you don't have a 
              free partition, you can use a file and a loopback
              device.  Do the following (for 10MB server
              space):

            insmod loop
            dd if=/dev/zero of=afile bs=1k count=10000
	    losetup /dev/loop0 afile
            mkfs -t ext2 /dev/loop0
            mount /dev/loop0 /vicepa

  	   NOTE 2: you need the package bc (binary calculator on the server).
                   get it from Red Hat or from our ftp directory.
	

2. Usage:
	a) server startup:
            srv -rvm /rvm/LOG /rvm/DATA 20480000 -d 1000 &
            xterm -e tail -f  /vice/srv/SrvLog & 
           when the server is up:
            vice-makerootvol 
           Note: if you didn't use vice-server-setup then you need to 
           read the manual.

        b) client: (** make sure the server is up _AND_ you have
                       made root volumes **)
	   start venus with 
            insmod coda     ( you may not need to do this )
	   if your kernel is not version 2.0.29 you should move the module:
            cp /lib/modules/2.0.29/fs/coda.o /lib/modules/`uname -r`/fs

            venus -init &
            xterm -e tail -f /usr/coda/venus.cache/venus.log
            xterm -e codacon
	   When the server is up cd to /coda and start playing.


        c) Restarting a server. volutil shutdown shuts down the server.
	   Restart as above.

	d) Restarting a client. You should umount /coda, since this 
 	   may not get done automatically. If it fails, make sure you
           kill all processes using /coda; cd out of Coda directories etc. 

	   If ps aux | grep venus displays a Zombie venus, reboot 
           your machine before trying again.  (If you don't you'll
           likely have to run fsck by hand later.)

	e) Troubleshooting.
           I) If the server crashes before you have used it through
              /coda, do rm -rf /vice /rvm and start all over. At the
              minimum you must do vice-killvolumes before you restart.

	      Remember: first clean, then start srv, then make rootvolumes.

	   II) If venus comes up but hangs or crashes, check for zombie 
              venus processes. If these exist, reboot first.

3.  There are 5 subsystems that need to be build

	a) kernel-src kernel code for coda filesystem calls and 
	   inode manipulation kernel code.
	b) lib-src contains libraries needed by other components,
	   including a threads package used by many other user
	   level components
	c) rvm-src contains the rvm transaction package, depends 
           on threads
        d) coda-src contains source for coda, depends on a, b, c
        e) util-src contains nothing right now but will contain
	   a variety of tools, for testing, kernel
           hacking. Dependency varies.


4.  Building coda (outside CMU):
       -a) unpack the source; you need gcc, g++, flex, ncurses etc, and 
           have 80MB free to build from source.
	a) at the top level type ./configure --enable-platform=...
	   choices: i386_linux2,i386_nbsd1,i386_mach,pmax_mach
           use other configure flags as desired.
	b) at the top level type make coda
	c) at the top level type make install-client, or make install-server
	d) rebuild kernels if needed
	e) configure clients/servers and you should be up.

Peter J. Braam
braam@cs.cmu.edu


II. Makefile Information
==========================

(Makefile setup converted to GNU tools by Peter Braam and Josh Raiff.
Further substantial improvements by Bob Baron.)


Every
Makefile includes (says what/how to process in this directory)
     1.	Makeconf includes (sets VPATH, DIRS, FLAGS, LIBRARIES, _RPC2)
	     a.	Makefile.setup (variables set as part of the configure process)
	     b.	configs/Makeconf.$(SYS) (sets machine dependent VARIABLES, flags)
     2.	Makerules (says how to build/install/clean & some specific rules)

		GLOBAL VARIABLES you set on the command line

GFLAG=	 request debugging info on compilation (GFLAG=-g is the default)
OPTFLAG= request optimization (OFLAG=-O is the default)
DEPFLAG= request dependency generation (DEPFLAG= is the default)
LIBFLAG= {G}CC options used when creating a a.out
MYFLAGS= any old thing you want

		GLOBAL VARIABLES CREATED BY configure

TOPDIR	top of source tree
srcdir	here
SECSRC	user source area
SHOB	shared objects
TOPOBJ	top of build area subquently define

		GLOBAL VARIABLES PROCESSED BY Makerules

EXECUTABLES
	build; install to .../bin; rm on clean
HEADERS
	no build;install to .../include; no clean
LIBRARIES
	build; install to .../lib; rm on clean
RP2FILES
	rp2gen these files; no install; rm *.multi.c *.client.c *.server.c
RP2HEADERS
	no build; no install; rm on clean
SCRIPTS
	no build; install to .../bin; no clean
SUBDIRS
	visit & install or all
TESTS
	build; no install ??; rm on clean



III. BUILDING on MACH (for CMU mostly)
======================================

Bob Baron, Jan 1997

	I tried to get a consistent envirnoment for the i386_mach and
pmax_mach.  I have focused on gcc 2.5.8 on both platforms.  I have put
the g++/c++/gcc's into an appropriate bin.  I added mkdir and gmake to
the bin.  I added a libg++.a to the lib and I put some "mach" headers
into include that were used.  So ideally if you put
/afs/cs/project/coda/@@sys on all your paths, the pmax and i386 should
work.  (Note: it might be necessary to do a:
		modmisc - -release alpha cs.misc.gnu-comp on your
build platform.  Using an old gnu-comp in /usr/misc has not been
tested yet.)

To build, you need to put /afs/cs/project/coda/@@sys on your paths.  You do
		setpath -i1 /afs/cs/project/coda/@@sys
If you don't use cmu shell, you must do:
		set path = (/afs/cs/project/coda/@@sys/bin $path)
		setenv LPATH /afs/cs/project/coda/@@sys/lib:$LPATH
		setenv CPATH /afs/cs/project/coda/@@sys/include:$CPATH
Personally, I do a
		setpath -r
before I start the build process.  This command resets all paths to a minimal
state.
	
