
This is psys, a library that most of the Chipmunk tools use for low-level
operations. If you have a web browser, the best way to learn about what
Psys is and how to install it 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/index.html for the home
page of the Chipmunk tools, and to webdoc/compile/compile.html for
compilation instructions.

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.

---------

This is psys, the p-system emulation libraries for the caltech tools.
Psys was written by Dave Gillespie, Rick Koshi, Glenn Gribble,
Adam Greenblatt, and Maryann Maher and is maintained under Unix by Dave
Gillespie and John Lazzaro.  Psys is distributed under the GNU General
Public License; see file COPYING in this directory for more
information.

Psys's purpose in life is to support the graphical tools in the
Caltech CAD distribution: analog, wol, view, and until. These libraries
must be installed before attempting to install these tools.

Platforms and Requirements 

The Chipmunk tools require an ANSI c compiler (typically GCC) and X11
(R4, R5, or R6).  Monochrome, 8-bit, 16-bit, and 24-bit per pixel
color displays are supported; however, 16-bit and 24-bit color modes
have only been tested on PC platforms (X11 under Linux and OS/2). An
HTML browser (like Mosaic or Lynx or Netscape) is also necessary to
access the Chipmunk documentation.

These are the currently supported platforms, with details of
platform-specific requirements: 

   AmigaOS. Requires ADE X or AmiWin X11. 
   Apple Macintosh, OS/X, AU/X, and MachTen
   DEC MIPS-based DECstations 
   DEC Linux/Alpha. OSF/1(Digital Unix) not tested, but may also work. 
   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/x86. 
   IBM RS/6000. The IBM xlc compiler is known to compile
   Chipmunk; gcc has not been tested. 
   SGI, Irix 5.2/5.3, cc or gcc. 
   Sun SPARC, Solaris 1.X (SunOS 4.X). 
   Sun SPARC, Solaris 2.X (SunOS 5.X). 
   IBM PC and Compatibles, OS/2. 

     OS/2 Requirements 

     Only the Log system (diglog, analog and loged) is ported. Here are the
     requirements for Log:

     WARP Connect.
 
     The PMX server (The X Window System for OS/2) About $140 US, availible
     from Indelible Blue, 800-776-8284. 

     The icc compiler, and nmake. Not known if gcc will work also, please
     let me know if you try gcc. 


Binary distributions have been built by third-parties for the
following architectures. Contact the authors for additional
information.

IBM PC-Compatibles, MS-DOS. Luigi Rizzo's group at the Universita' di
Pisa, Italy, has been working on an MS-DOS port of analog. Compiled
with djgpp, uses xlibemu and fvwm to provide an interface similar to a
virtual window manager under X with Motif-like widgets. See his home
page for current status; there may be an early-alpha version of a
binary available for evaluation (see "Materiale didattico" section).
(http://www.iet.unipi.it/~luigi/) 

Amiga. Marco Gigante (se62@galileo.iet.unipi.it) has created a binary
distribution for the Amiga, which uses the ADE X or AmiWin X
server. These binaries are available on the Aminet server
(ftp://ftp.wustl.edu/pub/aminet/misc/sci/), for several hardware
configurations. Binary filesets ChipMunk*.lha, log*.lha, view*.lha,
until*.lha, wol*.lha, contain the distributions for Chipmunk, Log,
View, Until, and Wol respectively.

If your configuration is different than the ones described above, only
take the package if you feel confident in your C/Unix abilities to do
the porting required. If you do successfully port to a new
architecture or OS, send us the changes required, and we will
incorporate your port in the next release of the chipmunk tools.

Absent from this list are the following popular platforms. 

IBM PC-Compatibles, Windows NT No ports are in progress, to my knowledge. 

IBM PC-Compatibles, NextStep. No ports are in progress, to my knowledge. 

Apple Macintosh, MacOS. No ports are in progress, to my knowledge. However,
MachTen does run as a process on top of MacOS. 



			INSTALLING PSYS
			---------- ----

Chipmunk System Setup 
----------------------

The first part of setting up a Chipmunk system is to choose a place in
your directory tree for the tools. Chipmunk can be installed in a user
directory; you do not need to install it in a public place like 
/usr/local/. Once you've decided on a place, create a directory
called chipmunk. Now move all the Chipmunk tar files to the 
chipmunk directory, and uncompress them using gzip if necessary.

Next, un-tar the files using the tar command, with the options
appropriate for your system. For most Unix systems, the command 

tar -xf file.tar 

untars the file file.tar. Once this is complete, a directory listing
of chipmunk should include the following directories 

webdoc/ psys/ 

as well as some of the following directories, depending on which
applications you pickup up. 

log/ mosis/ netcmp/ until/ util/ view/ wol/
wolcomp/ 

Compiling Psys 

This document assumes you are compiling the Psys libraries for one of
the currently supported machines, and that you have the required
support software detailed in this document. This document also
assumes that you have uncompressed and untarred the Psys file, and
installed it in the chipmunk directory. 


Begin by descending to the psys/src directory. At this point OS/2
users only should execute the following command. 
      ----

cp Makefile.os2 Makefile 

All users should now edit the 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, execute the command 

make install 

If things are working correctly, a long series of compilations, linkings,
and file movements should occur without error. When these operations
complete, Psys is successfully installed. 

Problems and Solutions 
-----------------------

It is quite possible that compilation did not proceed smoothly. Here are
some problems that could have happened, along with suggestions. 

ANSI header problems 

   Sometimes, not all the /usr/include/*.h files are ANSI
   standard, especially in older machines. Symptoms of this
   problem include mention of the stdlib.h and stddef.h
   header files in the compilation error message, and mention of
   the _SIZE_T and _PTRDIFF_T defines in the compilation
   error message. There are several possible solutions to this problem,
   depending on your machine configuration; they are listed in order of
   probability of working: 

    1. Make a file stdlib.h in the directory psys/include,
    that contains one line: the string #include
    <sys/types.h>. This file may help for the compilation of
    some files but break the compilation of other files; if so, delete
    and re-make the file as needed. 
    2. Undo the change described in 1. above, and add -D_SIZE_T
     -D_PTRDIFF_T to the CFLAGS definition in the Makefile. 
    3. Undo the change described in 2. above, and add the empty files 
    stddef.h and stdlib.h in the directory 
    psys/include. These files may help for the compilation of
    some files but break the compilation of other files; if so, delete
    and re-make the files as needed. 

Ranlib problems 
   On some systems, it may be necessary to run ranlib on the
   file libp2c.a for linking to be successfull. 

Font problems 
   The Chipmunk system expects the X fonts 8x13and 6x10 to
   be available. Some minimal systems don't have these. If you
   don't have them, search for the string DefaultFont in 
   psys/src/newcrt.c and psys/src/mylib.c, and
   change the definitions to be similarly-sized fonts that are in
   your system. 

Gcc installation problems 
   Sometimes Gcc is installed incorrectly in a system, and the
   Chipmunk tools are the first program that reveal the incorrect
   installation. Examples problems include Gcc using the cc
   preprocessor instead of its own preprocessor, and Gcc is
   looking in the wrong place for include files. When compiling
   the Chipmunk tools, a symptom of these problems often
   involves problems with accessing the system include file 
   varargs.h. 

Putc definition problems (Linux users only) 
   The putc definition in newcrt.c is set up for the current
   Slackware distribution of Linux. If newcrt.c does not
   compile for you under Linux, search in newcrt.c for the
   word dreaded for more information. 

Email support for Chipmunk Users 
--------------------------------

If you are having trouble creating a working version of the Chipmunk
tools, please let me know, and I'll try to offer help. 

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. 

Chipmunk and X 
---------------

Chipmunk and X: Color Depth 

Chipmunk tools currently support monochrome, 8-bit, 16-bit, and 24-bit
displays. The 16-bit and 24-bit display modes are only known to work
on the PC architecture (X11 under Linux and OS/2); see this document
for more details on the current status of color support.

By default, the Chipmunk tools select a color mode using these rules:

If Pseudo-Color mode is supported with a depth of at least 8
bits, the tool uses 8-bit mode.

If Pseudo-Color mode is not supported but TrueColor mode is supported,
the tool uses 24-bit depth if available, or 16-bit depth if 24-bit
depth is not available.

If all else fails, monochrome mode is selected. 

The user can force the color mode of a Chipmunk tool by setting the
environment variable LOG_COLOR to be the string bw or 8bit or 16bit or
24bit.

Chipmunk and X: Window Placement 

Manually placing and sizing the mylib and newcrt windows can
quickly become tedious. The Chipmunk tools can automatically size
and place these windows. To enable this feature, you'll need to add
information to an X initialization file in your home directory,
typically named .Xresources. Three resources are implemented
for the Chipmunk tools: 

mylib.geometry: =AxB+C+D 
   You can use this resource to set the size of the mylib window
   to have an X dimension of A pixels, and a Y dimension of B
   pixels, and have it automatically placed at the position indicated
   by C (x placement) and D (y placement). 
newcrt.geometry: +C+D 
   The size of the newcrt window is fixed for all Chipmunk
   tools. This resource automatically places the newcrt window
   at a position indicated by C (x placement) and D (y placement). 
mylib.color black_and_white 
   This X resource forces Chipmunk tools to generate
   monochrome displays, even if the machine has a color monitor. 

You will need to exit and restart your X server after changing you 
.Xresources file to activate the new behavior.


Examples 

My .Xresources for my color Sun IPC machine is as follows: 

mylib.geometry: =1150x550+0+0

newcrt.geometry: +510+586

My .Xresources for my HP 712/80 machine, which has a higher-resolution
monitor, is

mylib.geometry: =1278x682+0+0

newcrt.geometry: +638+710

These features were added to the Chipmunk tools by Jim Clark at
Harvard University, Tor Sverre Lande at IFI, and Michael Godfrey at
Stanford University.

	                    Closing Remarks
	                  ------------------

This is a preliminary release of the P-system libraries.  Some have
been translated from a different language and operating system; others
are hand-written emulations.  A few bugs and weaknesses arising from
the translation process still remain.  Correspondence on the P-system
emulation library should be sent to daveg@synaptics.com and
lazzaro@cs.berkeley.edu.

						-- Dave Gillespie, San Jose
						-- John Lazzaro, Berkeley
						











