%> do tex %F -l -d"-t a4"
%> do tex %F -l -l -d"-D" -p2

\documentstyle[12pt,times]{article}

\textwidth=16cm
\oddsidemargin=1cm
\evensidemargin=1cm
\textheight=22cm
\topmargin=0cm
\parindent=0mm
\parskip=4mm

\title{TOPO: Quick Reference	\\
	Front-End --- version 3R6}

\author{Jos{\'e} A. Ma{\~n}as			\\
        Tom{\'a}s de Miguel			\\
        Tom{\'a}s Robles			\\
        Joaqu{\'\i}n Salvachua		\\
        Gabriel Huecas			\\
        Marcelino Veiga			\\
					\\
        Dpt. Ingenier{\'\i}a Telem{\'a}tica	\\
        E.T.S.I. de Telecomunicaci{\'o}n	\\
        Univ. Polit{\'e}cnica de Madrid	\\
        E-28040 Madrid, SPAIN		\\
					\\
        {\tt <topo@dit.upm.es>}
        }

\date{18 January, 1995}

\pagestyle{myheadings}
\markright{Quick Reference -- Front End}

\begin{document}

\maketitle

\begin{abstract}
TOPO is a set of interoperating LOTOS tools grouped in several packages.
This one is basically the front-end, including the basic facilities
(mainly syntax and semantic checking).

This paper is a quick reference guide for users.
\end{abstract}

%\newpage
%\tableofcontents

\newpage

\section{Getting Started \ldots}
TOPO is a set of interoperating LOTOS tools grouped in several packages.
This one includes mainly syntax and semantic checking, and it is a
front-end for the other ones.

\begin{center}
\begin{tabular}{| r @{$\;\rightarrow\;$} l |}
  \hline
  spec\verb/.lot/       & The LOTOS specification                  \\
  \hline
\end{tabular}
\end{center}

There are basically two shell tools to drive the concrete components:	\\
\verb/toposet/: sets a compilation environment.	\\
\verb/topo/: coordinates compilation activities.

\section{Environment}
TOPO tools are accessed via a unique interface called \verb/topo/,
that is described in the next section.
There are some extra files that are needed at compile time.
The paths are coded relative to the value of a root directory
that is fixed at installation time.
However,
the paths may be affected by the settings of the following environment
variables:
\begin{center}
\begin{tabular}{| l | l | l |}
  \hline
  variable	& default	& used for			\\
  \hline
  TOPO		& user		& root for topo tools		\\
  \hline
  TOPOBIN	& \$TOPO/bin	& binaries to be executed	\\
  TOPOINC	& \$TOPO/lib	& files to be included		\\
  TOPOLIB	& \$TOPO/lib	& libraries to be loaded	\\
  TOPOSTDLIB	& \$TOPO/stdlib	& lotos libraries to be loaded	\\
  \hline
\end{tabular}
\end{center}

Variable TOPO is mandatory.

The other variables may be set only if needed.
If these variables are not found in the environment,
\verb/topo/ sets sensible values for them and,
only in the case of UNIX,
puts them in the environment for called tools to benefit from.
UNIX version sets as well the PATH.

In MS-DOS,
the user is expected to set environment as desired.
\verb/topo/ will just read it for internal purposes.

You may further influence the behaviour of concrete tools by setting
environment variables.
There is one variable for most tools in the package.
See the corresponding QuickReference document.

These are the relevant ones for the frontend

\begin{center}
\begin{tabular}{| l | l | l | l |}
  \hline
  variable	& tool	& help	& example		\\
  \hline
  TOPOF\_LFE	& lfe	& lfe -h & setenv TOPOF\_LFE -c	\\
  TOPOF\_LSA	& lsa	& lsa -h & setenv TOPOF\_LSA -f	\\
  \hline
\end{tabular}
\end{center}

%\newpage
\section{Context}
A number of compilation options may be specified in a context that is
stored a a separate file (spec.ctx). 
It is set by \verb/toposet/ and used by \verb/topo/.
It may be edited, but be very careful to strictly respect the format,
since there is no error checking at all!

\verb/toposet/ is expected to be used before \verb/topo/.
It stores the current context into SPEC.ctx.
If there is no such file, \verb/topo/ will use some default values.
\verb/toposet/, if executed without options, sets a default context:

\begin{verbatim}
      Library 
      Language C
      BehaviourName lbc
      DataName ldc
      BehaviourPieces 1
      DataPieces 1
      GladLibrary 
      Makefile 
\end{verbatim}

\begin{center}
\begin{tabular}{| r | l |}
  \hline
  \multicolumn{2}{| c |}{
    \rule[-3mm]{0mm}{6mm}
    \verb/toposet/ spec[\verb/.lot/] [options]
    } \\
  \hline
  \hline
  -help
    & One line help			\\
   -context F
   & Use file F.ctx as context		\\
  -make F
   & use F as makefile			\\
  -list
    & Print current context		\\
  -verbose
    & Echo activity			\\
  \hline
  -library L
    & \begin{minipage}[t]{12cm}
	IS8807 defines only one library of predefined data types,
	{\em THE Standard Library}.
	Nevertheless, TOPO permits to use a different library.

	Users may use their own libraries (any LOTOS specification).
      \end{minipage}                                        \\
  -nolibrary
    & Don't use any standard library	\\
  \hline
  -tname N
    & Root name for generated files (behaviour)	\\
  -tpieces N
    & Number of pieces to break C files down	\\
  \hline
  -dname N
    & Root name for generated files (data)	\\
  -dpieces N
    & Number of pieces to break C files down	\\
  \hline
  -glad G
    & \begin{minipage}[t]{12cm}
	GLAD is a tool to annotate data types,
	so that sensible code may be generated from them.
	Its role may range from selecting the naming of the LOTOS data
	objects when code is generated, to linking to external data
	types.

	The most basic use of GLAD allows to choose internal names for
	the operations when code is generated (cryptic but solid) \\
	\centerline{\verb|toposet spec -glad \$TOPOSTDLIB/internal.gld|} \\
	or to use the lexical values (nicer, but risky): \\
	\centerline{\verb|toposet spec -glad \$TOPOSTDLIB/lexical.gld|} 

	Users may specify their own annotation criteria.
      \end{minipage}                                        \\
  -noglad
  & do not use GLAD.				\\
  \hline
  -language L
    & Either C or Ada				\\
  \hline
\end{tabular}
\end{center}

%\newpage

The default is to use no standard library.
The following {\em standard} libraries are available:
\begin{center}
\begin{tabular}{| r @{$\;\rightarrow\;$} l |}
  \hline
  minimal       & Only {\em Booleans} (default)                 \\
  ditupm        & improved and extended IS library              \\
  is            & The standard library as in IS8807             \\
  is-neq        & idem, but with no equation			\\
  mod-is        & IS8807, modified by LotoSphere		\\
  mod-is-neq    & idem, but with no equation			\\
  bool\_nat     & Only {\em Booleans} and {\em Naturals}        \\
  \verb/<>/     & User defined at \verb:./<>.lot:               \\
  \hline
\end{tabular}
\end{center}

\verb/toposet/ plays an active role in removing intermediate
compilation results that are no longer valid or needed upon option
changing.
It revises as well the coherency of the standard library (if any),
and issues a warning if it is out of date and tries to regenerate it.

More precisely,
\verb/toposet/ tries to locate the desired library in the current
directory. 
If it founds ``\verb|./LIB.lot|'',
it checks if file ``\verb|./LIB.ls|'' exits and is newer,
issuing a warning if fails and trying to regenerate it.
Otherwise,
if there is a ``\verb|./LIB.ls|'', this is recorded as standard library
to use.
Lastly, if the previous checks fail,
\verb/toposet/ tries ``\verb|TOPOSTDLIB/LIB.ls|'';
if it is found, it is recorded as the standard library to use.
If all the previous ones fail,
\verb/toposet/ emits an error.

Later on,
\verb/topo/ will use the recorded library.
If there would be a ``\verb|./LIB.lot|'',
it will check consistency in every compilation,
to check for updates of the ``standard'' library.

\section{Actions}
\verb/topo/ is a collection of interoperating tools.
All of them may be accessed via a single interface
that coordinates them for effective interworking.
Command line flags are used to select the intended functionality.
This paragraph takes care of basic actions.
\begin{center}
\begin{tabular}{| r | l |}
  \hline
  \multicolumn{2}{| c |}{
    \rule[-3mm]{0mm}{6mm}
    \verb/topo/ spec[\verb/.lot/] [action]
    } \\
  \hline
  \hline
  -help
    & On line help          \\
  \hline
  -syntax
    & Just checks syntax conformance.        \\
  -s
    & \begin{minipage}[t]{12cm}
	Checks semantics conformance and builds user libraries of data
	types.
      \end{minipage}                                                \\
  \hline
  -listmake
    & shows internal makefile to control tool interoperation             \\
  -clean
    & Clean directory: intermediate files are removed.             \\
  -tidy
    & More drastic cleaning: all the generated files are removed.        \\
  \hline
  \hline
  default & -s     \\
  \hline
\end{tabular}
\end{center}

It is also possible to provide options to \verb/topo/.
\begin{center}
\begin{tabular}{| r | l |}
  \hline
  \multicolumn{2}{| c |}{
    \rule[-3mm]{0mm}{6mm}
    \verb/topo/ spec[\verb/.lot/] [topo\_options] [action]
    } \\
  \hline
  \hline
  -context F
    & Use file F.ctx as context		\\
  -verbose
    & Echo activity          \\
  \hline
\end{tabular}
\end{center}

And even to actions.
\begin{center}
\begin{tabular}{| r | l |}
  \hline
  \multicolumn{2}{| c |}{
    \rule[-3mm]{0mm}{6mm}
    \verb/topo/ spec[\verb/.lot/] [topo\_options] [action [action\_options]]
    } \\
  \hline
\end{tabular}
\end{center}

\end{document}
