-- @(#)INTRO-OTSO	5.4 --


OTSO is an Object Oriented development tool for developing distributed OSI
protocol applications.  It can also be used for developing
other distributed applications.  OTSO was developed using the C++
programming language.

"Otso" is a Finnish word for a bear.  It also refers to the Transport
Service between two Objects.

OTSO was developed as part of the FINSOFT "Protools" program.  The
acquisition, use, and distribution may be restricted to certain
conditions.

Please read READ-ME file for contact information, if you have bugs,
comments, questions, or use e-mail : OTSO@tel.vtt.fi


Contents of this file:
	(1) OTSO DIRECTORIES
	(2) UNIX SYSTEM VARIABLES
	(3) COMPILING OTSO (via UNIX make)
	(4) G++ Problems
	(5) - SCCS 
	    - dv_make, dv_create and dv_sccsup 
	(6) USING OTSO
	(7) OTSO DOCUMENTATION
	(8) MAKING BACKUPS OF OTSO (UNIX tar files)
	(9) DISK SPACE NEEDED FOR OTSO
	(10) C++ DEBUGGER Hints
	(11) CAVEATS


(1) OTSO DIRECTORIES:
----------------------
OTSO contains the following directories (some of these are not available in
public release):

appli/		- applications, e.g. on top of protocols
bin/		- executables such as prepro and demos.
casnsupport/	- support library for use with modified CASN compiler,
		  hacked out of Nokia's original runtime code.
compiler_bugs/	- bugs other users have found with C++ implementations
docs/		- documents concerning use of OTSO
demo/		- all demo subdirectories under demo.
dvops/		- Distributed Virtual Operating System of OTSO.
		  (kernel)
enviros/	- anything in OTSO that is somehow dependent on the
		  runtime environment (compiler used, Host operating
		  system, hardware, etc).  Should contain all the
		  source code in OTSO that one needs to think about
		  porting,  all other directories are pure C++ and
		  should be portable.
enviros/device/	- device class source code.  Subdirectories by OS used.
enviros/device/include	
		- all header files to be used with main OTSO 
		  device class libraries.
enviros/makes	- contains the system.make file that sets all the settings
		  for local Makefiles, run from local directory 'make' files.
		  system.make is generated from system-specific Makefiles.
example/	- an example of using Makefiles with OTSO
include/	- all header files to be used with main OTSO library.
include/incfirst - Certain OTSO header files should be included before
		  local or other OTSO header files.  e.g. OTSO.hxx and
		  PROTOCOL.hxx.  This is inclusion at compile time:
			CC -I/otso/include/incfirst -I. -I/otso/include ...
include/device	- all header files to be used with main OTSO 
		  device class libraries.
include/protocols - all header files to be used with main OTSO 
		  protocol class libraries.
include/cvopshdr  - header files to be used with OTSO code taken from
		  CVOPS.  This is mostly cframe.c cframef.c in libdvops,
		  and for the casnsupport sourcecode, since casn was
		  was originally developed for use with CVOPS.
isoaddrs/	- ISO address classes (for psap, ssap, tsap, etc).
lib/		- all OTSO libraries go here: libdvops.a, libdevbsd.a,
		  libsess.a, libtran.a, libtran.a, etc.
make*		- each directory has an executable file 'make' that is
		  an alias for make.  It uses system/system.make (system
		  dependent) and include/headers.make (macros for header 
		  names).
makes/		- various make files.  all 'make' shells in other directories
		  should be linked to level1.make, level2.make, etc.
man/		- contains man page subdirectories for OTSO.  You can
		  use the OTSO man pages by (in UNIX's /bin/csh):
			alias dman	'man -M $OTSO/man $*'
			dman subjectname
		    Developers should try to write and add man pages 
		  for important new classes to $OTSO/man/man1 after
		  they are developed and tested.  man pages about
		  OTSO runtime files are in $OTSO/man/man5.
		    Man pages can be generated automatically from .hxx
		  header files, by using the sdoc or psdoc (postscript doc)
		  facilities of OTSO.  
prepro/		- OTSO preprocessor source code.  OTSO extensions to
		  the C++ language.
protocols/	- OTSO OSI protocol implementations. Subdirectories:
		  7=applications, 6=presentation, 5=session, ...
sccs/		- dv_make, dv_create, dv_sccsup are here, SCCS headers too.
		  Generic SCCS headers for OTSO are in sccs/create:
			sccs.h.cx for .cxx files, sccs.h.c for .c files,
			sccs.h.hx for .hxx files, sccs.h.h for .h files,
			etc.
		  The appropriate generic header should be placed on 
		  the top of files before they are delta'd into SCCS files.
		  This can be done by using dv_create, etc.
simsrc/		- source code for simulation
simdemo/	- simulation demos and examples
tools/		- useful tools for OTSO.
tutorial/	- some example programs
util/		- some useful shells.


(2) UNIX SYSTEM VARIABLES:
--------------------------
Remember to define the variables OTSO, and the PATH as shown below. 
The following is a suggestion to add to your .cshrc file (if you run /bin/csh),
or your .profile (if you run /bin/sh), or your .bashrc (if you run /bin/bash):

# OTSO definitions
setenv OTSO /usr/local/src/otso
setenv PATH "$PATH":"$OTSO"/sccs:"$OTSO"/sccs/create:"$OTSO"/bin:"$OTSO"/tools


(3) COMPILING OTSO:
---------------------

See file INSTALL-OTSO !

Every Directory that has compilable source code (except the include
header directories) has a UNIX Makefile and a UNIX 'make' file.  'make' is
an alias that usually looks something like this:

: run this script through /bin/sh. This file is 'link'ed to other 'make' files.
exec /bin/make TOPDIR=../ -f ../system/system.make -f ../include/headers.make -f ./Makefile ${1+"$@"}

OTSO should compile using /bin/make in HPUX, but you may encounter some 
problems (with symbolic links and *.a files) in HPUX when you start working 
in a subdirectory.  GNU's gmake (or Sun's /bin/make) should work better.

Many Makefile Macros are defined in system/system.make (e.g. CC, 
CFLAGS, etc).   include/headers.make contains many Makefile Macros that
define the location of header files and groups related header files 
under single Macro names (to make Makefile dependencies shorter to write).
Look at them both for more details.

The Makefiles usually have several targets.  Sample targets are 'all',
'plib', 'dlib', 'prepro-all', 'exe-all', 'install', 'clean',
and 'documents'.

The root makefile target 'all' is generally what you use to create libraries,
demos, etc.   The order in which targets are created in 'all' is important.
You can't create the protocol libs until the prepro has been created, for
example.

EXAMPLE (/bin/csh):
	$ cd /usr/local/src/otso
	$ make >&! make.log &
		.... make OTSO libraries first  'dlib' ....
		....      install OTSO libraries to otso/lib ....
		.... makes prepro next 'prepro-all' ....
		....      install prepro to otso/bin ....
		.... make OTSO protocol libraries next  'dlib' ....
		....      install OTSO protocol libraries to otso/lib ....
		.... makes demos and other executables last 'exe-all' ....
		....      install other executables to otso/bin ....

OR:
	$ cd otso/enviros/device/bsd
	$ make libdevbsd.a
		.... files recompiled .....
		.... local libdevbsd.a made ....
	$ make inst-all
		.... /usr/local/src/otso/device/bsd/libdevbsd.a 
			copied to /usr/local/src/otso/lib ...

You may change the list of 'DIRS' in the root Makefile so it
reflects what you want made each time.  For example, you may not
want all the demo programs recompiled each time.  At a minimum,
you probably should leave the existing library targets and 
the prepro target as they are.

The 'inst' targets install executables or libraries to otso/bin
and otso/lib respectively.  The 'install' target installs, and 
then 'clean's. 

The target 'clean' is used to clean out .o's and other unnecessary junk
that clutters up directories.  To give your fair warning, these are the
types of files removed (so be careful about renaming files as file.old
or file.tmp; or alternatively name your junk files mystuff.tmp so they
get cleaned out) :
CLEANSTRINGS = 	*.o *.a core *.old *.tmp *.i *.ixx \
		version.major version.minor version.local \
		,*
EXAMPLE:
	$ cd /usr/local/src/otso
	$ make clean
			... junk cleaned out ...

The target 'tar-clean' is used to clean out all non ascii code, to
make tar file creation shorter, and to make tar files smaller and
more portable between different boxes that run OTSO.  Please add Makefile
statements to tar-clean out libs and exes as you add them to OTSO.  Also,
make sure to run 'make look-opend' before 'tar-clean' to find open
deltas.

EXAMPLE:
	$ cd /usr/local/src/otso
	$ make look-opend
		.... you should close any open deltas that were reported ....
	$ make tar-clean
		... all executables + libs + objects + junk cleaned out ...
	$ cd /usr/local/src/otso
	$ make public-release

The target 'look-opend' should be run before 'tar-clean'.  It prints
out a list of open deltas.  You should try to close all open deltas 
before releasing OTSO to others.

The target 'documents' is unused now.  It is hoped that someday
each OTSO directory will have some sort of .doc file explaining
it in detail.  Maybe 'documents' could be used to make a master
document, or install man pages,  or print out the documents for
each directory.  It is for future use.

If you don't have UNIX make, you are out of luck.  Maybe GNU make
will work ?  OTSO Makefiles have only been tested with SUN make, HPUX make,
and GNU make, so there may be problems with other UNIX make programs.


(4) G++ Problems
--------------------------

We used to have conditional compilation switches for GNU's g++,
but they are not maintained anymore.  The latest version
we tried was gcc 2.0, but we still had problems with stream library
compatibility.  Anyway, if you are trying to GNU gcc compile OTSO, it 
probably is NOT wise to set COMPILER_GPLUS on. 



(5) SCCS + dv_make, dv_create, and dv_sccsup
--------------------------------------------

NOTE: It is strongly recommended that you sooner or later become
familiar with the UNIX command 'sccs', as dv_* are merely
shell scripts that use the UNIX 'sccs' commands.

'man sccs' should be sufficient to learn about sccs.

DIRECTORY WITH MANY FILES TO BE ADDED TO SCCS (dv_make) :
---------------------------------------------------------
dv_make is used to add OTSO SCCS headers to A WHOLE DIRECTORY OF FILES
and create them into an SCCS directory.  It is used as follows:
	$ cd /usr/local/src/otso
	$ mkdir newstuff
	$ cd newstuff
	$ cp $HOME/mystuff/* .
	$ dv_make
		....
		remove Makefile ?   no
		.... everything in directory newstuff
			is deltaed into newstuff/SCCS/s.* ....
		remove s.make ?	    yes
		....
'dv_make' recognizes many endings (.c, .cx, .cxx, .h, .hxx, .y .l, ...)
and adds the appropriate SCCS header to each from /usr/local/src/otso/sccs/create.
Make sure you define the Unix environment variable $OTSO as stated above !  
See dv_make for the full list of endings it knows about, and add 
new ending types there !

Once a directory has been created with dv_make, you must use
'sccs create filename' to add new files to the directory.  You
must make sure to add the proper OTSO header to the start of
the file by hand first.  You may need to look at dv_make to
find which otso/sccs/create/sccs.h.filename to use as the header.


ADDING JUST A FEW NEW FILES TO AN EXISTING SCCS DIRECTORY (dv_create) :
--------------------------------------------------------------------
When you need to add a NEW file to an existing SCCS directory, use
dv_create in the following manner:

Example (1):
  $ cd /usr/local/src/otso/dvops
  $ ls newname.cxx SCCS/s.newname.cxx
  Files not found.

  -- it's ok for us to add our new file. 

  $ cp ~me/newname.cxx .
  $ dv_create newname.cxx
  Putting jfr.cxx into SCCS ...
  cp: jfr.cxx: Permission denied
  No id keywords (cm7)
  1.1
  No id keywords (cm7)
  70 lines
  $ pwd
  /usr/local/src/otso/dvops
  $ ls -l SCCS/s.newname.cxx
  -rw-rw-r--  1 me         11820 Jan 17 15:37 SCCS/s.newname.cxx
  $

  -- and you're done.

dv_create will complain if the file exists in SCCS already:

Example (2) :
  $ cd /usr/local/src/otso/dvops
  $ cp ~me/myvops/newname.cxx .
  $ dv_create newname.cxx
  Putting jfr.cxx into SCCS ...
  ERROR: That file already exists in SCCS !
  $


UPDATING FILES THAT EXIST IN AN EXISTING SCCS DIRECTORY (dv_sccsup) :
---------------------------------------------------------------------

'dv_sccsup' is used to update changes to OTSO files kept in SCCS.
It is used as follows:
	$ cd /usr/local/src/otso/dvops
	$ ls SCCS/s.agent.cxx
	SCCS/s.agent.cxx
	$ dv_sccsup	$MYDIR/agent.cxx
	Old Version:	1.1
	Your Version:	1.1
	Continue ?	yes
		..... s.agent.cxx is updated with your changes ....

dv_sccsup needs to have the same type SCCS header in both the s.file
and your file with changes.  If your version number doesn't match
the latest version in SCCS, answer no !, and put your changes on
top of the latest version and then try dv_sccsup again.  If the
versions don't match, it means someone else has put changes to
the file since you began working on it.  DO NOT answer yes as
dv_sccsup is quite simple and will overwrite the other persons
changes by just 'cat'ing your file over their changes.

Simple SCCS changes can be done as follows:
	$ cd /usr/local/src/otso/dvops
	$ ls SCCS/s.agent.cxx
	SCCS/s.agent.cxx
	$ sccs edit agent.cxx
	Old Version: 1.1
	New Version: 1.2
	$ emacs agent.cxx
		... add your changes ...
	$ recompile and make sure changes work
	$ sccs delget agent.cxx
	1.2
	0 lines deleted
	10 lines inserted
	1.2
	$ grep Version agent.cxx
	/* Version: 1.2 */
	$

Simple fixes to a version (without creating a new version) can
be done by:
	$ sccs fix -r1.2 agent.cxx

the -r version# is mandatory.  See SCCS man pages for more details.
	
SCCS REMEMBER:
--------------
To OPEN A DELTA, use: 'sccs edit'
To CLOSE A DELTA, use: 'sccs delget'
SCCS/s.filename is the sccs file with all the changes ever 
	done to filename via SCCS.
SCCS/p.filename is a list of changes (OPEN DELTAS) currently
	in progress in SCCS for filename.


SCCS keeps:
	 CLOSED DELTA files in -r--r--r-- mode.
	 OPEN DELTA files in -rw-r--r-- mode.

By files, I mean the actual source, not the s.files:
	$ cd /usr/local/src/otso/dvops
	$ ls -l a*.cxx
	-r--r--r--  1 jfr           943 Nov 17 11:41 agent.cxx
	-rw-r--r--  1 jfr	     40 Nov 17 11:43 alamo.cxx
agent.cxx is a CLOSED DELTA, but alamo.cxx is probably 
an OPEN DELTA (check for open deltas by looking for SCCS/p.*,
or use 'make look-opend').

'sccs get filename' will fail if the file exists already
and is in 'rw' mode.  This prevents overwriting changes that
are in progress.  

If you open a delta via 'sccs edit' and change your mind,
you don't have to 'sccs delget' with no changes.  Remove the
OPEN DELTA file ('-rw-r--r-- mode'), and remove the SCCS/p.filename
for your file.  The  p.filename keeps a track of what version deltas 
are open for filename (rember to remove the p. and NOT the s.).
	$ sccs edit agent.cxx
	Old Version 1.2
	New Version 1.3
	$  .... oops, I don't have any changes to do ....
	$ rm agent.cxx SCCS/p.agent.cxx
	$ sccs get agent.cxx

It is a good idea to close open deltas (found by searching for
SCCS/p.* or 'make look-opend'), before releasing 'tar' tapes of OTSO, etc.


(6) USING OTSO HEADERS AND LIBRARIES TO CREATE YOUR OWN PROGRAMS
----------------------------------------------------------------
OTSO tries to provide libraries to be used in your local directories.
The first step is to make OTSO.  The second step is to write your code
that uses OTSO libraries. The third step is to compile your new
code, (in your local directory) with the OTSO libraries and try 
and get it to run (It would be a good idea to learn how the UNIX
archiver 'ar' command works, so you can replace .o's in archives
on the fly).  Perhaps you will add new libraries, tools, 
demos, etc to the main OTSO directory structure when you feel they 
work well enough.  

The emphasis is that in your working directory, that you should
only have new source code (or changes to old source code), and
that you use existing OTSO libraries as much as possible
(or modified local copies when necessary), so we don't have the 
same, exact source files repeated in everyone's working
directories.

You can make a template of an otso protocol class + service and
peer classes by the following command:

/otso/tools/otsotemplate filPref className

It will make a local directory called "filPref-templ" with a bunch
of files beginning with your "filPref".  The files will be
built for class "className".  A Makefile is also produced for
you.  

e.g.  otsotemplate tran0 Tran0 produces the following files:
tran0-templ/Makefile
tran0-templ/make@
tran0-templ/tran0.cx
tran0-templ/tran0.hx
tran0-templ/tran0_demo.cx
tran0-templ/tran0_demo.hx
tran0-templ/tran0_demo.pro
tran0-templ/tran0_demo.str
tran0-templ/tran0_peer.cx
tran0-templ/tran0_peer.hx
tran0-templ/tran0_serv.cx
tran0-templ/tran0_serv.hx

You can then `cd tran0-templ` and issue a `make` command and your template
should compile.  Please report any problems with this.



(7) OTSO DOCUMENTATION
-----------------------

- OTSO User's Guide (a paper document)
- Look at otso/docs directory for other documents.
- Look at otso/Makefile for other targets (like doc).
- Header files for otso classes are in otso/include.
- Read the source.

Documentation for OTSO classes in the form of UNIX man pages is available.
It exists in the /usr/local/src/otso/man subdirectories
(specifically /usr/local/src/otso/man/mann).
This documentation is generated by the OTSO 'prepro' tool out of C++ header 
files:

% cd /usr/local/src/otso/prepro
% make inst-all
% cd /usr/local/src/otso/include
% make
% ls /usr/local/src/otso/man/mann

The best way to see the documentation is to do one of the following:

  1) nroff -man /usr/local/src/otso/man/man1/object.n

  2) alias man 'man -M /usr/man:/usr/local/src/otso/man'
     man object

  3) run sdoc or psdoc on the OTSO header files in /usr/local/src/otso/include
     e.g.	psdoc /usr/local/src/otso/include/object.hxx > object.ps

Other OTSO documents are available from OTSO@tel.vtt.fi



(8) MAKING BACKUPS OF OTSO (tar files)
--------------------------------------

------------------
Using ftp
------------------

  $ cd /usr/local/src/otso	-- root OTSO directory
  $ make backup			-- will create an exclude file 
				-- to eliminate .o's .a's big executables, etc.

ftp otso-private.tar.Z to some other machine.

To produce an openly available OTSO release (file otso-public.tar.Z):

  $ cd /usr/local/src/otso
  $ make public-release	
 

------------------------------
Making a tape backup of OTSO
------------------------------

1. Local tape drive :
  $ cd /usr/local/src/otso	-- (or wherever OTSO lives on your machine)
  $ rm *.tar.*
  $ make backup
  $ cp otso-private.tar.Z /dev/rst8

2. Remote tape drive (e.g tapedrive at tel3  via ethernet) :
  $ cd /otso
  $ rm *.tar.*
  $ make backup
  $ cat otso-private.tar.Z | rsh tel3 dd of=/dev/rst8 bs=20b
   

NOTE FOR USERS OF TEL2:
-----------------------
  On tel2.tel.vtt.fi, the home directory above /otso (/home/users/otso),
which includes other relevant source trees besides OTSO (such as InterViews)
is backed up nightly (at 11:30 pm) by the Unix 'cron' process.  
  See /var/spool/cron/crontabs/jfr for more details on tel2, or contact jfr 
in case you need to retrieve something from the previous day's backup.  You 
can only retreive something within one day, as each night's backup 
overwrites the old one.



(9) DISK SPACE NEEDED FOR OTSO
-------------------------------

   The compressed tarfile should take up about 1-2 Mbytes, the uncompressed
version of tar.otso is about 6-10 Mbytes (depends if 'make clean' was
run or not on OTSO before the tarfile is made).  
   The complete OTSO directory structure after OTSO has been compiled
may need on the order of 50 Mbytes of hard disk.  (There is a lot of fat
in this number (.o's + demo executables + -g compilation of source files).
There is also a lot of duplication of directories in OTSO now, but hopefully
that should go away with a "merge" of various directories soon.
  You could probably compile most of OTSO with only 20 Mbytes of free 
hard disk.  

All figures above are for a Sun Sparcstation-1

* Your mileage may vary *


(10) C++ Debugger Hints
-----------------------
Currently we have compiled OTSO with OWC++ (AT&T Cfront 2.1+)
and HP C++ compiler.  These are some hints on using Sun dbx and
GNU gdb debuggers with compiled OTSO modules.

---------
   DBX
---------
SUN DBX: This should be used with AT&T Cfront based compilers on
Sun Workstations.  Your .dbxinit file could look something like this,
(where 'use' sets the path to the OTSO source code directories you
are interested in) :

  use . /otso/dvops /otso/include /otso/device/bsd /otso/include/device ~otso/owc/include
 button command quit
 button command dump
 alias break stop in
 toolenv srclines 18
 toolenv cmdlines 16
 toolenv font /usr/lib/fonts/fixedwidthfonts/cour.r.14

To see local variables inside of subroutines, use the 'dump' command of
dbx.  Local variable names are often preceded with __0 or __1, etc. This
is nothing to worry about.  You can then do a 'print' command on the variable:
Learn how to use the UNIX command 'nm' !!!!, so you can figure out where
to set breakpoints (e.g. nm -g channel.o | grep "run" => _run__7IstreamFv =>
dbx> break run__7IstreamFv).  Don't worry, you'll get the hang of it.
For more info : man dbxtool. 

DBX Hints:
- To redirect standard input from inside dbx :  run < filename
  or from shell prompt: dbxtool a.out < filename

------------
  GNU GDB 
------------
GDB: This should be used with GNU g++.  GDB is more user friendly than dbx
is.  It generally understands C++ naming conventions such as 
ClassName::memberName.  So, doing things like:
	break Istream::run
	print this->waiting
	etc.
are legal.  It is easiest to run GDB from inside an GNU EMACS editor.  This
is not strictly necessary though.  See more info in the files :
/usr/local/emacs/info/gdb.info*

GDB is perhaps more user friendly than DBX, but can only be used with
files compiled with g++.

Your .gdbinit file should look something like (directory specifies directories
of where your source code is located):
   directory /otso/dvops
   directory /otso/include
   directory /otso/asnsupport
   directory /otso/protocols/7/acs
   directory /otso/protocols/7/acs/generated
   directory /otso/device/bsd
   directory /home/users/jfr/gnu/libg++-1.37.0/src
   directory /home/users/jfr/gnu/libg++-1.37.0/g++-include
   directory /otso/include/device
   directory /otso/isoaddrs
   set prettyprint

GDB HINTS:
- It is difficult to set breakpoints inside of constuctors or destructors.
  You may have to temporarily create pseudo structor functions to help you
  set breakpoints.  Example:	

  class A {
  public:
   int x;
   A(int i) { x=i; }	// gdb won't let me set breakpoint in ctor A.
  };

	change to:

  class A {
  public:
   int x;
   tmpA(int i) { x=i; }	// we can set breakpoint (tmpA) here...
   A(int i)  {tmpA(i);} // ... but not here (A)
 };

- GDB can have problems displaying code that was inlined in .hxx files.


(11) CAVEATS
-------------

OTSO has been compiled at one time or another with all of these
platforms:
	- Sun SparcStation & Sun3 (SunOS 4.0+) 
		- ObjectWorks C++
		- Sun C++
		- It is preferable to use SunC if available you
		  will have less problems than with /bin/cc
	- MSDOS/Borland C++
	- GNU G++ (no longer supported - but perhaps with gcc 2.0)

	- BSD Unix is prefereable (select() call) to SysV, but
	  not mandatory.

	- HPUX (on an HP-750)

	- GNU's bison is preferable to yacc if available,
	  but 'lex' is prefereable to GNU's flex for now.

	-------------------------------------------------------
	Add more comments to this file as you see fit.  
	Many other directories also have README or *.doc files.
	-------------------------------------------------------

The current version cannot be compiled with all these without some 
modifications.

