TOPO	loTOs comPOiler
====	---------------

TOPO is a collection of tools to deal with LOTOS specifications.
LOTOS is a Formal Description Technique standardized by ISO (IS-8807)

TOPO is an evolving collection of tools,
where we keep adding new functionalities.
It is designed to be open for other to contribute,
but certainly lack of documentation makes this activity difficult.

Tools
-----
FronEnd:
    lfe		syntax analysis, and CAST builder
    lsa		static semantics analysis
    misc	miscellaneous: user interface, etc
    stdlib	standard(?) libraries

Miscellaneous:
    dtok	data token analysis
    adtxr	ADTs hierarchy and X-References
    lxref	X-REFerences
    pl		pretty printer
    rdtts	Real Data Type Test Specification
    drast	draws syntactic CAST (Coloured Abstract Syntax Tree)
    glad	General Lotos Abstract Data annotator

Compiler:
    om		behaviour machine (LBM)
    omdrast	draws LBM CAST (Coloured Abstract Syntax Tree)
    idle	data machine (LDM)

Interpreter:	of virtual machines code
    ldi		Lotos Data Interpreter - Library
    ildi	Symbolic Data Interpreter
    interlib    LBM interpreter (a library to build ...)
    ltg         behaviour test generation

l2c:		lotos to C
    d2c		data (LDM->C)
    omlbC	behaviour (LBM->C)
    m2c		C run time support

l2a:		lotos to Ada
    Adamisc	miscellaneous
    d2ada	data (LDM->Ada)
    omlbADA	behaviour (LBM->Ada)
    labra	Ada run time support

LITE:		interface to tools from the LotoSphere Project
    ast2cr

Dependencies
------------
The previous packages are interdependent.
In a "makefile" style, the dependencies may be stated as
	Miscellaneous:	FrontEnd
	Compiler:	FrontEnd
	Interpreter:	Compiler
	l2c:		Compiler
	l2a:		Compiler
	lite:		FrontEnd

Directories
-----------
You may not have everything,
so some of the pieces below may be missing.
However, if you get them, they are expected at the following places:

	bin		where binaries go into

	lib		where libraries go into

	stdlib		where LOTOS standard libraries go into

	src		sources
	src/lfe		Lotos Front-End: syntax + ast
	src/lsa		Lotos Semantics Analizer
	src/misc	miscellaneous
	src/stdlib	STandarD LIBraries

	src/dtok	LDM tokenizer
	src/adtxr	lotos ADTs X-References
	src/lxref	Lotos X-REFerences
	src/pl		pretty printer
	src/rdtts	Real Data Type Test Specification
	src/drast	draws syntactic CAST (Coloured Abstract Syntax Tree)

	src/glad	Data annotation
	src/om		Machine Independent Code gEnerator
	src/omdrast	draws LBM CAST (Coloured Abstract Syntax Tree)
	src/idle	Lotos Data Compiler

	src/ldi		Symbolic Data Interpreter (library)
	src/ildi	Symbolic Data Interpreter
	src/interlib	LBM interpreter (a library to build ...)
	src/ltg		behaviour test generation

	src/d2c		data (LOTOS -> C)
	src/omlbC	behaviour (LOTOS -> C)
	src/m2c		behaviour (C run time support)

	src/Adamisc	behaviour (LOTOS -> Ada)
	src/d2ada	data (LOTOS -> Ada)
	src/omlbADA	behaviour (LOTOS -> Ada)
	src/labra	behaviour (Ada run time support)

	src/ast2cr	generation of LITE Common Representation

	exs		some examples (plain LOTOS)
	exs/C		some examples (for the C compiler)
	exs/ADA		some examples (for the Ada compiler)

	doc		as much documentation as available
	doc/C		(really, less than it should :-(
	doc/ADA

Distribution
------------
The easiest way is to get the stuff already compiled;

* See directory Sun4/ for SPARC/SunOS 4.1
  (statically linked, stripped)
* See directory PC/ for MS-DOS
  (using djgpp, gnu port to msdos)

Then, there are files with the names shown above, that contain the
sources (format tar). Sources are not very readable, and are only
useful to recompile for a different system. If you need to recompile,
you will need EPS, an attributed grammars evaluator, that you may find
in
	host: ftp.dit.upm.es [138.4.2.10]
	directory: lotos/tools/TOPO_???/EPS_???/...

where ??? stands for the version, that may evolve.

Installation
------------
If you took the already compiled story, that's all.

Otherwise,
Read [, modify] and execute INSTALL.
./INSTALL

That should be all that is needed.
The rest should go automagically :-)
[It has been tried on
several flavours of Sun-3, Sun-4 (sparc); SunOS 4.0.3, 4.1
BSDi, ..., HP 9000/835 HP-UX 7.0 ..]

# After installation you may wish to clean up sources
./CLEANUP

# Or you may wish to remove sources,
rm -rf src

From now on,
it is a useful idea to have a few environment variables defined:

setenv TOPO `pwd`                    <===  MANDATORY
setenv TOPOBIN $TOPO/bin             <---  optional
setenv TOPOLIB $TOPO/lib             <---  optional
setenv TOPOINC $TOPO/lib             <---  optional
setenv TOPOSTDLIB $TOPO/stdlib       <---  optional

Now you may choose:
------------------
OPTION 1:
  Don't do anything now,
  but whenever you use TOPO
  remember to have $TOPOBIN/topo and $TOPOBIN/toposet in your $PATH
  and, if you are using the compiler stuff,
  remember to have TOPO... in your search paths
  for 'includes' (-I$TOPOINC)
  and 'libraries' (-L$TOPOLIB)

  Usually, it is enough to set an environment variable
setenv TOPO `pwd`
  and allow for the others to be set automagically.

OPTION 2:
  If you got LITE, and want to install the TOPO satellite,
  follow the instructions in
  	src/ast2cr/README

OPTION 3:
  You need your system manager (root) to fix some links to topo files,
  let's call ... to this directory (top level dir for topo)

  cd /usr/include
  ln -s TOPOINC/lotos.hh
  ln -s TOPOINC/kaos.hh

  cd /usr/local/lib           [HP: /usr/lib]
  ln -s TOPOLIB/libotos.a
  ln -s TOPOLIB/libkaos.a

  cd /usr/local
  ln -s TOPOBIN/topo
  ln -s TOPOBIN/toposet


To exercise TOPO, a shell script will probably help a lot.
  $TOPOBIN/topo

Try
  ...> topo -H                        for help
  ...> topo spec                      to check spec semantically

In order to set options, try
  ...> toposet -H                     for help
  ...> toposet spec -list             to see default options
  ...> toposet spec options ...       to set specific options

Integration with LITE
---------------------
If you are using TOPO with LITE (LotoSphere results),
or using it with SMILE (a symbolic simulator),
please read
	src/ast2cr/README
for installation details.

Problems and Bugs
-----------------

If you discover any bug,
or if you may suggest any improvements,
or if even you add something that you regard useful for other users,
or if just there is something that doesn't work,
or if you cannot find the way to make it run,
...

please, contact us at

	Lotos Tools Development Team <topo@dit.upm.es>
