
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.

To use these tools, you need:

1) A unix workstation that runs X11r3, X11r4, or Openwindows
2) A color screen (some tools work with black & white screens, see below)
3) Gcc (for most platforms; see below)

This distribution has been built successfully by the maintainers,
using gcc 1.4X, on Sun Sparcstations, HP Series 300, HP/Apollo Series
400, and Apple Macintosh under AU/X. On Suns, 24-bit displays are not
presently supported. 

For these machines, gcc 1.XX is recommended at the present time.
However, in most cases the 2.XX will work well, if installing gcc 1.4X
on your machine is not possible. This distribution has been built
successfully by the maintainers, on DEC Ultrix MIPS-based machines,
using gcc 2.2.2; on these machines gcc 1.XX is NOT recommended, and
gcc 2.2.3 is NOT recommended.

This distribution has also been built successfully by the maintainers,
using the HP cc compiler with the extra-cost ANSI-option, on HP Series
700/800 machines; presently (Oct 1992) gcc 1.xx and 2.xx do not handle
varargs correctly on these machines, but this hopefully will be
supported soon, and gcc can be used on these machines as well.
However, in some versions of HP compilers (8.05 and earlier), the file
math.c causes an internal compiler bug; if your version of the
compiler has this problem, you will need to compile this file
separately with gcc, while compiling all other files with cc.
Alternatively you can get a patch tape from HP.

This distribution has been updated with suggested changes from users
who have successfully ported the chipmunk tools to the IBM RS/6000
archiecture, using the xlc compiler, but the maintainers have not
tested the distribution on this machine.

The distribution has been built successfully under Linux, using gcc
2.3.3 and the xfree1.1 Xserver. 

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.

The C sources contain ANSI C prototypes in a few places, and several
source files are *very* large.  These two reasons prompt us to require
the use of gcc as the system compiler for most platforms. The specific
gcc version recommendations, as well as non-gcc compiler
recommendations, for different platforms, reflect the current bugs in
gcc versions and cc's on different machines.  If you don't have gcc,
but have an ANSI-standard compiler on your system, psys and the CAD
tools may compile.

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


To install the psys libraries (1.10) on SUN, HP 300/400, 
or DEC MIPS machines, follow the following steps. 

  0.  The top-level distribution directory is referred to as "/usr/chipmunk"
      here.  You can actually install Chipmunk CAD in any home.  You
      should have been in "/usr/chipmunk" or your equivalent when you
      un-tar'd "psys.tar".

  1.  "cd" into "/usr/chipmunk/psys/src" and type "make install".

  2.  Install other Caltech CAD tools at the /usr/chipmunk level, the
      peer level to psys.

For HP series 700/800, IBM RS/6000, AU/X, and linux machines, changes
to the Makefile will be necessary before executing step 1. Comments in
the Makefile will guide you through these changes; the changes are
labeled with the markers (1), (2), (3), ect.

	       IF COMPILATION DOES NOT PROCEED SMOOTHLY
	       ----------------------------------------

Over the past 18 months, the maintainers have recieved about two
queries per week from users having problems compiling part of the
chipmunk system.  If you are having problems, here is a list of the
most common situations people have encountered.

(1) Problems associated with ANSI headers. Symptoms of this problem
include mention of the "stdlib.h" and "stddef.h" header files in the
error message, and mention of the _SIZE_T and _PTRDIFF_T defines in
the error message. There are several possible solutions to this problem,
depending on your machine configuration; they are listed in order of
probability of working:

  (a) make a file stdlib.h in the directory psys/include, that contains
      the following line:

       #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.

   (b) undo the change in (a), and add  -D_SIZE_T -D_PTRDIFF_T to CFLAGS
       definition in the Makefile.

   (c) undo the changes in (a) and (b), 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.

(2) ranlib problems. On some systems, it may be necessary to run ranlib
     on libp2c.a for linking to be successfull. 

(3) GCC installation problems. Sometimes Gcc gets installed incorrectly in
    a system, and the chipmunk tools are the first program that reveal the
    incorrect installation. Some symptoms/problems include:

   (a) Gcc using the cc preprocessor instead of its own preprocessor. This 
       can result in problems with varargs.h, in particular.

   (b) Gcc is looking in the wrong place for include files. Varargs.h
       problems can result in this case also.       

If your problem does not appear on this list, feel free to send email
to lazzaro@cs.berkeley.edu and/or daveg@synaptics.com explaining your
problem. Please include:

(1) Complete machine configuration, including machine type, OS revision,
compilers used.

(2) A listing of the output from the failed compilation process.

(3) Details of any changes you have made to the distribution before this
    compilation.

(4) If applicable to your problem, the effects of the suggestions given
    above.


	Specifying Window Geometry in Your .Xresources File
	---------------------------------------------------

This version of psys looks in your .Xresources file for geometry information
for all the chipmunk tools. If set properly, this allows windows of a
certain size to be automatically placed at a particular place at every
invocation of a chipmunk tool; manual placement of windows is no longer
necessary. This feature was added by Jim Clark at Harvard. Adding these
lines to your .Xresources file:

mylib.geometry: =1150x550+0+0
newcrt.geometry: +510+586

will result in good placement and sizing for the color monitors
shipped with SPARC IPC's; for other screens, charge the numbers after
"+" signs for new positions, and change the numbers between the "x"
for modify the size of the mylib window. The newcrt window cannot be
modified; many of the chipmunk tools expect it to be a fixed size.

Psys now senses if a display screen is black and white, and tries to
use stipple instead of colors. However, there are times where you want
to force the tools to display in black and white, even if the display
screen is color. These times include using an OS/2 based color PC as an
X terminal for the analog tools, because of present incompatabilities
between PC graphics cards and analog. To force a black and white display,
add this line to your .Xresources file:

mylib.color:  black_and_white

and then restart your X server. Black and white support was provided
by Tor Sverre Lande (Oslo), and the .Xresources flag was added by Mike
Godfrey (Stanford).

	                    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
						

