stubgen README file
Michael John Radwin
$Id: README,v 1.1 2002-09-21 14:12:12 ocoursiere Exp $


Description
-----------
Welcome to stubgen version 2.05 (build 1086).

stubgen is a C++ development tool that keeps code files in sync with
their associated headers.  When it finds a member function declaration
in a header file that doesn't have a corresponding implementation, it
creates an empty skeleton with descriptive comment headers.  stubgen has
several options, but see the "Brief Example" section below for an idea
of what it can do.

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.


Brief 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 -s Point.h" would produce the following file:
 
          /***********************************************
           * AUTHOR: Michael John Radwin <mjr@acm.org>
           *   FILE: Point.cpp
           *   DATE: Mon Apr 20 17:39:05 1998
           *  DESCR:
           ***********************************************/
          #include "Point.h"
 
          /*
           *  Method: Point::Point()
           *   Descr:
           */
          Point::Point(int x, int y)
          {
          }
 
          /*
           *  Method: Point::addTo()
           *   Descr:
           */
          void
          Point::addTo(const Point& other)
          {
          }


Supported Platforms
-------------------
I've successfully built stubgen on the following platforms, using the
GNU tools make, gcc, bison, and flex:

    SPARC Solaris (2.5 and 2.6)
    SunOS 4.1.3
    SGI IRIX 5.3
    RS6000 AIX 3.2
    MS Windows NT 4.0 (using GNU bison/flex and MSVC++ 5.0)


Home Page
---------
Check out the stubgen home page and download the current source code at:

    http://www.radwin.org/michael/projects/stubgen/


Files
-----
The following files are included in this distribution:

    COPYING        -  the GNU general public license
    ChangeLog      -  a listing of changes made on various versions.
    Makefile       -  a makefile for building stubgen on unix
    README         -  this file
    etc/           -  debugging routines for use with the -d option
    getopt.[ch]    -  GNU getopts (for Win32)
    lexer.l        -  flex source, generates tokens
    main.c         -  code generation routines
    parser.y       -  yacc source, parses header and code files
    pathname.[ch]  -  dirname() and basename() routines
    stubgen.1      -  nroff-able man page
    table.[ch]     -  data structures used in parsing
    util.[ch]      -  utilities, logging routines, used in parsing
    test/          -  test header files for stubgen
    win32/         -  MS Visual C++ 5.0 project (Win32 console app)


Building
--------
1. ensure that your system has 'flex' installed.
2. ensure that your system has 'yacc', 'byacc', or 'bison' installed.
3. edit 'Makefile' and pick your favorite CC, LEX, YACC, LFLAGS and CFLAGS
4. run 'make'

We assume that flex, bison, and cc/gcc are in your path.

For win32, there's no need to build.  You'll find stubgen.exe in the
directory .\win32.


Installing
----------
There is no fancy installation procedure.  Since the binary doesn't
depend on any other files, copy it to /usr/local/bin or wherever you
choose.  You may wish to copy stubgen.1 to /usr/local/man/man1 or some
similar directory.


Acknowledgments
----------------
stubgen borrows code 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/


Copyright
---------
stubgen is Copyright (c) 1996-1998 Michael John Radwin, under the terms
of the GNU General Public License. See COPYING for more.
