---
name: "stablegen"
section: "1"
platform: "linux"
package: "pm3-extra"
version: "1.1.15-1"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/stablegen"
---

# stablegen(1)

## Name

**stablegen** -- Generate stubs for stable objects.

## Syntax

- **stablegen**

  \[**-i** *Interfaces*\] \[**-o** *StableObjectIntf*\] \[**-im** *StableObjectImpl*\] \[**-rm** *RepModule*\] \[options\]

## Description

The program *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 *m3build* and the quake macros *stableobj* and *Stableobj* instead to run the stub generator (see the m3build section below).

The command

```
    stablegen -i Data -o Data -im Impl -rm Rep
```

writes into “*Impl*.m3” an implementation of the generic interface “Stable(Data)”. See this generic interface for the specifications of the methods and procedures implemented by *stablegen*.  Thus *Data* should be the name of an interface and *Data*.T should name an object type; *stablegen* implements a stable version of *Data*.T and writes the implementation to “*Impl*.m3”.  *Impl* defaults to the objects interface name as stated in the -o option with “Stable” prepended.  All interfaces that contain revealations of *Data*.T must be listed after the -i parameter.  The first interface of the list must contain the most specific supertype of *Data*.T. In most cases this will be *Data* itself. But if *Data* does not state any more specific supertyp of  *Data*.T than 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 “*Impl*.i3” the text

```
    INTERFACE Impl = Stable(Data) END Impl.
```

The implementation of stable objects consists of two modules. The first is generated by *stablegen*, the second is an instantiation of the generic module “StableRep”. The name of this second module is stated after the -rm option. It defaults to the name of the generated implementation *Impl* with “Rep” appended. If both module names are defaulted, “Stable*Data*Rep” will be used for the generic's instantiation. So in the file “*Rep*.i3” you will need the text

```
    INTERFACE Rep = StableRep(Impl) END Rep.
```

And the file “*Rep*.m3” looks like

```
    MODULE Rep = StableRep(Impl) END REP.
```

The m3build macros will also generate all these files (see below).

## Classifying the methods

The interface “*Data*.i3” presented to the stub generator must contain a pragma that lists all methods of *Data*.T that modify the state of the object.  The pragma has the form

```
    <* STABLE UPDATE METHODS m_1, ..., m_k *>
```

where the m's are the names of the update methods of *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 *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 ANY instead of a list of methods in which case all methods of the object are treated as update methods.

## 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 *m3fe* for a list of these options.  In particular, it is possible to set the search path used by the stub generator with the -T*x* option, where *x* is the name of a map file generated by m3build.  The name of the map file associated with package *P* and build directory *B* is P/B/.M3IMPORTS. It is also possible to set a specific search path with the -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.

## Restrictions

As mentioned before, not all types *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.

- 1\.

  No argument to an update method may be of type PROCEDURE \
   	or have a component of type PROCEDURE.

- 2\.

  The name of the update methods listed in the STABLE UPDATE METHODS\
   	pragma must not conflict with the names of the stable object\
   	methods as declared in Stable.ig.

The marshaling of parameters to update methods is performed as  for network objects, as specified in the documentation for *stubgen*.

## 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 *m3build*.  You must put the following line in your *m3makefile*, prior to any occurrences of one of the macros:

```
    import("stable")
```

To state that an interface *Data* contains a stable object use one of the macros:

```
    stableobj("Data", [])
    Stableobj("Data", [])
```

(*Stableobj* sets the visability of the stable object's interface to visible, *stableobj* to hidden) which generates stubs for *Data*.T, storing them in “Stable*Data*.m3”. It generate the instatiation of Stable.ig in “Stable*Data*.i3” and the instatiation of the generic part of the implementation (StableRep) in “Stable*Data*Rep.i3” and “Stable*Data*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 *Data* depends on. The first in the list must be the interface containing the most specific exported revealation of *Data*.T. The following interface names are only used to trigger *stablegen* correctly. If one of those interfaces are changed, *stablegen* will be run again on the next call of *m3build*.

If the second parameter is the empty list, it is assumed that “*Data*.i3” is the only interface containing definitions necessary for *Data*.T.

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

## Copyright

Copyright (C) 1994, Digital Equipment Corporation.\
 Distributed only by permission.\

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