stubgen man page

NAME

SYNOPSIS

stubgen [-hqrivgacd] [-e ext] [-{bfsn}] [infiles]  

DESCRIPTION

For example, suppose you have the following header file Point.h:

class Point {
public:
    Point(int x, int y);
    void addTo(const Point& other);

    int xValue, yValue;
};

Running "stubgen -n Point.h" would produce the following file:

/***********************************************
 * AUTHOR: Michael Radwin <mradwin>
 *   FILE: Point.cpp
 *   DATE: Mon Apr 20 17:39:05 1998
 *  DESCR: 
 ***********************************************/
#include "Point.h"
 
Point::Point(int x, int y) 
{
}
 
void
Point::addTo(const Point& other) 
{
}

If no input files are listed on the command line, stubgen reads from stdin and writes to stdout. This facility is provided so that code may be run through a preprocessor first. When doing stdio, the -q option is implicit.

For each input file, stubgen first looks for a code file by the same name in the working directory. If such a code file exists, it is first scanned for member function definitions. Then, stubgen runs through the corresponding header file, looking for prototypes that don't yet exist in the code file.

To compare two methods, stubgen compares the signature of the two methods. A signature is comprised of:

* The name of the class that the method belongs to.
* The name of the method.
* The list of arguments to the method.
* Whether the method is 'const' or not.
* The 'throw' declaration, if any.
* The template declaration, if any.

stubgen won't expand a method if:

* A method with the same signature exists in the code file.
* The method is inlined in the header file.
* The method is pure virtual.

By default, block method headers are generated (see METHOD HEADER STYLES below) in a code file. The corresponding header file will be #include'd in the code file. stubgen appends to whatever code file you have around, so it won't accidentally clobber your existing code.  

OPTIONS

-h

Display usage information.

-q

Quiet mode, no status information while generating code.

-r

Make RCS-style file headers, like the following example:

/*
 *  FILE: MyClass.cpp
 *  AUTH: Michael Radwin <mradwin>
 *
 *  DESC: 
 *
 *  DATE: Mon Apr 20 17:06:24 1998
 *   $Id: stubgen-man.html,v 1.7 2004/01/01 03:20:35 mradwin Exp $
 *
 *  $Log: stubgen-man.html,v $
 *  Revision 1.7  2004/01/01 03:20:35  mradwin
 *  foo
 *
 *  Revision 1.6  2000/09/13 18:02:14  mradwin
 *  radwin.org style
 *
 *  Revision 1.5  2000/04/12 23:30:22  mradwin
 *  search on navbar
 *
 *  Revision 1.4  1999/08/20 18:25:31  mradwin
 *  monospace ->
 *
 *  Revision 1.3  1999/07/01 03:16:05  mradwin
 *  fix tidy but ∓ -> &
 *
 *  Revision 1.2  1999/07/01 03:13:59  mradwin
 *  xhtml
 *
 *  Revision 1.1  1999/07/01 03:09:58  mradwin
 *  Initial revision
 *
 *
 */

-i

Don't insert a #include "MyClass.h" directive in MyClass.cpp

-v

Display version information.

-g

Generate dummy return statements for methods. For example:

int
MyClass::sampleFunc(char c1, char c2, char c3) 
{
    int dummy;

    return dummy;
}

For methods that return a pointer type (those that have a "*" in the return type), NULL will be returned instead of creating a dummy local variable. No dummy return value will be produced for methods that return a reference type (those that have a "&" in the return type), since they require an lvalue.

-a

Split function arguments over multiple lines, like the following example:

int
MyClass::sampleFunc(char c1,
                    char c2,
                    char c3) 
{
}

-e ext

Generate source files with extension '.ext' (default '.cpp').

-c

Use cerrs to display the name of the method within the body of the expanded method as below:

cerr << "MyClass::sampleFunc()" << endl;

This will insert a #include <iostream.h> in the code file.

-d

Use the dprintf macro to display the name of the method within the body of the expanded method as below:

dprintf(("MyClass::sampleFunc()\n"));

This will insert a #include <Debug.H> in the code file.

METHOD HEADER STYLES

-b

Block method headers (default):

/***********************************************
 *  Method: MyClass::sampleFunc()
 *  Params: char c1, char c2, char c3
 * Returns: int
 * Effects: 
 ***********************************************/

-f

Full method headers: like block, but less asterisks:

/*
 *  Method: MyClass::sampleFunc()
 *  Params: char c1, char c2, char c3
 * Returns: int
 * Effects: 
 */

-s

Simple method headers:

/*
 *  Method: MyClass::sampleFunc()
 *   Descr: 
 */

-n

No method headers.

ENVIRONMENT

If the variable STUBGEN_DOM is set in the environment, stubgen will append the user's domain to the account number the USER header comment, yielding the author's e-mail address.  

FILES

/tmp/$USER-stubgen.log

log file for debugging

Debug.[CH]

debugging routines for -d option

BUGS

Parse fails if a function has an implicit return value of 'int'. Workaround: explicitly declare the return type of the function.

Function pointer syntax is not parsed correctly.

Nested classes don't know about template declarations. In general, there is poor recognition of templated code.

Users can't define their own debugging code or method and file header styles.  

AUTHOR

stubgen also borrows code and design from:

Jutta Degener's 1995 ANSI C grammar (based on Jeff Lee's 1985 implementation).
ftp://ftp.uu.net/usenet/net.sources/ansi.c.grammar.Z
http://www.lysator.liu.se/c/ANSI-C-grammar-l.html
http://www.lysator.liu.se/c/ANSI-C-grammar-y.html

Graham D. Parrington's Stub Generator for the Arjuna project at the University of Newcastle upon Tyne.
http://arjuna.ncl.ac.uk/