
Supplementary Chipmunk Tools 
----------------------------

In addition to the four major tools (Log, Wol, View, and Until), and
the original smaller tools (Netcmp, Mosis) the Chipmunk tools include
a number of smaller programs. Some date back to the pre-Unix era,
while others have been donated to the project by new Chipmunk users.
These tools include:

Spc-tools 
   These tools are filter programs for use with SPICE output from the
   Log program Logspc. Written By Harold Levy, Caltech. 
Sctomat 
   This tool, written by Michael Godfrey, converts SCOPE output files
   in Log to a format readable by MATLAB. 
Conscripts 
   These shell scripts support transfer of CIF between Magic and Wol, so
   that chips designed using Wol and Wolcomp and be DRC'ed with
   Magic. 
Cleancif 
   Cleancif does comment removal for Wol CIF: some programs don't
   deal well with Wol-style commenting. 
Boxify 
   Boxify is a simple filter for cleaning up quite general CIF and make it
   readable for Wol, written by Tor Sverre Lande. 

This tar file contains separate directories for each of the tools
above. Since these tools have been contributed by users, the licensing
restrictions for each tool is unique: see the subdirectories for details.

If you have a web browser, the best way to learn about these tools and
how to install them is to pick up the latest version of the webdoc Web
pages (webdocX.XX.tar.gz, where X.XX is a version number) from the
same place you picked up this file. Once you have this Web tree
untarred, point your Web browser (examples of Web browsers include
Mosaic, Lynx, Netscape, and tkWWW) to

webdoc/describe/supplement.html

for a description of the tools

webdoc/document/other/index.html

for user documentation of the tools, and

webdoc/compile/util.html

for compilation instructions for each tool.

The rest of this file is written assuming that you don't have access
to a Web browser -- all text is copied from webdoc pages
verbatim. I'll do my best to keep this file up to date, but the Web
tree is now the primary documentation for all aspects of the Chipmunk
system.

-------

Platforms and Requirements 
--------------------------

The supplementary tools require an ANSI c compiler (typically GCC) and
X11 (R4, R5, or R6). Since all are text-based, graphics support is not
an issue.
 
Since this is the first release of these utilities, many of these
tools have not been checked on all the platforms listed below, which
are the current supported platforms for Chipmunk. However, all have
been compiled on HP 700 series machines, and many have been compiled
on many of the platforms below:

   AmigaOS. Requires ADE X or AmiWin X11. 
   Apple Macintosh, AU/X. 
   DEC MIPS-based DECstations 
   HP Series 300/400, HPUX. 
   HP Series 700, HPUX. The HP-supplied cc, with extra-cost
   ANSI option, will also compile Chipmunk. 
   IBM PC and Compatibles, FreeBSD. 
   IBM PC and Compatibles, Linux, Slackware. 
   IBM PC and Compatibles, OS/2. Press here for details. 
   IBM RS/6000. The IBM xlc compiler is known to compile
   Chipmunk; gcc has not been tested. 
   SGI. Chipmunk known to work on Indigo and Challenge, no
   others were tested. The SGI cc is recommended. 
   Sun SPARC, Solaris 1.X (SunOS 4.X). 
   Sun SPARC, Solaris 2.X (SunOS 5.X). 

To get these tools running, first bring over a copy of psys-Y.YY.tar.Z
(where Y.YY is a version number), available at the same place this
file was found. Untar and make psys per instructions in the package.
After psys is installed, you can start to install the tools. The major
reason to psys before the tools is to get various bin and lib
directories made, since these tools don't directly use psys. If these
tools are the only Chipmunk tool you need, you should be able to hack
your way past any problems you'll find by not having psys installed.

Compiling the Supplementary Tools 
---------------------------------

This document assumes that you have successfully compiled the Psys 
libraries. This document also assumes that you have uncompressed
and untarred the Util file that holds the supplementary tools, and
installed it in the chipmunk directory.

The 1995 release is the first release of the supplementary toolkit.
Many of the tools were contributed by the Chipmunk tool users, who
may have only used them on a few platforms. As a result, compiling
and running these tools may not be as smooth as the other Chipmunk
tools. 

Begin by descending to the util directory. Then cd to each
subdirectory, and edit the file Makefile, and make any necessary
changes. Comments in the Makefile will guide you through these
changes; the changes are labeled with the markers (1), (2), (3),
etc. Once these changes are made in each directory, return to util/
and execute the command 

make install 

If things are working correctly, a long series of compilations,
linkings, and file movements should occur without error. This will
create the programs and shell scripts in the directory 
chipmunk/bin/. 

To learn more about the Supplementary tools, see the user
documentation. 

If you have problems compiling or using these tools, I'd be happy to
offer suggestions; Send email to lazzaro@cs.berkeley.edu and include the
following information.

   Complete machine configuration, including machine type, OS
   revision, compilers, and X servers. 

   A listing of the output from the failed compilation process, or
   any messages printed by a Chipmunk program or the OS or X
   when an error occurs.
 
   Details of any changes you have made to the distribution before
   this compilation. 

   The effects of following any advice given in the compilation
   instructions. 

For many types of problems, I'll probably refer you to the
contributing author for the tool.

Documentation for Supplementary Tools 
-------------------------------------

All of the documentation for using these tools is included in the webdoc
package. See:

webdoc/document/other/index.html

----

If using the Webdoc documention isn't practical, here are tips for
each tool:

boxify     : Look at the man page boxify/boxify.1
Cleancif   : Look at cleancif/README
Conscripts : Look at conscripts/README
sctomat    : Look at sctomat/doc/scope_to_mat.ps
spc-tools  : Look at spc-tools/README

