PICASSO INSTALLATION NOTES - version 2 release 0
January 22, 1992

CHANGES FROM RELEASE 0 BETA

The updated manuals are available for ftp from postgres.berkeley.edu in the
directory pub/Picasso-papers.  Also pick up the tutorial in the pub
directory.  It doesn't get up to the tool-building stage, but after working
through the examples, you should grok Picasso enough to be able to dive into
the other manuals.

The scripts for using Lucid (Sun) Common Lisp are included.

Some bugs (yes Virginia, there are bugs in Picasso) have been fixed.  Thanks
to Robert Bowdidge at UCSD for sending a list of bugs and bug fixes (hint,
hint) from the Beta release.  If (when) you find bugs, send a detailed
report (what you did, what Picasso said, what happened, etc.) to
picasso-bugs@postgres.berkeley.edu.

Files that have been changes/added since Picasso 2.0.Beta
  src/headers/package.cl
  lib/po/mosaic/mosaic.cl
  lib/po/picasso/search.dialog
  lib/po/picasso/replace.dialog
  src/widgets/text/text-widget.cl
  src/widgets/text-buffer-gadget-methods.cl
  bin/Makefile
  bin/compile-l-picasso
  bin/dump-l-picasso
  bin/make-picasso-sbin
  bin/resource.lisp
  lib/po/cimtool/support/make-cimtool-sbin
  lib/po/cimtool/support/compile-l-cimtool

WHAT'S NEXT

We are planning to make another Picasso release in the near future - it will
probably be called 2.1.  The main changes will be code to allow Picasso
objects (even whole tools) to be attached and detached from the X server
more smoothly.  This will allow you to run a tool, detach it, and make an
image dump.  At some later time you can reload the image, attach the tool,
and continue where you left off.  Most of this code is complete but hasn't
been tested much.

2.1 should also include the new improved HIP (Hypermedia In Picasso) tool.
Quite a few bugs have been found and some minor new features added.  The HIP
tool isn't included in this release since it is in a state of flux.

Picasso (mainly HIP) doesn't get along all that well with Allegro 4.1 Beta.
The main problem is some poor name choices for classes that conflict with
classes in the lisp package.  We turned off locked package errors for now,
but we will rename the offending classes.

INSTALLATION NOTES

This document explains how to install picasso from a tar file (or tape) on
either a machine or network of machines.

1.  The picasso account

	Picasso should be installed in the home directory of the picasso
account.  This account should be created with group picasso and any picasso
users should be members of the picasso group.  This home directory should be
provided with ample space (40-60 megabytes recommended).

	You can also install picasso without setting up an account.  You
still need the 40-60 Megs of file space.  In either case, you'll also need
plenty of swap space to dump the Picasso image.

If you are using Allegro and you include any foreign function code
(src/toolkit/resource/gif-utils.cl uses foreign functions and is included in
the image) such as gifs, sound, cling, sling, etc., due to what appears to
be a bug in Allegro 4.0, you'll need roughly twice as much swap space as the
size of the image you are building.  Thus to build an image with 12 Megs of
Old space and 6 Megs of New space will require at least 36 free Megs of
swap.  If the amount you have is insufficient, you will get errors during
the dump-picasso script of the form:
   ; foreign loading ....
     foreign function xxx not found....  and probably more errors.
Either increase the amount of swap space your machine has, or remove
the foreign functions (comment out line in src/pic.cl).  Gif code is
included in the image because the vp tool uses gif files.

	If you are using Lucid, you'll still need plenty of swap space.
Lucid seems to need quite a bit of memory for compilation and not as much
for making an image dump.  If Lucid is very short on memory, you will get
errors during compilation.  If it is a little bit short on memory, you will
get no errors or warnings, but at least two of the source files
(src/toolkit/base/gc.cl and src/widgets/table/matrix-field-methods.cl) will
produce corrupted binaries which are undetectable until run-time.  Errors
involving functions with the words "synth", "row", and "col" are good
indicators of this problem.  The provided scripts should have the memory
growth-limit set high enough, but if your machine doesn't have that much
swap space, strange things happen.

2.  Setting Up the Picasso Directory Tree.

	The tar version of picasso has been set up to allow you to extract it
directly from the picasso home directory.  All pathnames are relative.

FOR FTP USERS:

	You should have already transferred the file picasso-2.0.tar.Z from
postgres.berkeley.edu to your machine.  Uncompress this file (using
uncompress) and place it in the home directory for the picasso account (or
the picasso home directory you select if you aren't creating a picasso
account).  Extract the Picasso directory tree with the command:

	tar xvf picasso-2.0.tar

FOR TAPE USERS:

	The tape you have includes these installation and release notes, a
README file, and the tar-format file picasso-2.0.  Extract these from the
tape into the picasso account home directory.  Then, extract the rest of the
Picasso directory structure with the command:

	tar xvf picasso-2.0

3.  Setting Up for Your Environment
	
	You need to make several changes to the provided files to ensure that
Picasso can find all of the files it needs.  You also need to add some 
environment variables to your .cshrc or .login files.

  A.)  You need to add a DISPLAY environment variable set to "unix:0.0",
"localhost:0.0" or the-name-of-the-machine-you-use:0.0 (e.g. mysun:0.0).  The
unix or localhost forms seem to work for most machines in most situations,
but if you have trouble with them, the machine name always works (it just
requires a shell script or the like to be able to handle running Picasso
from any one of a number of machines.)

  B.)  You must add a PICASSOHOME environment variable set to the name of
the Picasso home directory followed by a trailing "/".  For example
   setenv PICASSOHOME "/b/usr/applications/picasso/"
could be a line from your .cshrc.  This is necessary for building a picasso
dump.

  C.)  In the bin directory, you need to edit the Makefile so that the first
line sets the variable PICHOME to the Picasso home directory.  For example
   PICHOME = /b/usr/applications/picasso
(no trailing /).

  D.)  The file src/headers/compat.cl contains many of things that need
to changed to port picasso to a new version of Lisp, and all of the
constants and variables that refer to absolute pathnames.

 	One of the first lines of code in that file is
(defconstant *picasso-home-default* "~picasso/").  Again, put the name of
the Picasso home directory, followed by a /, in the double quotes.  This will
allow a user to run picasso even if they haven't set their PICASSOHOME
environment variable.

	Other things in this file that should be changed are the
*default-font-path*, and the path names for some of the additional features.

	Sound, video, cling, sling, libpq, and hip are all directories
under widgets that contain features that are not compiled into the
picasso dumps you make (the lines that would cause these to be
compiled/loaded are commented out of src/pic.cl).

	For example, you can add sound support to Picasso by compiling
the file src/widgets/sound/sound.c (this requires using .h include
files provided by Sun) and changing the *map-sound...  vars to point
to the sound.o and the libaudio.a (also provided by Sun) files.  Cling
and Sling (Ingres interfaces) work similarly (you need library files
provided with the Ingres installation).

	The source for libpq (Postgres interface) is provided, although this
is an interface to Postgres 1.x and won't work with newer versions of
Postgres (someone is working (slowly) on an interface to Postgres 3.x).  The
code for HIP (Hypermedia in Picasso) is also included (the tool isn't), but
is also not placed in the dump.  A new version of both the Picasso HIP code
and the HIP are in progress and will be released sometime after the Picasso
2 release.

	Those trying to port Picasso to a different version of Lisp will
want to add to or modify the macros in src/headers/compat.cl to match the
features of your Lisp.  There are other places in the code where #+allegro
and #+lucid are used to deal with implementation specific issues and these
are the areas that should be looked at first when making changes.

	If your Lisp doesn't allow concatenation of binary files (such as
.fasl and .sbin), you will need to change the dump-picasso script so that
rather than loading picasso.fasl, you instead load src/pic.cl and then do a
(load-picasso).  Of course, you might need to change a lot of other stuff
too...

	If you plan on using both Allegro and Lucid Common Lisp, you will
need to change the "dump-picasso" and "dump-l-picasso" scripts (and the
"$PICASSOHOME/lib/po/cimtool/support/compile..." scripts) so that the two
Picasso versions have different names.

  E.)  If you are planning on using Allegro, you should make sure that "cl"
is in your path before you run the makefile.  Ideally, the CL should have at
least 11 Megs of Old space and at least 6 Megs of New space.  You will get
lots of scavenges if you set the New space too small.  Most system
administrators build their Common Lisps with smaller memory allocations, so
the default cl is probably less than ideal.  If your version of Allegro has
a different name, then the last line of the scripts "compile-picasso" and
"dump-picasso" need to be changed since they reference "cl".

We briefly tested Picasso with Allegro 4.1.Beta.  The first lines of
src/headers/package.cl turn off locked package errors which are caused by us
using some bad names for classes (these should be fixed in a later release).
There are also some problems with HIP, which is not included in this Picasso
release.

  F.)  If you are using Lucid (Sun) Common Lisp, you should build a custom
image containing CLX, CLOS, and any provided patches.  You should not use the
application image as a starting point since Picasso will need to use the
compiler.  You will need to change the last line of the scripts
"compile-l-picasso" and "dump-l-picasso" to reference your custom image.

	All of the Picasso Lisp source files have the filename extension
".cl" (the default for Allegro).  The scripts provided add the ".cl"
extension to the search path for source files in Lucid (whose default is
".lisp").

	The Lucid scripts have a commented out line that loads
"$PICASSOHOME/bin/resource".  This is one of the CLX source files which
doesn't seem to be included in the CLX binary provided with our copy of
Lucid.  If you encounter errors involving "resource-database" or something
similar while compiling Picasso, you should load your custom Lucid image,
enter production code mode (using (proclaim '(optimize (compilation-speed
0)))), compile the file "$PICASSOHOME/bin/resource.lisp", and uncomment the
lines that load this file in the scripts "compile-l-picasso" and
"dump-l-picasso" (or just make another custom image with this file loaded).

  G.)  You should take advantage of Allegro Presto and the Lucid Delivery
Toolkit.  Our experience with Presto has been very positive as it results in
smaller image sizes both on disk and in memory.  The smaller size provides a
slight performance improvement also.  When our work on attach/detach is
completed, allowing an image to be saved after most of a tool has loaded and
initialized, Presto will allow even greater time/space savings.

We are in the middle of investigating the Delivery Toolkit.  The Lucid
Treeshaker doesn't seem to be appropriate for Picasso, since arbitrary Lisp
code can appear in any Picasso object, although with a lot of effort some
code reduction might be possible.  The Reorganizer can help to improve
performance.

4.  Compiling Picasso

	Now that hard part is over, you should cd to the bin directory and
type
	make allegro
if you are using Allegro Common Lisp, or type
	make lucid
if you are using Lucid (Sun) Common Lisp.

This will compile the sources, concatenate them into a picasso.fasl (or
.sbin for Lucid) file, dump the image bin/new-picasso, and finally, compile
the support code for cimtool (a good test of whether picasso dumped
properly).

5.  Getting Started

	We suggest that you obtain any reference materials (by ftp
from postgres.berkeley.edu in the pub/Picasso-papers directory) that
you do not already have copies of.  The Picasso documentation (Picasso
Reference Manual and the Widget Writers Guide) were only changed
slightly from release 1.0.

Make sure that any Picasso users add $PICASSOHOME/bin to their paths.

	Now we suggest you run a sample Picasso tool to ensure that Picasso is
correctly installed.

	a.	Start picasso (just type "new-picasso" to the shell if your
                               path is set correctly)
	b.      You should get the <new-picasso> prompt from lisp<.
	c.      Enter (paper)
                This will run the tool described in the Picasso Programming 
                Model paper.  Other tools you can run include:
        		(cimtool)
			(mosaic)
        		(test)
			(vp)

	And now, you can start using Picasso!!