	Littlle Smalltalk Installation Notes


_2.  _S_p_e_c_i_f_i_c _M_a_c_h_i_n_e _I_n_s_t_a_l_l_a_t_i_o_n _I_n_s_t_r_u_c_t_i_o_n_s

	A single source form and command syntax cannot be used
for all combinations of machine / operating systems, because
of differences in library routine syntax or function availa-
bility.    An   attempt   has  been  made  to  surround  the
occurrences of such features  with  conditional  compilation
directives, so that by defining or not defining a symbol the
correct result can be produced on different systems.   These
commands  have  all  been  collected  in  the  include  file
parser/env.h, so for the most part this should be the  prin-
ciple  file  needing  to  be  edited.   In addition, ``meta-
defines'' are provided for many systems to which the  Little
Smalltalk  system  has already been ported.  By defining one
of these ``meta-defines'', correct values are given for  the
remainder of the symbols.

	There are a few places where path specifications must
be  given  in the  C sources.   These are  described  in the
following sections.

	Finally, bytecodes are kept in the form of ``unsigned
characters'';  that  is,  characters containing numbers from
0-255.  These  may  or  may  not  be  supported  on  various
machines.   The file parser/env.h contains a typedef for the
type `uchar' and two macros  for  converting  from  unsigned
characters  to  integers  and  back  again.  These should be
defined in such a manner that  the  appearance  of  unsigned
characters  is  achieved,  whether  or not they are actually
supported.   Generally,  either  the  model  of the  VAX-780
or the PDP11/70 should be sufficient.


_2._1.  _B_r_i_n_g_i_n_g _L_i_t_t_l_e _S_m_a_l_l_t_a_l_k _U_p _o_n _a _N_e_w _S_y_s_t_e_m

	If the system you are attempting to port to is not one
of  the  systems described in the following sections, a cer-
tain amount of experimentation will probably be necessary to
successfully install the system.  This section will describe
some of the major changes required; what other  changes  may
be necessary is generally unpredictable.

	The file  parser/env.h  contains various hard paths,
which  are  described  in that file.  Also in that file, the
following symbols  should  be  defined  or  left  undefined,
depending upon the availability of various features.

CURSES	  This symbol should be defined if it is desired  to
	  provide  the  simple  ascii  graphics given by the
	  curses  and  termcap  packages.   See  section  on
	  graphics below.

ENVSAVE   This symbol should be defined if it  is  necessary
	  to  save  the  value of the global varible _e_n_v_i_r_o_n
	  during a  fastload.   This  is  necessary  on  the
	  11/70, IBM PC, possibly other machines.

FACTMAX   This symbol should be defined to  be  the  largest
	  integer for which the factorial can be computed by
	  repeated multiplication  without  overflow.   This
	  value  is  generally  12 for 32 bit machines and 8
	  for 16 bit machines.

FASTDEFAULT     This symbol should be defined if the default
	  behavior of the system should be to perform a fast
	  load on the standard prelude (see section 3).

FLUSHREQ  If defined a fflush() is given after every call to
	  printf.

GAMMA	This symbol should be defined if the gamma() func-
	  tion  is  part  of the standard math library, left
	  undefined otherwise.

INLINE	  This symbol should be defined if in-line  code  is
	  desired  for object increments and decrements.  In
	  line code is generally slightly  faster,  although
	  the  code size is slightly larger.  If this symbol
	  is not defined subroutine calls will be  generated
	  for object increments and decrements.

NOSYSTEM  This symbol should be defined on non-unix  systems
	  for  which the ``system()'' call is not supported.
	  As this seriously limits functionality (i.e. class
	  descriptions  cannot be modified during execution)
	  is should not be used unless necessary.

OPEN3ARG  This symbol should  be  defined  if  Berkeley  4.2
	  style  open statements (3 arguments) are used.  If
	  the older, 2 argument, format is used this  symbol
	  should be left undefined.

PLOT3	  This symbol should be defined if you  have  termi-
	  nals  for  which  the  plot(3)  routines can write
	  directly to the screen, rather  than  requiring  a
	  postprocessing  filter.   See  section on graphics
	  below.

SETJUMP   This   symbol   should   be   defined	if	the
	  setjump/longjump  facility  is available.  This is
	  used ONLY in the file sources/process.c to  imple-
	  ment recovery when the user has typed an interrupt
	  character.

SHORTDATA If this symbol is defined various  heuristics  are
	  used  to  reduce  the  data  segment  size, at the
	  expense  of  functionality  or  execution   speed.
	  Should only be defined if absolutely necessary.

SIGS	  This symbol  should  be  defined  if  the  signals
	  facility  is  available.  This is used ONLY in the
	  file sources/process.c to implement recovery  when
	  the user has typed an interrupt character.


_2._2.  _B_e_r_k_e_l_e_y _l_o_o_k_a_l_i_k_e_s

	It has been reported that following the directions  for
Berkeley  4.2  (below)  is also sufficient for the following
systems:

	Amdahl / System V
	Pyramid 90x / System V
	Sequent Balance 8000


_2._1_1.  _V_A_X _7_8_0 / _B_e_r_k_e_l_e_y _4._2

	In parser/env.h the ``meta-define''  BERK42  should  be
given,  and  any  other meta-defines removed.  Also in env.h
the paths in the strings TEMPFILE, PARSER and PRELUDE should
be defined.

	(VAX only) If the -g flag is used the  define  FLUSHREQ
need  not be given (although it will work if it is present),
otherwise FLUSHREQ should be defined in order for input  and
output to interleave correctly.

	As distributed, the system does not perform a fastload
(see  next  section)  automatically.  If fastload works this
can be made default by defining the symbol FASTDEFAULT.

	These instructions appear to  work  also for the SUN
workstation;  of  course,  if you have a SUN workstation you
can run the Xerox system.

_3.  _F_a_s_t _L_o_a_d_i_n_g

	The Little Smalltalk system has the ability to save and
restore a user environment by basically moving a copy of all
of the users data space into a file.  Although this produces
rather  large  files,  the  savings in time permitted by not
having to recreate a specific environment  can  be  substan-
tial.   Because  this  is such an unusual thing to do, it is
probably  wise,  if  installing  the   system   on   a   new
machine/operating  system,  to  first comment out the define
for FASTDEFAULT in parser/env.h, which will install a system
which will not default to doing a fast load.

	Once such a system has been created and passed all self
tests, you can experiment with fast loading by executing the
st command with the argument -f.  For test cases you can use
the  programs  in  /tests.   If it appears to be successful,
then (by  defining  the  variable  FASTDEFAULT)  you  should
regenerate  the system so that the default behavior is to do
a   fast   loading.	(When   regenerating   the	system,
sources/main.c  should be the only file needing to be recom-
piled).

	Fastloading does not currently work on the HP-9000.  It
may not work on other machines as well.

_4.  _P_r_o_t_e_c_t_i_o_n_s

	The directories /sources and /parser need not be read-
able  by  casual  users.   The  directory  /prelude contains
files, however, which must be loaded by the Little Smalltalk
system  prior  to  every  execution.  The protection of this
directory, and on the files in it, should therefore be  such
that  all  users  have  READ  access.   Although  the /tests
directory is only used during system installation, users may
want  to  refer to it for examples of class descriptions and
to see how various problems (8 queens, dinning philosophers)
have been solved in Smalltalk.  Allowing all users access to
the /docs directory will permit a kind  of  on-line  access,
however  users  should not be allowed to modify any files in
any directory.

_5.  _N_o_n-_U_N_I_X _s_y_s_t_e_m_s

	Non-UNIX8*9 systems which do not  support  multiple  user
processes, and thus the system() call, cannot at current run
Little Smalltalk.  There are plans, however, to at some time
in  the  future  support  such  systems.   This section will
describe,  in  broad  terms,  the  changes  required.	The
detailed changed are, of course, at the moment not known.

	First, the defined value  NOSYSTEM  must  be  given  in
parser/env.h.  This will cause all occurrences of the ``sys-
tem()'' call to be commented  out,  and  in  most  cases  be
replaced by error messages.

	Next, the parser must be modified to place  its  output
in  a  file  (presumably the file given as argument with .st
replaced by .p) instead of the standard output.  This  is  a
trivial, although probably system specific, change.

	In use, the user would then be required to  ``compile''
all  class  descriptions by running the parser (which there-
fore would have to be user accessible program)  before  run-
ning  the  Little  Smalltalk system.  Little Smalltalk could
not be used to edit class descriptions on the fly - the user
would have to leave the system, perform the edit, and return
to the system.  This would seriously limit functionality and
utility, but that is cost of not running UNIX!

_6.  _G_r_a_p_h_i_c_s

	The nice bit-mapped graphics display of the  Smalltalk-
80  system  is,  unfortunately, not very portable to conven-
tional machines running conventional  ascii  terminals.  Two
mutually  exclusive  approaches have been furnished for pro-
viding vvvveeeerrrryyyy rudimentary but nevertheless relatively  device-
independent graphics capabilities.

	The first approach used the  curses(3)  and  termlib(3)
routines to provide simple ascii (character-level) graphics.
To use these, define the symbol CURSES in parser/env.h,  and
modify   the  Makefile  in  /sourses  adding  the  libraries
-lcurses and -ltermlib (or termcap, whichever  is  appropri-
ate) to the symbol LIB.
_________________________
* UNIX is a trademark of AT&T Bell Laboratories.

	The functionality so provided can be described as  fol-
lows:

clearScreenThis message is accepted by  the  pseudo-variable
	  smalltalk and clears the screen.

printAt:  This message is accepted  by  instances  of  class
	  String.   The argument must be a point, represent-
	  ing a line@column pair.  The string is printed  at
	  the point.

	In addition, there is a class FFFFoooorrrrmmmm found  in  /prelude,
which  is  an  attempt  at  providing simple graphics forms.
Instances of FFFFoooorrrrmmmm also repond to printAt:.  A sample program
plane.st  can  be  found  in /tests illustrating some of the
features of forms.  Refer to the Makesfiles in /prelude  and
/tests for more information.

	The second approach uses the plot(3) routines.  On some
terminals  (the  Tektronix 4014, for example) these routines
can be set up to write  directly  to  the  terminal  screen,
rather  than going through a postprocessing filter.  If such
a device is available, the symbol PLOT3 should be defined in
parser/env.h,  in  addition  appropriate  loader commands (-
l4014, for example) should be added to  the  symbol  LIB  in
sources/Makefile.

	The functionality so provided is the ability to produce
lines,  circles and arcs.  Various classes (Pen, PenSave and
Form) for doing this are provided in the /prelude  subdirec-
tory,  consult  the  Makefile  for  details.  A test program
(penshow) is provided in the /tests subdirectory.

_7.  _T_r_o_u_b_l_e_s_h_o_o_t_i_n_g

	Here are a few of the problems you might run into,  and
possible solutions:

	The first thing  to  suspect  if  you  observe  strange
behavior is the fastloading feature.  Try running the system
with the -m flag, which  will  turn  off  fastloading.   For
example,  on  the 11/70 fastloading will inhibit the )i com-
mand from working correctly, but no error messages  will  be
generated.   The  appearance  of a message such as ``_x_x_x: is
not an identifier'', or of can't happen message number 23 is
also  a  clue  that  fastloading does not work and should be
disabled.  Similarly, the appearance  of  the  message  ``no
such  context as: _x_x_x/stdsave'' during startup is an indica-
tion that the file containing the saved binary form  of  the
standard  prelude either does not exist or is unreadable, or
that the path given in parser/env.h is wrong.

	The appearence of the message ``xxx:  not  an  identif-
ier''  following  a  fast load or a )l command may be a sign
that the environment pointer is being trashed.   Try  defin-
ing the symbol ENVSAVE and recreating the system.

	Solutions to problems with fastloading are to try to to
recreate  the  stdsave file in /prelude, or as a last resort
to remove the definition for FASTDEFAULT from /parser/env.h,
``make  clean''  and recompile everything.  This latter step
will configure a system that will  not  attempt  fastloading
unless explicitly called for.

	If the function _gamma is undefined following load  for
st.   Solution:  remove the definition for the symbol GAMMA,
``make clean'' and recompile.

	``Can't happen number 1''.  If you are  running  on  a
machine  with  small  memory,  your program creates too many
objects and runs out of memory.  If you are running on a vax
or other large machine - your application is creating cycles
or many many objects, probably a programming error.

	No output appears when you start the  program,  and  if
you type control-D all the output appears.  Solution: define
the symbol FLUSHREQ and recompile.

	Can't happen number 22 - either TEMPFILE is unreadable,
or /prelude/standard does not exist.

	Systems that have trouble with long lines may have dif-
ficulty  with the file syms.c in /sources (there is one line
in that file over 300 characters long).  If necessary,  this
file  can  (and  will  be)  automatically reconstructed from
other files in the directory.

	Receiving error number 129 whenever  any  non-primitive
class  method is called may be a symptom of a clash of vari-
able names.  On older systems the  variables  runningProcess
and  runningInterpreter  would clash on systems that did not
support long variable  names.   The  variable  runningInter-
preter  (in  process.c) has since been changed to presentIn-
terpreter, so this problem  should  not  occur  in  software
taken from more recent distribution tapes.

	129 errors can also be caused  by  bad  preludes.   Try
removing  all  the .p files from /prelude and remaking stan-
dard.  (Frequently, if  you  receive  an  error  when  first
building   the  prelude,  some  of  the  .p  files  will  be
incorrect).

	Note that /sources and /prelude have make instructions
``make  clean''  which remove object files and are useful in
insuring the files are in a clean state  before  starting  a
reconstruction of the system.


_8.  _F_u_r_t_h_e_r _D_i_s_t_r_i_b_u_t_i_o_n

	The Little Smalltalk system is public domain,  and  may
be  distributed  further  as  long  as proper attribution is
given in all published references.

	In the interests of keeping the distribution up to date
and  as  error  free  as  possible, we wish to keep track of
known sites using the system.  People  interested  in  being
placed  on the mailing list for future bug announcements and
new version announcements should contact Professor Budd,  at
the   address  listed  below.   Changes,  modifications,  or
improvements to the code or the standard library can be sub-
mitted  also, and will be considered for inclusion in future
distributions.

_9.  _W_h_a_t _t_o _d_o _w_i_t_h _B_U_G_S

	Observed irregularities in  Little  Smalltalk  behavior
during  execution  (hereafter  known  as ``Bugs'') should be
reported to:

	Professor Tim Budd
	Little Smalltalk Distribution
	Department of Computer Science
	The University of Arizona
	Tucson, Arizona  85721  USA

	CSNET address:  budd@arizona
	UUCP  address:  ihnp4!arizona!budd


The report of the bug should indicate whether it is reprodu-
cible,  and if so how it is manifested.  If it is available,
a description of the fix for the bug should be given, and it
will  be  incorporated  into future distributions.  Periodi-
cally, a listing of known bug fixes will be mailed to  known
sites.

	The Little  Smalltalk system  is distributed without
responsibility for the performance of the system and without
any guarantee of maintenance.
