Maintenance Utilities
 

 


next up previous contents
Next: Compiling VIS and Up: No Title Previous: An Example Package

Maintenance Utilities

 

The VIS environment currently has two maintanance utilities; extdoc, which extracts documentation from source code, and extproto, which automatically inserts function declarations within header and source files.

VIS uses the Revision Control System, or RCS, for version control.

extproto

 

Extproto analyzes source code and inserts automatically-generated function declarations into the appropriate source and header files. It requires a package that follows the conventions in Chapters 2 and 3.

When run on a header file named package.h (the external header file), it looks for externally-visible functions (i.e., those with the prefix Package_) and places them between the /**AutomaticStart*** and /**AutomaticEnd*** comments within the header file described in Chapter 2.

When run on a header file named packageInt.h (the internal header file), it looks for internally-visible functions (i.e., those with the prefix Package) and places them between the automatic comments within the file.

When run on a C source file, it looks for static functions and places them between the /**AutomaticStart** and /**AutomaticEnd comments.

For example, if extproto is run on the rng example described in the previous section, then it will add lines to the files in the package as shown.

  • To extract the static functions in rngUtil.c, 
     
% extproto rngUtil.c
processing rngUtil.c
%
    which adds the following lines to rngUtil.c: 

    /**AutomaticStart*************************************************************/

/*---------------------------------------------------------------------------*/
/* Static function prototypes                                                */
/*---------------------------------------------------------------------------*/

static boolean RangeOverlap(Rng_Range_t *range1, Rng_Range_t *range2);

/**AutomaticEnd***************************************************************/

  • To extract the internal and external function prototypes into the appropriate headers, 
     
% extproto *.h
processing rng.h
processing rngIntUtil.c
processing rngUtil.c
Writing rng.h, the external header
processing rngInt.h
processing rngIntUtil.c
processing rngUtil.c
Writing rngInt.h, the internal header
%
    which adds the following lines to rng.h, the external header 
    /**AutomaticStart*************************************************************/

/*---------------------------------------------------------------------------*/
/* Function prototypes                                                       */
/*---------------------------------------------------------------------------*/

EXTERN Rng_Range_t* Rng_RangeAlloc();
EXTERN void Rng_RangeFree(Rng_Range_t *range);
EXTERN Rng_Range_t* Rng_RangeOrWithRange(Rng_Range_t* range1,
  Rng_Range_t* range2);

/**AutomaticEnd***************************************************************/
    and the the following lines to rngInt.h, the internal header 
    /**AutomaticStart*************************************************************/

/*---------------------------------------------------------------------------*/
/* Function prototypes                                                       */
/*---------------------------------------------------------------------------*/

EXTERN boolean RngRangeIsOK(Rng_Range_t *range);

/**AutomaticEnd***************************************************************/

extdoc

 

Extdoc extracts documentation from packages that follow the conventions in Chapters 2 and 3. It can write both simple text files, or HTML for the World Wide Web.

For example, running extdoc on the rng package of Chapter 4 in text-producing mode, 

% extdoc --text rng
processing rngRangeIntUtil.c
processing rngRangeUtil.c
processing rngInt.h
processing rng.h
writing rngDoc.txt
%
creates a file rngDoc.txt that contains 
The rng package

This package deals with functions that are used to manipulate   the range
(Rng_Range_t) data structure.

Gitanjali Swamy

**********************************************************************

Rng_RangeAlloc()               Allocates memory for a Rng_Range_t.

Rng_RangeFree()                Free memory associated with a Rng_Range_t.

Rng_RangeOrWithRange()         OR two ranges.

Rng_RangeReadBegin()           Return the beginning of the range.

Rng_RangeReadEnd()             return the end of the range.

Rng_RangeSetBegin()            Set the beginning of the range.

Rng_RangeSetEnd()              Set the end of the range

**********************************************************************

The basic data structure in the range package is an   integer range. The
range is designated as {L,U}, where L is the lower limit of    the range, and
U is the upper limit of the range, and     includes all integers x, L =< x =<
U).

Rng_Range_t*
Rng_RangeAlloc(

)
  This functions takes no inputs, and when called allocates space for and
  returns a new Rng_Range_t.


void
Rng_RangeFree(
  Rng_Range_t *     range
)
  This function takes a Rng_Range_t* as input, and free the memory used by it.

  Side Effects: Rng_Range_t is no longer valid.

Rng_Range_t *
Rng_RangeOrWithRange(
  Rng_Range_t*      range1,
  Rng_Range_t*      range2
)
  Given two ranges, this function OR's together the two, and returns the
  result. If the two ranges do not overlap it returns with an error flag.



Rng_RangeReadBegin(
                    range
)
  Given a range {L,U}, this returns the beginning value L of the range.



Rng_RangeReadEnd(
                    range
)
  Given a range {L,U}, this returns the ending value U of the range.



Rng_RangeSetBegin(
                    range,
                    val
)
  Given a range and a value L, this sets the beginning value L of the range.

  Side Effects: There original beginning value of the range is lost.


Rng_RangeSetEnd(
                    range,
                    val
)
  Given a range and a value L, this sets the end value L of the range.

  Side Effects: There original ending value of the range is lost.

RCS

RCS is a file-based revision control system used within VIS.

To use RCS within VIS,

  1. Create a directory ~/vis/common/src.

  2. Define the environment variables VIS and VIS_USER_DIR: 

    % setenv VIS /projects/vis/vis
% setenv VIS_USER_DIR ~/vis/common/src

  3. To put a new package pkg residing in $VIS/common/src/pkg under RCS control, 

    % mkdir $VIS/common/src/pkg/RCS
% chmod 775 !$
% echo "VIS: Initial version" > /tmp/rcsText
% cd $VIS/common/src/pkg
% gmake RCSFLAGS='-t/tmp/rcsText' rcs_ci

The files in the packages in $VIS/common/src are not writable. All changes must be made through RCS, using the working area $VIS_USER_DIR.

The Makefile in each package has 5 RCS commands defined. These commands operate on all the files of the package under RCS control, namely RCSFILES = $(SRC) $(HDR) $(MISC) $(LFILE) $(YFILE) as defined in the Makefile.

To use the commands on package pkg, first create directory pkg in
$VIS_USER_DIR. Then, you can execute package level RCS commands from either the Makefile at $VIS/common/src/pkg, or the Makefile at $VIS_USER_DIR/pkg (if you already have a Makefile there). The commands are as follows:

  • gmake rcs_co

    Check out a copy of RCSFILES and put them at $VIS_USER_DIR/pkg. This operation will fail if another user has these files checked out. In this case, negotiate with this user to determine when you can have access. To keep things simple, we don't want to have multiple branches of development.

  • gmake rcs_ci

    Check in the RCSFILES in $VIS_USER_DIR/pkg into
    $VIS/common/src/pkg/RCS. This leaves a copy of the new files at $VIS/common/src/pkg. For any file that has changed, you will be prompted to supply a log message (terminated by ctrl-D or a period on a line by itself). For files that have not changed, the check-in does nothing. This operation causes the protection of RCSFILES in $VIS_USER_DIR/pkg to be changed to read only. You can choose to remove (rm) these files, or leave them there. If you make rcs_co again, these files will be overwritten and the protection will be changed to allow writing.

  • gmake rcs_diff

    For each RCSFILE, performs a diff between the corresponding files in
    $VIS_USER_DIR/pkg and $VIS/common/src/pkg/RCS. This is useful to remind yourself what changes (if any) you have made.

  • gmake rcs_ident

    For each RCSFILE in $VIS/common/src/pkg, searches the file for RCS identifiers, like $Id. This is useful to see who most recently modified a file, and when this was done.

  • gmake rcs_status

    For each RCSFILE in $VIS/common/src/pkg currently checked out, this tells you who has the file checked out. This is useful to determine who is modifying which files.

The first two commands do all the work. The last three are only for informational purposes; you can't do any harm by using them.

More experienced RCS users can specify options to the RCS commands by setting the RCSFLAGS in the gmake invocation (e.g., gmake RCSFLAGS='-b -i' rcs_diff).

RCS commands can be performed from the Makefile at $VIS/common/src:

  • gmake rcs_ident: Run make rcs_ident on each package.

  • gmake rcs_status: Run make rcs_status on each package.

For files not part of code packages but under RCS control (e.g., src/Makefile, ext/*), you must use RCS commands on individual files; there is no Makefile support for them.


next up previous contents
Next: Compiling VIS and Up: No Title Previous: An Example Package


Tom Shiple
Fri May 10 17:19:47 PDT 1996
Contact 
©2002-2018 U.C. Regents