\manpage{Manpage for the stub generator}{stablegen}{1}

\section{Name}
\bf{stablegen} -- Generate stubs for stable objects.
\section{Syntax}
\begin{description}
\item{\bf{stablegen}} [\bf{-i} \it{Interfaces}] [\bf{-o} \it{StableObjectIntf}]
[\bf{-im} \it{StableObjectImpl}] [\bf{-rm} \it{RepModule}] [options]
\end{description}

\section{Description}
The program \it{stablegen} generates stubs for Modula-3 stable 
objects. Stable objects are Modula-3 objects whose state 
is backed up on the disk or other stable medium, so that it 
will survive program crashes.  

It is not intended to be used from the command line. Use
\it{m3build} and the quake macros \it{stableobj} and \it{Stableobj}
instead to run the stub generator (see the m3build section
below).

The command
\begin{verbatim}
    stablegen -i Data -o Data -im Impl -rm Rep
\end{verbatim}
writes into ``\it{Impl}\tt{.m3}'' an implementation of the generic
interface ``\tt{Stable(Data)}''. See this generic interface for the
specifications of the methods and procedures implemented by
\it{stablegen}.  Thus \it{Data} should be the name of an interface and
\it{Data}.T should name an object type; \it{stablegen} implements a
stable version of \it{Data}.T and writes the implementation to
``\it{Impl}\tt{.m3}''.  \it{Impl} defaults to the objects interface
name as stated in the -o option with ``\tt{Stable}'' prepended.  All
interfaces that contain revealations of \it{Data}.T must be listed
after the -i parameter.  The first interface of the list must contain the
most specific supertype of \it{Data}.T. In most cases this will be \it{Data}
itself. But if \it{Data} does not state any more specific supertyp of 
\it{Data}.T than \tt{ROOT}, the interface listet after the -i will be the
one containing the most specific revealation.

To complete your program, you
should include in the file ``\it{Impl}\tt{.i3}'' the text
\begin{verbatim}
    INTERFACE Impl = Stable(Data) END Impl.
\end{verbatim}
The implementation of stable objects consists of two modules.
The first is generated by \it{stablegen}, the second is an
instantiation of the generic module ``\tt{StableRep}''. The name of
this second module is stated after the -rm option. It
defaults to the name of the generated implementation \it{Impl}
with ``\tt{Rep}'' appended. If both module names are defaulted,
``\tt{Stable}\it{Data}\tt{Rep}'' will be used for the generic's instantiation.
So in the file ``\it{Rep}\tt{.i3}'' you will
need the text
\begin{verbatim}
    INTERFACE Rep = StableRep(Impl) END Rep.
\end{verbatim}
And the file ``\it{Rep}\tt{.m3}'' looks like
\begin{verbatim}
    MODULE Rep = StableRep(Impl) END REP.
\end{verbatim}
The m3build macros will also generate all these files (see below). 

\section{Classifying the methods}
The interface ``\it{Data}\tt{.i3}'' presented to the stub generator
must contain a pragma that lists all methods of \it{Data}.T that modify
the state of the object.  The pragma has the form
\begin{verbatim}
    <* STABLE UPDATE METHODS m_1, ..., m_k *>
\end{verbatim}
where the m's are the names of the update methods of \it{Data}.T.  The
stub generator will override these methods to log their arguments
before calling the corresponding method of the supertype.  The stub
generator will not override the other methods of \it{Data}.T; the
stable object will simply inherit them from its supertype.  The pragma
may appear more than once (the list stated in the second pragma will
be appended to those methods already mentioned).  You may use \tt{ANY}
instead of a list of methods in which case all methods of the object
are treated as update methods.

\section{Options}
The stub generator is based on the Modula 3 toolkit, therefore the
other options defined by the toolkit are available.  See the manpage
for \it{m3fe} for a list of these options.  In particular, it is
possible to set the search path used by the stub generator with the
\tt{-T}\it{x} option, where \it{x} is the name of a map file
generated by m3build.  The name of the map file associated with
package \it{P} and build directory \it{B} is \tt{P/B/.M3IMPORTS}. It is also
possible to set a specific search path with the \tt{-D} option, though
this is usually more trouble than it is worth.

You may use -help instead of any other options to get a list of available
options.

\section{Restrictions}
As mentioned before, not all types \it{Data}.T are valid for stub generation.
The following restrictions apply.  The stub generator will not 
produce stubs for types that violate any of the restrictions. 
\begin{enumerate}
\item	No argument to an update method may be of type \tt{PROCEDURE} 
	or have a component of type \tt{PROCEDURE}.
\item	The name of the update methods listed in the \tt{STABLE UPDATE METHODS}
	pragma must not conflict with the names of the stable object
	methods as declared in \tt{Stable.ig}.
\end{enumerate}
The marshaling of parameters to update methods is performed as 
for network objects, as specified in the documentation for \it{stubgen}. 

\section{Generating stubs using m3build}
Currently the macros described here only support the defaults
for the filenames of the generated module and the instatiated
generic part of the implementation.

It is possible to manage stub generation using \it{m3build}.  You must
put the following line in your \it{m3makefile}, prior to any
occurrences of one of the macros:
\begin{verbatim}
    import("stable")
\end{verbatim}
To state that an interface \it{Data} contains a stable object use one
of the macros:
\begin{verbatim}
    stableobj("Data", [])
    Stableobj("Data", [])
\end{verbatim}
(\it{Stableobj} sets the visability of the stable object's interface
to visible, \it{stableobj} to hidden) which generates stubs for
\it{Data}.T, storing them in ``\tt{Stable}\it{Data}\tt{.m3}''. It
generate the instatiation of \tt{Stable.ig} in
``\tt{Stable}\it{Data}\tt{.i3}'' and the instatiation of the generic
part of the implementation (\tt{StableRep}) in
``\tt{Stable}\it{Data}\tt{Rep.i3}'' and
``\tt{Stable}\it{Data}\tt{Rep.i3}''. It also arranges for the
generated stubs to be compiled and linked into the program.

The second parameter of the macros is a list of interfaces that
\it{Data} depends on. The first in the list must be the interface
containing the most specific exported revealation of \it{Data}.T.
The following interface names are only used to trigger \it{stablegen}
correctly. If one of those interfaces are changed, \it{stablegen}
will be run again on the next call of \it{m3build}.

If the second parameter is the empty list, it is assumed that
``\it{Data}\tt{.i3}'' is the only interface containing definitions
necessary for \it{Data}.T.

The rules for importing interfaces during stub generation are 
the same as those for compilation under \it{m3build}. See the \it{m3build} 
manpage for further detail.

\section{Copyright}
\begin{flushleft}
Copyright (C) 1994, Digital Equipment Corporation.\newline
Distributed only by permission.\newline

Last modified on Thu Jan 19 14:28:03 PST 1995 by kalsow  
     modified on Tue Sep 27 11:52:22 PDT 1994 by weich   
\end{flushleft}
