Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
stablegen(1)		    General Commands Manual		  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. Sta-
       ble  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	gener-
       ator (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	 "Sta-
       ble(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; stable-
       gen 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 re-
       vealations  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 re-
       vealation.

       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	imple-
       mentation Impl with "Rep" appended. If both module names	are defaulted,
       "StableDataRep" 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  -Tx  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	avail-
       able options.

Restrictions
       As  mentioned  before,  not all types Data.T are	valid for stub genera-
       tion.  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	 METH-
	     ODS       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 net-
       work 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 vis-
       ible,  stableobj	 to  hidden) which generates stubs for Data.T, storing
       them in "StableData.m3".	It generate the	instatiation of	 Stable.ig  in
       "StableData.i3"	and the	instatiation of	the generic part of the	imple-
       mentation (StableRep) in	"StableDataRep.i3" and "StableDataRep.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 in-
       terfaces	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

								  stablegen(1)

Name | Syntax | Description | Classifying the methods | Options | Restrictions | Generating stubs using m3build | Copyright

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=stablegen&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help