\input texinfo.tex  @c -*- texinfo -*-
@comment Generated automatically from gst.txi.in by configure.
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename gst.info
@settitle GNU Smalltalk User's Guide
@comment @setchapternewpage odd
@comment %**end of header (This is for running Texinfo on a region.)

@ifinfo
This file documents GNU Smalltalk Version 1.1.5.

Copyright @copyright{} 1990, 1991, 1992, 1994, 1995, 1996 Free Software Foundation, Inc.
Authored by Steve Byrne.

Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on
all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission notice
identical to this one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).
@end ignore

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
GNU Copyright statement is available to the distributee, and provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end ifinfo

@setchapternewpage odd

@titlepage
@title GNU Smalltalk User's Guide
@subtitle GNU Smalltalk Version 1.1.5
@subtitle Not yet revised to completely reflect version 1.1.5 reality

@author by Steven B. Byrne
     
@comment  The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990, 1991, 1992, 1994, 1995, 1996 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on
all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
GNU Copyright statement is available to the distributee, and provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end titlepage
     
@node Top, , , (DIR)

@ifinfo
This document describes installing and operating the GNU Smalltalk
programming language.  If you're anxious to get started, and you know
something about the Smalltalk language, you can skip the introduction
and proceed directly to the Installation node.

You may report bugs or suggestions (or even offers of assistance)
to @file{bug-gnu-smalltalk@@prep.ai.mit.edu}.  If there is sufficient
traffic about GNU Smalltalk that is not bug-related, I will create a 
gnu.smalltalk newsgroup for communication about GNU Smalltalk.

@menu
High level node categories
* Introduction::        What GNU Smalltalk is.

* Installation::        How to build and install GNU Smalltalk.

* Invocation::          Running GNU Smalltalk.

* Features::            A description of GNU Smalltalk's special features.

* Emacs::               Smalltalk interface for GNU Emacs.

* STIX::                Smalltalk Interface to X (STIX).

* Futures::             A list of tasks for GNU Smalltalk's subsequent
                        releases.  Volunteers to help out in performing
                        some of these tasks would be greatly appreciated.
                        Please see this node to find out what you can do
                        to help make GNU Smalltalk a truly winning system.

* Acknowledgements::    Who helped in various ways with this release of 
                        GNU Smalltalk.

Individual nodes
* Installation::        Installing GNU Smalltalk

* What to examine::     Files to examine before attempting to compile
                        GNU Smalltalk.

* Compiling::           How to compile GNU Smalltalk.

* Implementations::     Known working hardware/operating systems/compilers.

* Invocation::          How to invoke GNU Smalltalk.

* Command line::        Command line arguments

* Startup::             Initial startup operation description

* Syntax::              Syntax of GNU Smalltalk method definitions

* Init file::           Per-user init file.

* Features::            Special features of GNU Smalltalk.

* General Features::    General features of GNU Smalltalk.

* Additions::           Winning features of GNU Smalltalk.

* C callout::           C function calling mechanism.

* UNIX file-IO::        UNIX file I/O primitive methods.

* system::              Access system(3).

* getenv::              Access getenv(3).

* Init Blocks::         Startup-time initialization blocks.

* Differences::         Differences from Blue Book Smalltalk.

* Emacs::               Smalltalk interface for GNU Emacs.

* STIX::                Smalltalk Interface to X (STIX).

* Futures::             Future directions for the GNU Smalltalk Project.

@end menu
@end ifinfo

@node Introduction, Installation, Top, Top
@unnumbered Introduction


GNU Smalltalk is an implementation that closely follows the Smalltalk-80
language (tm ParcPlace Systems) as described in the book @cite{Smalltalk-80:
the Language and its Implementation} by Adele Goldberg and David Robson,
which will hereinafter be referred to as ``the Blue Book''.

The Smalltalk programming language is an object oriented programming
language.  This means, for one thing, that when programming you are
thinking of not only the data that an object contains, but also of the
operations available on that object.  The object's data representation
capabilities and the operations available on the object are
``inseparable''; the set of things that you can do with an object is defined
precisely by the set of operations, which Smalltalk calls @dfn{methods},
that are available for that object.  You cannot even examine the
contents of an object from the outside.  To an outsider, the object is a
black box that has some state and some operations available, but that's
all you know.

In the Smalltalk language, everything is an object.  This includes
variables, executable procedures (methods), stack frames (called method
contexts or block contexts), etc.  Each object is an @dfn{instance} of a
@dfn{class}.  A class can be thought of as a datatype and the set of
functions that operate on that datatype.  An instance is a particular
variable of that datatype.

When you want to perform an operation on an object, you send it a 
@dfn{message}, and the object performs an operation that corresponds to
that message.  For example, to print an object, you'd send it the
message @code{print}, thus: 
@example
randomObject print
@end example

The message that you send is actually the name of a method (procedure) to 
invoke.  When you send a message to an object, Smalltalk tries to find a
method that's defined for that type of object.  It first looks in the
object's class for a method that matches.  If none is found there, it looks
in the object's parent class, then the grandparent class, and so on.  At
the top of the class structure is a class called Object, which has no parent.
If the method is not found by the time that the searching gets to the methods
of class Object, an error occurs.  This error is signaled by sending the
original object a @code{doesNotUnderstand:} message, which, if not intercepted by
the object's class or any parent class, will be handled by Object itself by
reporting the error to the user and printing a backtrace of the methods
that had been invoked at the time the error occurred.


@node Installation, Invocation, Introduction, Top
@chapter Installation
@menu
* What to examine::     What you need to examine before attempting to
                        compile and install GNU Smalltalk (see also node
                        Implementations, below).

* Compiling::           How to compile the GNU Smalltalk system.

* Implementations::     Systems that GNU Smalltalk is known to have
                        compiled and run on.

* Readline::            How to use the Bash readline library for reading
                        commands to GNU Smalltalk.
@end menu

@node What to examine, Compiling, Installation, Installation
@section Which files to examine before compiling

[The text below is mostly incorrect now.  Typically, you'd do 
@example
./configure
make
@end example
and the right things will happen; much simpler! Please see README-1.1.5 for
further information.].

Before compiling GNU Smalltalk, you'll want to examine some files,
and adjust them to suit the environment that you're running in.

The files that need to be examined are:

@enumerate
@item
@file{gstpaths.h-dist}

@item
@file{Makefile}
@end enumerate

@file{gstpaths.h-dist} needs to be copied to @file{gstpaths.h} and edited
to reflect your directory structure.  This defines where GNU Smalltalk
will look by default for the kernel method definition files and where it
will look for the saved Smalltalk binary image.  As distributed, these
default to @file{/usr/local/smalltalk/}.  If you plan on installing the
GNU Smalltalk system elsewhere, you will want to edit these in
@file{gstpaths.h}.

Also, you may want to examine the first part of @file{Makefile}.  This file 
defines which compiler you will use, the mail path to the GNU Smalltalk 
maintainer, etc.

@node Compiling, Implementations, What to examine, Installation
@section Compiling GNU Smalltalk

If you have made the modifications as described in the previous
section, you should be ready to build GNU Smalltalk.  First, you should
configure GNU Smalltalk for the particular machine and operating system
that you are on.  The current list of supported (i.e., known working)
platforms is given in the sections on supported implementations
(@pxref{Implementations}).

To perform this configuration, merely type:
@example
config.mst @var{platform}
@end example
@noindent
where @var{platform} is one of the supported hardware/software platforms of
GNU Smalltalk.  This will create a file called @file{mstconfig.h} that
is used by the GNU Smalltalk system to tailor certain behaviors.

After you've configured GNU Smalltalk, and you're satisfied with the
settings in @file{Makefile} and @file{gstpaths.h}, you can compile the
system by typing:
@example
make
@end example

Smalltalk should compile and link with no errors.  Before you make any
further changes to the Smalltalk system, you should also do
@example
make setup
@end example
@noindent
which will create a copy of all of the Smalltalk files in a
subdirectory called @file{./orig}.  This step is optional, but useful
for the following reason: any changes or fixes that you make to the
GNU Smalltalk system (such as bug fixes or enhancements) can, 
at some later point in time, be automatically diffed by doing
@example
@code{make diffs}
@end example
This is the preferred way to report changes or fixes to the system.

After doing a @code{make diffs}, and sending off the differences (or at
least squirreling away a copy of the @file{gst.diffs} file that @code{make
diffs} creates) you can do another @code{make setup} to set the
original state to be the current state.  As a shortcut, you can
produce your differences and mail them to the GNU Smalltalk maintainer
(me :-) in one operation by doing:
@example
make mail-diffs
@end example

@emph{Note:} If you add files to the top level Smalltalk directory
that you want to be included in the diffs, you must add them to the
list of files in @file{gstfiles}.  This includes top level
directories.  The @file{gstfiles} file drives the diffs system and the
@code{make setup} system.

After you have successfully built the GNU Smalltalk interpreter, you
can test it by invoking it.  You should be able to invoke Smalltalk,
thus: 
@example
@code{gst -V}
@end example
You should see the various classes being loaded one by one.  At the end
you should see a message of the form:
@example
Processing CFuncs.st
Processing Autoload.st
"GC flipping to space 1...copied space = xy.z%...done"
Smalltalk 1.1.5 Ready

st> 
@end example
At this point, you have a working GNU Smalltalk.
@emph{Congratulations!!!}

If more people than just yourself are going to be working on GNU
Smalltalk, or if you just wish to be a bit more tidy, you'll probably
want to put copies of the kernel method definitions in the directory
that is mentioned in @file{gstpaths.h} as @code{KERNEL_PATH}.  You can
do this by typing (using @file{/usr/local/smalltalk} as an example):
@example
cp *.st /usr/local/smalltalk
@end example
@noindent
assuming that you have previously created that directory.

You will also want to create the image file in the proper place
(@pxref{General Features} for info about what an image file is).  You
should switch to the directory that you want the Smalltalk binary image
to live in, and invoke Smalltalk.  It should reload the kernel
definition files and produce a new binary image.  One small issue with
this approach is that the file names associated with the method
definitions may be incorrect if the kernel definition files are in the
same directory that Smalltalk is invoked in when you create the binary
image.  Smalltalk will function completely normally, except that if you
try to get the source code for a method, you will probably lose.  To
avoid such lossage, you can switch to a directory that does not have the
Smalltalk kernel definition files in it, run Smalltalk to create the
binary image, and then move or copy the image file to its final home.
Yes, this is clumsy, and yes, I will fix this in a future release.

@node Implementations, Readline, Compiling, Installation
@section Implementations

GNU Smalltalk is known to have run on the following machines,
operating systems, and compilers:

@example
Machine                 Operating system        C compiler

Apollo 3000,4000,10000  Domain/OS 10.1          cc
Atari                   TOS                     gcc
DECStation 3100         Ultrix (2.1)            cc
Encore Multimax         ???                     cc
HP 9000/@{300,800@}       HP-UX (800=7.0,300=6.5) cc
Interactive 386         System V.3
Sony News 1810          NEWOS 3.2               cc
Sun3,Sun4               SunOS 3.5, 4.0.1        gcc 1.35, 1.37; cc
NeXT                    1.0                     cc (gcc 1.34)
Pyramid                 OSx4.1                  cc
Sequent                 ???                     cc
SGI Iris-4D             ???                     cc
Tektronix 431[5-7], 9?  ???                     cc              
VAX                     BSD 4.3/Mach            cc
@end example

The names of the supported configurations (as given to @file{config.mst}) are:
@example
@file{config.mst} target             Machine

apollo                  Apollo 3000 & 4000 (Domain/OS 10.1 or later)
apollo-88k              Apollo 10000
atari                   Atari ST
ds3100                  DECStation 3100 (2.1)
encore                  Encore Multimax
hp9k300                 HP 9000 series 300 (hp-ux 6.5)
hp9k800                 HP 9000 series 800 (hp-ux 7.0)
iris4d                  SGI Iris 4D
i386-sysv               Interactive Systems 386 System V.3
news                    Sony News 3.2
next                    NeXT, OS version 1.0
pyr-bsd                 Pyramid
sequent                 Sequent
sun-os3                 Sun 2's 3's and 4's, SunOS 3.@var{x}
sun-os4                 Sun 2's 3's and 4's, SunOS 4.0.@var{x}
tek4310                 Tektronix 431@var{x}
vax                     BSD derivative
@end example

@node Readline, , Implementations, Installation
@section Readline interface for GNU Smalltalk

The readline library is a piece of technology that allows for Emacs style
command editing (control keys move forward and back through what has
been typed, @kbd{C-p} and @kbd{C-n} move to previous and next commands
that have been typed, etc.) from within GNU Smalltalk.  It actually is the 
exact same readline library that comes with Bash; for that reason, it is not 
supplied with GNU Smalltalk.

To use readline with GNU Smalltalk, you must first obtain a version of the
readline library.  The readline library is now available as a standalone
distribution from standard GNU archives, or you may use the one which
comes with Bash distributions.  Copy (or make 
a link to) the readline to a directory in the Smalltalk top level
directory called @file{./readline}.  Edit the @file{Makefile} and
uncomment the line
@example
#READLINE = -DUSE_READLINE
@end example

Now do:
@example
make clean
@end example
This will ensure that the proper files which depend on the readline
library are recompiled.

Now invoke @file{make}.  Smalltalk should link and run normally, with
the exception that the readline functionality is enabled.


@node Invocation, Features, Installation, Top
@chapter Invoking GNU Smalltalk

@menu
* Command line::        What you can specify on the command line.

* Startup::             A step-by-step description of the GNU Smalltalk
                        startup process.

* Syntax::              A description of the input file syntax

* Operation::           A short description of how to interact with
                        GNU Smalltalk.

* Init file::           How to have GNU Smalltalk load your own method
                        definitions.

* Test suite::		How to run the test suite system.

@end menu

@node Command line, Startup, , Invocation
@section Command line arguments

GNU Smalltalk may be invoked via the following command:

@example
gst [ flags ... ] [ file ... ]
@end example

When you first invoke GNU Smalltalk, it will attempt to see if any of
the kernel method definition files are newer than the last saved binary
image in the current directory (if there is one).  If there is a newer
kernel method definition file, or if the binary image file (called
@file{gst.im}) does not exist, a new binary image will be built by
loading in all the kernel method definition files, performing a full
garbage collection in order to compact the space in use, and then saving
the resulting data in a position independent format.  Your first
invocation should look something like this:

@display
"GC flipping to space 1...copied space = 24.4%...done"
Smalltalk 1.1.5 Ready

st> 
@end display

If you specify @var{file}, that file will be read and executed and
Smalltalk will exit when end of file is reached.  If you specify more
than one file, each will be read and processed in turn. If you don't
specify @var{file}, standard input is read, and if the standard input is
a terminal, a prompt is issued.  You may specify @code{-} or @code{--}
for the name of a file to invoke an explicit read from standard input.

The flags may be specified one at a time, or in a group.  A flag or a
group of flags always starts off with a dash to indicate that what
follows is a flag or set of flags instead of a file name.  In the
current implementation the flags can be intermixed with file names, but
their effect is as if they were all specified first.
The various flags are interpreted as follows:

@table @code
@item -c
When this flag is set and a fatal signal occurs, a core dump is produced
after an error message is printed and the stack has been backtraced.
Normally, the backtrace is produced and the system terminates without
dumping core.

@item -d
Declaration tracing...prints the class name, the method name, and the 
byte codes that the compiler is generating as it compiles methods.  Only 
for files that are named explicitly on the command line; kernel files
that are loaded automatically as part of rebuilding the image file do
not have their declarations traced.

@item -D
Like the -d flag, but also includes declarations processed for the
kernel files.

@item -e
Prints the byte codes being executed as the interpreter operates.  Only
works for those executions that occur after the kernel files have been
loaded and the image file dumped.

@item -E
Like the -e flag, but includes all byte codes executed, whether they
occur during the loading of the kernel method definition files, or
during the loading and execution of user files.

@item -h or -H
Prints out a brief summary of the command line syntax of GNU Smalltalk,
including the definitions of all of the option flags, and then exits.

@item -i
Ignore the saved image file; always load from the kernel method definition
files.  Setting this flag bypasses the normal checks for kernel files
newer than the image file, or the image file's version stamp out of date
with respect to the Smalltalk version.  After the kernel definitions
have been loaded, a new image file will be saved.

@item -I @var{file}
Use the image file named @var{file} as the image file to load.  Completely
bypasses checking the file dates on the kernel files and standard
image file.

@item -p
This flag is typically not used by the user; it is for the Smalltalk 
interactor mode within GNU Emacs (see @file{st.el}).

@item -q
Suppress the printing of execution information while GNU Smalltalk
runs.  Messages about the beginning of execution or how many byte codes
were executed are completely suppressed when this flag is set.

@item -r
Disables certain informative I/O; this is used by the regression
testing system and is probably not of interest to the general user.

@item -v
Prints out the Smalltalk version number.  Has no other effect on execution.

@item -V
Enables verbose mode.  When verbose mode is on, various diagnostic
messages are printed, such as the name of each file as it's loaded.

@item -y
Turns on parser debugging.  Not typically used.
@end table

@node Startup, Syntax, Command line, Invocation
@section Startup sequence

When GNU Smalltalk is invoked, it tries to find the saved binary image
file.  If this is found, it compares the write dates of all of the
kernel method definition files against the write date of the binary
image file.  If any of the kernel files are newer, or if the image file
cannot be found, or if the @code{-i} flag is set, the image file is
ignored, all of the kernel method definition files are loaded and then
the binary image file is saved.

Smalltalk first looks for the saved image file, called @file{gst.im} in
the current directory, to allow for overriding the system default image
file.  If that doesn't exist, it checks the @code{SMALLTALK_IMAGE} environment
variable, and if that's defined, it tries to find the image file in the
directory given by @code{SMALLTALK_IMAGE}, which again allows individual users
to override the system default location for the image file.  If
@code{SMALLTALK_IMAGE} is not defined, Smalltalk will use the definition of
@code{IMAGE_PATH}, as defined in @file{gstpaths.h}, which is compiled in when
the Smalltalk system is first built.

In a similar fashion, Smalltalk looks for each of the kernel method
definition files in the current directory, to allow for explicit
overriding of the installed method definition files.  If they cannot be
found in the current directory, and the @code{SMALLTALK_KERNEL} environment
variable is defined, the directory that environment variable refers to
is examined for the kernel file(s), which again allows individual users
to override the system default location for kernel files.  If
@code{SMALLTALK_KERNEL} is not defined, Smalltalk uses the definition of
@code{KERNEL_PATH}, which is also defined in @file{gstpaths.h} and compiled
into the system.

Even if the image file is more recent than all the kernel definition
files, if the version of Smalltalk that created the image file is
different from the one that's trying to load it, or if the size of the
OOP table is different between image save time and image load time, 
or if the @code{-I} flag is specified, the image file will be ignored.

The set of files that make up the kernel method definitions can be found
in @file{lib.c}, in the @var{standardFiles} variable.  Each file is
loaded in turn.  Once they have all been loaded, a full garbage
collection is performed, and the entire contents of the object table and
object memory are dumped to a file called @file{gst.im} in the current
directory. 

At this point, independent of whether the binary image file was loaded
or created, any blocks that were marked as init blocks 
(@pxref{Init Blocks}) are invoked (in the order of their declaration).

After the init blocks have been executed, the user initialization file
(@pxref{Init file}) (if any) is loaded.

Finally, if there were any files specified on the command line, they are
loaded, otherwise standard input is read and executed until an EOF is
detected.

@node Syntax, Operation, Startup, Invocation
@section Syntax of GNU Smalltalk

The language that Smalltalk accepts is based on the @dfn{file out} syntax as shown
in the @dfn{Green Book}, also known as @cite{Smalltalk-80: Bits of History, 
Words of Advice} by Glenn Krasner.  The entire grammar of GNU Smalltalk is 
described in the gst.y file, but a brief description may be in order:

@example
<statements> !
@end example
@noindent
Executes the given statements immediately.  For example,

@example
16rFFFF printNl !
@end example
@noindent      
prints out the decimal value of hex @code{FFFF}, followed by a newline.

@example
Smalltalk quitPrimitive !
@end example
@noindent
exits from the system.  You can also type a @kbd{C-d} to exit from Smalltalk
if it's reading statements from standard input.

@example
! <class expression> methodsFor: <category name> !
<method definition 1> !
<method definition 2> !
...
<method definition n> ! !
@end example

This syntax is used to define new methods in a given class.  The
<class expression> is an expression that evaluates to a class object,
which is typically just the name of a class, although it can be the
name of a class followed by the word @code{class}, which causes the method
definitions that follow to apply to the named class itself, rather than
to its instances.  Two consecutive bangs terminate the set of method
definitions.  <category name> should be a string object that describes
what category to file the methods in.

@example
!Float methodsFor: 'pi calculations'!

radiusToArea
    ^self squared * Float pi !

radiusToCircumference
    ^self * 2 * Float pi ! !
@end example

It also bears mentioning that there are two assignment operators:
@code{_} and @code{:=}.  Both are usable interchangeably, provided that
they are surrounded by spaces.  The GNU Smalltalk kernel code uses the
@code{_} form exclusively, as this is the correct mapping between the
assignment operator mentioned in the Blue Book and the current ASCII
definition.  In the ancient days (like the middle 70's), the ASCII
underscore character was also printed as a back-arrow, and many terminals
would display it that way, thus its current usage.

The return operator, which is represented in the Blue Book as an
up-arrow, is mapped to the ASCII caret symbol @code{^}. 

A complete treatment of the syntax of the language is beyond the scope of this
document.  Please refer to the Blue Book (or the Purple Book, if that's
the only Smalltalk-80 book available) for details of the syntax and
semantics of the Smalltalk language.

@node Operation, Init file, Syntax, Invocation
@section Operating GNU Smalltalk

You operate GNU Smalltalk by typing in expressions to the @samp{st>}
prompt, and/or reading in files that contain Smalltalk code.

At some time, you may wish to abort what GNU Smalltalk is doing and
return to the command prompt.  You can use @kbd{C-c} to do this.  Note
that the @kbd{C-c} handling is relatively new, and somewhat immature.
For example, typing @kbd{C-c} while loading a file may not work, and
it won't break out of C code that hasn't been called via the C callout
mechanism.  Still, it's a vast improvement over not having anything at
all :-).

@node Init file, Test suite, Operation, Invocation
@section Per-user init files

When GNU Smalltalk is invoked, it will examine your home directory for a
file with the name @file{.stinit}.  If this file exists, it is loaded
as a normal Smalltalk file.  This file can be used for per-user
customizations (such as turning off garbage collection messages), and
definitions.

This file is always loaded; there is no current way to have a file
loaded only before main binary image is created.  In version 1.1.5, this
problem is fixed.

@node Test suite, , Init file, Invocation
@section Running the test suite

GNU Smalltalk comes with a set of files that provides a simple
regression test suite.  

To run the test suite, you should be connected to top-level the
Smalltalk directory.  Type
@example
make regress
@end example

You should see the names of the test suite files as they are processed,
but that's it.  Any other output indicates some problem.  The only 
system that I know of which currently fails the test suite is the NeXT,
and this is apparently due to their non-standard C runtime libraries.

The test suite is by no means exhaustive.  One good way to help the GNU
Smalltalk project, and learn some Smalltalk in the process, is to add 
files and tests to the test suite directory.  Ideally, the test suite
would be used as the ``go/nogo'' gauge for whether a particular port
of GNU Smalltalk is really working properly.





@node Features, Emacs, Invocation, Top
@chapter Features of GNU Smalltalk
The following sections describe of the various features of GNU Smalltalk,
version 1.1.5, and discuss differences from the Smalltalk-80 language
which is described in the Blue Book.

@menu
* General Features::    General features of GNU Smalltalk.

* Additions::           Implementation specific additions to Smalltalk.

* Differences::         Differences from Blue Book Smalltalk.
@end menu

@node General Features, Additions, , Features
@section General Features

GNU Smalltalk supports the following features of general interest:
@table @samp
@item save binary file
This allows you to snapshot the current state of the GNU Smalltalk
virtual machine.  This means that all objects are saved to a file that
can be loaded rapidly at a later point in time.  There are two messages
that you can use:

@table @code
@item SystemDictionary snapshot
This saves the current state of the GNU Smalltalk system to a file
called @file{gst.im}.  When you later invoke GNU Smalltalk, this file
will be used for binary loading if none of the kernel files has a more
recent file modification date, if the GNU Smalltalk version number is
the same as the one that created the image file, and if the size of the
object table has not changed between the time that the image file was
dumped and the time that the image file is loaded.  Note that the
instance's class that you send this message to is
@code{SystemDictionary}; in practice, you send this message to the sole
instance of @code{SystemDictionary}, @code{Smalltalk}.

@item SystemDictionary snapshot: aString
This operates exactly like the @code{snapshot} message above, except
that the string argument you supply is used as the name of the file to
save the image to.  However, since you currently cannot specify any
other file name for the image file to load from other than
@file{gst.im}, this capability is of limited utility (you could save
several snapshots throughout a run, and move the one that you were happy
with to @file{gst.im}).
@end table

@item incremental garbage collection
This improves apparent performance by eliminating pauses while garbage
collection runs.  There is a message that is printed when a garbage
collector flip occurs; this is can be suppressed by doing:

@example
Smalltalk gcMessage: false!
@end example

@item Smalltalk editing mode for GNU Emacs
This mode supports editing Smalltalk method definitions 
(@pxref{Edit} for details on how to access this package, and 
@pxref{Emacs} for a description of the Smalltalk editing mode
for GNU Emacs).

@end table



@node Additions, Differences, General Features, Features
@section Additional features of GNU Smalltalk

In this section, the features which are specific to GNU Smalltalk are
described.  These features include support for calling C functions from
within Smalltalk, accessing UNIX environment variables, and controlling
various aspects of compilation and execution monitoring.

@menu 
* C callout::   How to call user written C functions from Smalltalk.

* UNIX file-IO:: Methods for reading and writing standard UNIX files.

* Init file::   Per user initialization file support.

* system::      Invoke arbitrary UNIX programs with system(3) from
                within Smalltalk.

* getenv::      Query the value of an environment variable from within
                GNU Smalltalk.

* Init Blocks:: You can specify certain blocks of code are send a
                @code{value} message on system startup.

* Edit::        You can invoke GNU Emacs to edit the source code for a
                method.

* FileIn::      You can explicitly load Smalltalk files by using the
                @code{fileIn:} message.

* Memory::      The direct memory accessing classes.

* backtrace::   Produce a backtrace of method invocation.

* executionTrace:: Control tracing of bytecode execution.

* verboseTrace:: Printing Smalltalk stack during execution.

* debug::       Assistance using C debuggers.

* monitor::     Control C profiling during execution of methods.

* gcMessage::   Control generation of GC flip messages.

* quitPrimitive:: Exit from GNU Smalltalk explicitly

* Alternate assign::  Description of alternate assignment operator
@end menu

@node C callout, UNIX file-IO, Additions, Additions
@subsection Using the C callout mechanism

To use the C callout mechanism, you first need to inform Smalltalk about the C
functions that you wish to call.  You currently need to do this in two places:
1) you need to establish the mapping between your C function's address and the
name that you wish to refer to it by, and 2) define that function along with
how the argument objects should be mapped to C data types to the Smalltalk
interpreter.  As an example, let us use the pre-defined (to GNU Smalltalk)
functions of @code{system} and @code{getenv}.

First, the mapping between these functions and string names for the functions
needed to be established in @file{cint.c}.  In the function
@code{initCFuncs}, the following code appears:

@example
extern int system();
extern char *getenv();

defineCFunc("system", system);
defineCFunc("getenv", getenv);
@end example

Any functions that you will call from Smalltalk must be similarly defined in
this routine.

Second, we need to define a method that will invoke these C functions and
describe its arguments to the Smalltalk runtime system.  Here are the
definitions for the two functions @code{system} and @code{getenv} (taken
from @file{CFuncs.st})

@example
Behavior defineCFunc: 'system'
         withSelectorArgs: 'system: aString'
         forClass: SystemDictionary
         returning: #int
         args: #(string)!

Behavior defineCFunc: 'getenv'
         withSelectorArgs: 'getenv: aString'
         forClass: SystemDictionary
         returning: #string
         args: #(string)!
@end example

The various keyword arguments are described below.  Note that we send the
defineCFunc:... message to the Behavior class to define the new methods, even
though the methods may be installed in some class other than Behavior.

The arguments are as follows:

@table @code
@item defineCFunc: 'system'
This says that we are defining the C function @code{system}.  This name must
be EXACTLY the same as the string passed to the @code{defineCFunc}
routine in 
initCFuncs.

@item withSelectorArgs: 'system: aString'
This defines how this method will be invoked from Smalltalk.  The name
of the method does not have to match the name of the C function; we
could have just as easily defined the selector to be @code{'rambo: fooFoo'};
it's just good practice to define the method with a similar name and
the argument names to reflect the data types that should be passed.

@item forClass: SystemDictionary
This specifies where the new method should be stored.  In our case, the
method will be installed in the SystemDictionary, so that we would
invoke it thus:

@example
   Smalltalk system: 'lpr README' !
@end example

Again, there is no special significance to which class receives the
method; it could have just as well been Float, but it might look kind
of strange to see:

@example
   1701.0 system: 'mail sbb@@eng.sun.com' !
@end example

@item returning: #int
    This defines the C data type that will be returned.  It is converted to
    the corresponding Smalltalk data type.  The set of legal return types
    is:
@example
   char        Single C character value
   string      A C char * value, converted to a Smalltalk string
   symbol      A C char * value, converted to a Smalltalk symbol
   int         A C int value
   long        A C long value
   double      A C double value, converted to an instance of Float
   void        No returned value
   cObject     An anonymous C pointer value; useful to pass back to
               some C function later
   smalltalk   An anonymous (to C) Smalltalk data value; should have
               been passed to C at some point in the past.
@end example

@item args: #(string)
    This is an array of symbols that describes the types of the arguments
    in order.  For example, to specify a to call open(2), the arguments
    might look something like:

@example
   args: #(string int)
@end example

    The following argument types are supported; see above for details.

@example
   unknown     Smalltalk will make the best conversion that it can
               for this object; see the mapping table below
   char        passed as "char", which is promoted to "int"
   string      passed as "char *"
   stringOut   passed as "char *", the contents are expected to be
               overwritten with a new C string, and the object that
               was passed becomes the new string on return
   symbol      passed as "char *"
   byteArray   passed as "char *", even though may contain NUL's
   int         passed as "int"
   long        passed as "long"
   double      passed as "double"
   variadic    an Array is expected, each of the elements of the 
               array will be converted 
   cObject     C object value passed as "long" or "void *"
   smalltalk   Pass the object pointer to C.  The C routine should
               treat the value as a pointer to anonymous storage.
               This pointer can be returned to Smalltalk at some 
               later point in time.
@end example
@end table

Table of parameter conversions:

@example
Declared param type     Object type             C parameter type used

smalltalk               Object                  void *
long                    Integer                 long
unknown                 Integer                 long
int                     Integer                 int
char                    Integer                 int
int                     Boolean (True, False)   int
char                    Boolean (True, False)   int
unknown                 Boolean (True, False)   int
long                    Boolean (True, False)   long
char                    Character               int (C promotion rule)
unknown                 Character               int
string                  String                  char *
stringOut               String                  char *
unknown                 String                  char *
symbol                  Symbol                  char *
string                  Symbol                  char *
unknown                 Symbol                  char *
byteArray               ByteArray               char *
unknown                 ByteArray               char *
double                  Float                   double (C promotion)
unknown                 Float                   double
cObject                 CObject                 void *
unknown                 CObject                 void *
variadic                Array                   each element is passed
                                                according to "unknown"
@end example

@node UNIX file-IO, system, C callout, Additions
@subsection UNIX file-IO primitive messages

@noindent
The following methods are defined for the @code{FileStream} class:

@table @code
@item open: fileName mode: fileMode
Returns an instance of @code{FileStream}.  The instance accesses a file
called @var{fileName} (which should be a @code{String}) with mode
@var{fileMode} (which should also be a @code{String}, something that
fopen(3) would accept as the mode, such as @code{'r'}, @code{'w'},
etc.).  The elements of the stream are characters.

@end table

@noindent
The following methods are defined for instances of @code{FileStream}:
@table @code

@item close
Close the given @code{FileStream}.  Any further messages sent to the
file stream are in error and have undefined behavior.

@item next
Returns the next character from the stream (an instance of 
@code{Character}).

@item nextPut: aChar
Stores the character (which should be an instance of @code{Character}) as
the next character of the receiver.

@item position: bytePosition
Sets the current position of the receiver to be @var{bytePosition},
with the beginning of file being denoted by zero.

@item position
Returns an integer that indicates the current position within the
@code{FileStream}.  This is zero-based.

@item contents
Returns a @code{String} that represents the entire remaining contents of
the @code{FileStream}.

@item atEnd
Returns @code{true} if the @code{FileStream} object is at end of file,
false otherwise.

@item size
Returns the size in bytes of the given @code{FileStream} instance (if
known).

@end table

In addition, the three files, @code{stdin}, @code{stdout}, and @code{stderr}
are declared as global instances of @code{FileStream} that are bound to the 
proper values.  

Also, @code{Object} defines two other methods: @code{print} and @code{printNl}.
These both do a @code{printOn:} to @code{stdout}, the @code{printNl} appends
a newline to the end of the printed result.


@node system, getenv, UNIX file-IO, Additions
@subsection The system message

@table @code
@item SystemDictionary system: aString
This message invokes system(3), passing the string @code{aString} to 
it.  It returns an integer which is whatever system(3) returns.
@end table

@node getenv, Init Blocks, system, Additions
@subsection The getenv message

@table @code
@item SystemDictionary getenv: aString
This message does a getenv(3) on string @code{aString}, and returns the
result.  The result is either a string, or @code{nil} if there was no
environment variable with the name @code{aString}.
@end table

@node Init Blocks, Edit, getenv, Additions
@subsection Initialization blocks

@table @code
@item SystemDictionary addInit: aBlock
This message adds @var{aBlock} to the set of init blocks that the system
has.  Init blocks are invoked after loading binary image files or kernel
files, but before loading any command line files or reading from
standard input.  @var{aBlock} should be a block that takes no arguments.
@end table

@node Edit, FileIn, Init Blocks, Additions
@subsection Editing method definitions

You can have GNU Smalltalk invoke GNU Emacs to edit the source code
definition of a method.  You must have an explicit load of the
@file{st.el} file in your @file{.emacs} file in order to do this. 
@xref{Autoloading}.

If you send the method's class the @code{edit:} message, and pass the
method's name as the argument, and if you can invoke GNU Emacs by typing
@code{emacs}, you should be able to exercise this feature.

Example
@example
"Edit the definition of the edit: method itself!"
Behavior edit: #edit: !
@end example

Note that this only allows you to visit the method definition; this does
not cause the method to be redefined after you edit it.  However, it is
conceivable that could create a method that does this in a fairly simple
way.

@node FileIn, Memory, Edit, Additions
@subsection Explicitly loading files

The @code{fileIn:} message sent to the FileStream class, with a file
name as a string argument, will cause that file to be loaded into
Smalltalk.

For example,
@example
FileStream fileIn: 'foo.st' !
@end example
@noindent
will cause @file{foo.st} to be loaded into GNU Smalltalk.


@node Memory, backtrace, FileIn, Additions
@subsection Memory accessing methods

GNU Smalltalk provides methods for directly accessing real memory.
You may access memory either as individual bytes, or as 32 bit words.
You may read the contents of memory, or write to it.  Due to the
limitations of Integers in GNU Smalltalk, you can only deal with word
memory as 31 bit quantities.

You may also determine the real memory address of an object or the
real memory address of the OOP table that points to a given object, by
using messages to the @code{Memory} class, described below.

There are two basic classes which provide methods to access memory:
@code{ByteMemory} and @*@code{WordMemory}@.  The methods for
these classes are as follows:

@table @code
@item ByteMemory class at: address
Returns the byte at @var{address} as an @code{Integer}.  @var{address}
is also an @code{Integer}.

@item ByteMemory class at: address put: value
Sets the byte at @var{address} (an @code{Integer}) to be @var{value} (an
@code{Integer} in the range of 0 to 255).

@item WordMemory class at: address
Returns an @code{Integer} that represents the contents of
@var{address}, which should also be an @code{Integer}.  Depending on
the machine architecture, you'll probably want to ensure that
@var{address} is a multiple of 4.  Note that this method does not
currently work on little endian architectures (such as a VAX).

@item WordMemory class at: address put: value
Stores the @code{Integer} @var{value} into real memory at
@var{address}.  Same alignment cautions as above, and also doesn't
currently work on little endian architectures.

@item Bigendian
A global variable that is set to @code{true} on machine architectures
where the most significant byte of a 32 bit integer has the lowest
address (e.g. 68000 and Sparc), and false on architectures where the
least significant byte occurs at the lowest address (e.g. VAX).
@end table

To find out the real memory address of an object or its OOP table
entry, you may use one of the methods described below.

@table @code
@item Memory class addressOfOOP: anObject
Returns the address of the OOP for @var{anObject}.  The address is an
@var{Integer} and will not change over time (i.e. is immune from
garbage collector action).

@item Memory class addressOf: anObject
Returns the address of the actual object that @var{anObject}
references.  Note that this address is only valid until the next GC
flip; thus it's pretty risky to count on the address returned by this
method for very long. 
@end table


@node backtrace, executionTrace, Memory, Additions
@subsection Producing backtraces

@table @code
@item SystemDictionary backtrace
When you send this message to a system dictionary (i.e.
@code{Smalltalk}, the only system dictionary available), it produces a
backtrace of the methods that are the ancestors of the currently
executing method.  This backtrace is exactly like the one that is
printed when the interpreter encounters an error.
@end table


@node executionTrace, verboseTrace, backtrace, Additions
@subsection Controlling tracing of bytecode execution

@table @code
@item SystemDictionary executionTrace: aBoolean
This method controls whether byte codes are printed as the interpreter
processes them or not.  It has the exact same effect as the command
line switch @code{-e}, but allows for very fine grain control of the
tracing.  Use @code{true} to enable tracing, and @code{false} to
disable tracing. 
@end table


@node verboseTrace, debug, executionTrace, Additions
@subsection Printing Smalltalk stack during execution

@table @code
@item SystemDictionary verboseTrace: aBoolean
This method is used in conjunction with
@code{SystemDictionary executionTrace:}.  When given the argument
@code{true}, and execution tracing is on, it causes the top element of
the Smalltalk stack to be printed before each byte code is executed.
@end table

@node debug, monitor, verboseTrace, Additions
@subsection Assistance using C debuggers

@table @code
@item SystemDictionary debug
This primitive method calls a C routine which is called @code{debug}.
This can be useful in the following way: you want to get access to dbx
or gdb at a particular point in the execution of a Smalltalk method.  There
typically is no easy way to do this.  In the GNU Smalltalk system, the
C routine called @code{debug} exists solely so that you can put a
breakpoint in it from a debugger such as dbx (it is an empty routine,
and thus harmless).  You put a call to the C @code{debug} routine in
the C function that you want to debug.

So, if you put a breakpoint in the @code{debug} routine, and invoke
the @code{debug} method just before the code which you want to
debug, you gain control for detailed debugging.
@end table

@node monitor, gcMessage, debug, Additions
@subsection Control C profiling during execution of methods.

@table @code
@item SystemDictionary monitor: aBoolean
This primitive method allows the user to enable or disable the
generation of C profiling information during the operation of the
interpreter.  You must modify the @file{Makefile} to switch the
compilation to profiling mode and recompile the entire system for this
to take effect.

When you pass @code{true} to this method, you enable the collection of
profiling data during the operation of the interpreter to be later
analyzed by the @file{gprof} program.  Passing @code{false} disables
this collection.  You can use this facility to closely monitor the
operation of the interpreter over a given set of Smalltalk code to see
where it's spending its time.
@end table

@node gcMessage, quitPrimitive, monitor, Additions
@subsection Controlling generation of GC flip messages

@table @code
@item SystemDictionary gcMessage: aBoolean
This message allows the user to control whether a message is printed each time
the garbage collector flips between old and new space.  The default state is
@code{true}, meaning that when the garbage collector performs a flip, a message will
be printed.  If you supply @code{false} as the argument of this message,
the message generation is disabled until you turn it back on.
@end table


@node quitPrimitive, Alternate assign, gcMessage, Additions
@subsection Explicit termination of GNU Smalltalk

@table @code
@item SystemDictionary quitPrimitive
Invoking this method causes an immediate and unconditional exit from GNU
Smalltalk. 
@end table

@node Alternate assign, , quitPrimitive, Additions
@subsection Alternate assignment operator

@table @code
@item @code{:=}
GNU Smalltalk allows the use of @code{:=} as an alternative assignment
operator in addition to the standard @code{_}.  This is for
compatibility with other Smalltalk implementations.  Be sure to surround
this operator with at least one space on each side; failure to do so
will cause parse errors.
@end table



@node Differences, , Additions, Features
@section Differences from Blue Book Smalltalk

The following is a brief description of the differences and omissions
between GNU Smalltalk and "Blue Book" Smalltalk (Smalltalk-80).

@itemize @bullet
@item
No long integers (yet)

@item
No fractions (yet)

@item
Time values based on UNIX epoch of Jan 1, 1970 (although 
Date instances @emph{are} based on the Smalltalk base date
of January 1, 1901).

@item
Millisecond times are since midnight, instead of since the "millisecond
clock" turned over.

@item
No async signals (yet)

@item
Beginnings of the technology for a graphical user interface, and beginnings
of an incremental development environment, but nowhere near what commercial
Smalltalks provide.

@item
Class Delay is not implemented (yet)
@end itemize


@node Emacs, STIX, Features, Top
@chapter Smalltalk interface for GNU Emacs

GNU Smalltalk comes with its own Emacs mode for hacking Smalltalk
code.  It also provides tools for interacting with a running Smalltalk
system in an Emacs subwindow.

@menu
* Autoloading::       Autoloading GNU Smalltalk mode.

* Editing::

* Interactor::        Smalltalk interactor mode.
@end menu

@node Autoloading, Editing, , Emacs
@section Autoloading GNU Smalltalk mode

To cause Emacs to automatically go into Smalltalk mode when you edit a
Smalltalk file (one with the extension @file{.st}), you need to add
the following lines to your .emacs file:

@example
(setq auto-mode-alist
      (append  '(("\\.st$" . smalltalk-mode))
	       auto-mode-alist))

(autoload 'smalltalk-mode "~/smalltalk-1.1.5/st.el" "" t)
@end example

This presumes that you have placed Smalltalk as a subdirectory of
your home directory; if you have placed it somewhere else, you'll need
to change the file name mentioned in the @code{autoload} line
accordingly.

If you want additional speed, you can byte compile the @file{st.el}
file, and change the autoload line to refer to @file{st.elc} instead.

If you plan on using the @code{edit:} method to edit the source code
of your methods, you'll want to explicitly load in the @file{st.el} or
@file{st.elc} file instead of letting them autoload in.  Use
@example
(load "~/smalltalk-1.1.5/st.el")
@end example
@noindent
instead of the autoload line.

It is also a good idea to put the main GNU Smalltalk directory in your
EMACSLOADPATH environment variable.

@node Editing, Interactor, Autoloading, Emacs
@section Smalltalk editing mode

The GNU Smalltalk editing mode is there to assist you in editing your
Smalltalk code.  It tries to be smart about indentation (if you use
newline at the end of a line). Also, if you want to re-indent a line,
use @kbd{M-Tab}.  Since Smalltalk syntax is highly context sensitive,
the Smalltalk editing mode will occasionally get confused when you are
editing expressions instead of method definitions.  In particular,
using local variables, thus:

@example
| foo |
    foo _ 3.
    ^foo squared !
@end example
@noindent
will confuse the Smalltalk editing mode, as this might also be a
definition the binary operator @code{|}, with second argument called
@var{foo}.  If you find yourself losing when editing this type of
expression, put a dummy method name before the start of the expression,
and take it out when you're done editing, thus:

@example
x
| foo |
    foo _ 3.
    ^foo squared !
@end example


@node Interactor, , Editing, Emacs
@section Smalltalk interactor mode

Several new features have been added to the Smalltalk editing mode for
GNU Emacs.  The most exciting one is the Smalltalk interactor system,
which basically allows you run in GNU Emacs with Smalltalk files in one
window, and Smalltalk in the other.  You can, with a single command, edit
and change method definitions in the live Smalltalk system, evaluate
expressions, make image snapshots of the system so you can pick up where
you left off, file in an entire Smalltalk file, etc.  It makes a tremendous
difference in the productivity and enjoyment that you'll have when using
GNU Smalltalk.

To start up the Smalltalk interactor, you must have a working GNU Smalltalk
interpreter somewhere in your @code{PATH} environment variable, and be
running in GNU Emacs.  You should be in a buffer that's in Smalltalk
mode (which can be automatically enabled by adding the proper magic
to the auto-mode-alist, @pxref{Autoloading}).  For this example, let's use
the file @file{t.st}.  Visit this file, make sure that you're in 
Smalltalk mode, and type @kbd{C-c m}.  A second window will appear with 
GNU Smalltalk running in it. 

This window is in most respects like a Shell mode window.  You can type 
Smalltalk expressions to it directly and re-execute previous things
in the window by moving the cursor back to the line that contains
the expression that you wish to re-execute and typing return.

Notice the status in the mode line (e.g. @samp{starting-up}, 
@samp{idle}, etc).  This status will change when you issue various 
commands from Smalltalk mode.

When you first fire up the Smalltalk interactor, it puts you in the 
window in which Smalltalk is running.  You'll want to switch
back to the window with your file in it to explore the rest of the
interactor mode, so do it now.

Let's try executing a range of code first.  Mark the region
around:
@example
('Welcome to GNU Smalltalk [', Version, ']

This file contains a wealth of goodies, not all packaged neatly.
It sort of grows by accretion, so you''re likely to find most
anything in here.' ) printNl.

@end example

Now type @kbd{C-c e}.  The expression in the region is sent to Smalltalk
and evaluated.  The status will change briefly to indicate that the
expression is executing.  This will work for any region that you
create.  If the region does not end with an exclamation point (which is
syntactically required by Smalltalk), one will be added for you.

As a second example, move the cursor down to the region of code that
looks like:
@example
Object withAllSubclasses do: 
    [ :subclass | (subclass name notNil and: [ subclass comment isNil ])
                      ifTrue: [ subclass name print.
                                ' has no comment.' printNl ] 
                      ]

!
@end example

This code will find any class that doesn't have a comment associated
with it (I used this to track down classes that needed commenting).
Put the cursor somewhere between the first and last lines and type 
@kbd{C-c d}.  The entire expression will be sent to GNU Smalltalk, and
after scanning all the classes, GNU Smalltalk will report that class Delay
has no comment.  This command (also invokeable as @kbd{M-x smalltalk-doit})
uses a simple heuristic to figure out the start and end of the expression:
it searches forward for a line that begins with an exclamation point,
and backward for a line that does not begin with space, tab, or the
comment character, and sends all the text in between to Smalltalk.
If you provide a prefix argument (by typing @kbd{C-u C-c d} for instance),
it will bypass the heuristic and use the region instead (just like
@kbd{C-c e} does).

Now move a ways down to some text that looks like

@example
!BlockContext methodsFor: 'debugging'!

callers
    self inspect.
    caller notNil
        ifTrue: [ caller callers ]
!
@end example

Put the cursor on the line containing @code{self inspect.}.  Type
@kbd{C-c c}.  Nothing much will appear in the Smalltalk window, but what
you've done is you've compiled the BlockContext>>callers method.  To test
this, you can switch to the Smalltalk window and type
@example
[ 'foo on you' ] callers!
@end example
which will produce a simple backtrace of the invocation stack.

The @kbd{C-c c} command uses a similar heuristic to determine the bounds
of the method definition.  Typically, you'll change a method definition,
type @kbd{C-c c} and move on to whatever's next.  If you want to compile
a whole bunch of method definitions, you'll have to mark the entire set
of method definitions (from the @code{methodsFor:} line to the
@code{!!}) as the region and use @kbd{C-c e}.

After you've compiled and executed some expressions, you may want to 
take a snapshot of your work so that you don't have to re-do things
next time you fire up Smalltalk.  To do this, you use the @kbd{C-c s}
command, which creates a Smalltalk binary image called @file{gst.im}.
If you invoke this command with a prefix argument, you can specify
a different name for the image file, and you can have that image file
loaded instead of the default one by using the @code{-I} flag on the 
command line when invoking Smalltalk.

You can also evaluate an expression and have the result of the
evaluation printed by using the @kbd{C-c p} command.  Mark the region
and use the command.

To file in an entire file (perhaps the one that you currently have in 
the buffer that you are working on), type @kbd{C-c f}.  You can type
the name of a file to load at the prompt, or just type return and
the file associated with the current buffer will be loaded into Smalltalk.

When you're ready to quit using GNU Smalltalk (assuming that that
happens sometimes), you can quit cleanly by using the @kbd{C-c q} command.
If you want to fire up Smalltalk again, or if (heaven forbid) Smalltalk
dies on you, you can use the @kbd{C-c m} command, and Smalltalk will
be reincarnated.  Even if it's running, but the Smalltalk window is
not visible, @kbd{C-c m} will cause it to be displayed right away.

You might notice that as you use this mode, the Smalltalk window will scroll
to keep the bottom of the buffer in focus, even when the Smalltalk
window is not the current window.  This was a design choice that I
made to see how it would work.  On the whole, I guess I'm pretty happy
with it, but I am interested in hearing your opinions on the subject.

Speaking of opinions, the whole Smalltalk interactor mode is quite young
(about a week old as I write this) and still could use some maturation.
If you have comments or ideas about how to improve this system,
please let me know.  I have been planning something like this for a while,
but even with a vision in my head of how it was going to work, I was
unprepared for just how much of a difference it makes when hacking Smalltalk.
Hacking on STIX was infinitely easier once I got this system operational.

One minor thing that you may note when using the interactor: if you try
to get the source code for a method that's been compiled from the 
interactor, you will get garbage.  This is because I create temporary files
to hold the method definitions and send a @code{fileIn:} message to cause
them to be loaded.  The method definitions will point to this temporary
file as their source code instead of the real source code.  This is
not too hard to fix, and I felt that it was an acceptable tradeoff to
make in order to get the 1.1 release out as soon as possible.



@node STIX, Futures, Emacs, Top
@chapter Smalltalk Interface to X (STIX)

This section describes STIX: the Smalltalk Interface to X.

@menu
* STIX Defined::    What is STIX?

* STIX Requirements:: What do you need to run STIX?

* STIX Operation::  How to run the example STIX program
@end menu

@node STIX Defined, STIX Requirements, , STIX
@section What is STIX?

This version of GNU Smalltalk comes with a simple interface to X
window.  This interface is currently pretty much a direct interface to
the X protocol layer...it's even lower than Xlib.  What it does
provide, however, is a more object oriented framework for dealing with
Xlib objects.

STIX is an initial cut at an interface from Smalltalk to X.  It is
intended to be usable for simple things, and my hope is that someone
will help me out by filling in the missing parts of the X protocol
interface.  Even with a later version of Smalltalk that contains
call-ins from C, the need for an interface at this level will persist.

STIX is somewhat of an experimental interface: the mapping of X Window
protocol functions to Smalltalk is not entirely straightforward.
Thus, you may find that the current implementation of STIX is not the
cleanest way to provide such an interface.  It is hoped, however, that
the next release will be substantially better organized, and the class
hierarchy will be more well defined.

STIX also has a simple implementation of the @code{Pen} class that is
described in the Blue Book...it is used to draw some of the graphics
in the example.

@node STIX Requirements, STIX Operation, STIX Defined, STIX
@section Requirements for STIX

To be able to run STIX, you need to have a working version of X11
release 4 installed and running on your machine.  You must know where
the include files for X can be found (often, this is
@file{/usr/include/X11}).


@node STIX Operation, , STIX Requirements, STIX
@section Running STIX

The STIX example has been designed to be as easy as possible to run.
You should perform the following steps:

@enumerate
@item 
Change your working directory to be the @file{stix} subdirectory of the
Smalltalk directory.

@item 
Configure GNU Smalltalk using @file{config.mst}, as you did before
compiling GNU Smalltalk in the parent directory.

@item
Edit the @file{Makefile} file and change the definition of
@code{XINCLUDE} to point to the directory that contains the include
files for X. 

@item
Compile GNU Smalltalk by typing @samp{make}.

@item
Load and run the STIX example by typing
@example
gst -V t.st
@end example
This will load normally, except that CFuncs.st will take a bit longer
than it normally does to load.  The first time that you do this, you
should see each of the kernel files being loaded; if you don't, it means
that you are using a saved image, which won't have the STIX methods
loaded in it.  Once it's loaded and the binary image
is saved, you should see several messages indicating that things
are being executed, and, if you're successful, a window will appear
that will let you know that it's from Smalltalk.

@end enumerate


@node Futures, Acknowledgements, STIX, Top
@chapter Future directions and tasks for GNU Smalltalk

Presented below is the set of tasks that I feel need to be performed to make 
GNU Smalltalk a more fully functional, viable system.  They are presented in 
no particular order.  I would @emph{very much} welcome any volunteers
who would like to help with the implementation of one or more of these
tasks.  Please write to me, Steve Byrne, currently at
@code{sbb@@eng.sun.com} if you are interested in adding your efforts
to the GNU Smalltalk Project.

Tasks:
@itemize @bullet
@item
Port to other computers/operating systems.  The code thus far has shown
itself to be relatively portable to various machines and UNIX derivatives.
The architecture must support 32 bit pointers and long integers, and have
allocated addresses that are either all positive or all negative.
You'll probably want a reasonable amount of paging area, as GNU
Smalltalk currently uses a fair amount of memory while it's running.

@item
Comment the C code more thoroughly.  The C source code for GNU Smalltalk
could stand a more thorough commenting.  This includes things like
describing the operation of the byte code interpreter.

@item
Comment the Smalltalk code more thoroughly.  In order to be more useful
to neophyte Smalltalk users, the method definition code should be
commented to at least describe the behavior of each method; ideally, the
method definitions would have normal internal commentary as well.

@item
Write a debugger for Smalltalk.  You may note vestiges of this in this
release.  Basically, my thinking is that the debugger would be written
in Smalltalk, and would allow for setting breakpoints at byte codes,
getting method invocation backtraces, moving up and down the invocation
stack, inspecting and altering variables, possibly allowing for source
level debugging (needs cooperation from compiler), etc.  I am willing to
hear other ideas on the subject; my mindset is inspired by the debugging
capabilities of present day Common Lisp systems.  Perhaps this debugger
could be integrated with the Emacs editing mode to provide a simple way
to indicate where to put breakpoints and inspect variables.

@item
Add more test cases to the test suite.  The test suite is much too
small.  Ideally, after making changes to the Smalltalk system, you'd put
it through its paces by running with the test suite and make sure that
you hadn't broken anything.

@item
Write a C call-in to Smalltalk.  The idea here is that C functions
should be able to send messages in Smalltalk, and receive results,
which allows for true bi-directional Smalltalk<=>C communication.
Should allow for C signals to signal Smalltalk semaphores, etc.

@item
Make Smalltalk more interfaceable to C: allow a C program to be the
main program, and it merely has to call initSmalltalk() before it tries
to do Smalltalk things.

@item
Make Smalltalk C++ compatible (able to compile with C++).  In order to
allow people to use C++ code with GNU Smalltalk, it would be convenient
to have the GNU Smalltalk system be entirely compilable with G++.

@item
Switch to using getopt.  GNU Smalltalk currently uses a home-grown
option parser; this is primarily a standardization task.

@item
Write a byte-code Smalltalk compiler in Smalltalk.  As a first step
towards creating a full Smalltalk compiler, duplicate the functionality
provided by the internal byte code compiler.

@item
Convert byte-code compiler to compile to machine code, possibly using the GCC
back end (if feasible).  My thinking is to capitalize on some of the
compiler technology that's used in Self to get high quality generated code. 

@item
Implement LargeIntegers for Smalltalk.

@item
Switch from OOP table representation to direct pointer representation.
Currently, all references to objects point to an entry in an indirect
table, called the OOP table.  This has advantages in that objects may be
moved around (i.e. during garbage collection) without having to worry
about who has pointers to the object.  It also allows for simple
enumeration of all instances of a particular class, and allows for a
simple implementation of the @code{become:} message.  However, most
present day Smalltalk implementations have gotten away from this
representation, and instead directly reference objects.

@item
Investigate switching to a generational garbage collector.  Many of
Smalltalk's kernel objects are relatively static, and having to sweep
past them when garbage collecting takes time.  Also, some objects are
very fleeting indeed (such as @code{BlockContexts} and
@code{MethodContexts}), and shouldn't unnecessarily slow down garbage
collection.  Also worth investigating is not creating real objects for
methods; rather, have a method cache (stack) that contains "proto-methods".
Check at certain places for storing a pointer to a method that's a proto-method
and migrate it to be a real one when that happens.

@item
Improve the interactive inspector in GNU Emacs.  Things to add include
inspect this object/expression; examine the selectors for this calls;
fixup the handling of the temp files so that file-outs of methods that
have been incrementally redefined don't lose big-time.  Also, editing
object contents on the screen might be nice.  This would make the generally
available GNU Smalltalk mode more and more like traditional Smalltalk 
development environments.

@item
Flesh out the STIX system. There are still a number of the protocol 
items that have yet to be coded; once they're done, work can begin on a
higher level interface (Xlib or above).  Things above Xlib might include
menus and text type windows (things such as you might find in Xt).

@item
Create an X Window development system for Smalltalk.  This would be a
window-based browser, similar to that which is available in commercial
implementations of Smalltalk.

@item
Add other interesting example classes, such as Directory, or Socket, i.e.
@example
"Establish a connection to the mail system on PREP"
sock _ Socket onHost: 'prep.ai.mit.edu' port: 25.
'HELO RAMBO' printOn: sock.
sock nl.
...     

(could also have symbolic names for the port numbers, but you get
the general idea...)
@end example

@end itemize

@node Acknowledgements, , Futures, Top
@chapter Acknowledgements

I would like to publically thank the following people, who have helped out 
in one way or another since with this release (and the 1.1.5 release) of
GNU Smalltalk:

Fritz Nordby, Michael Mellinger, Doug McCallum, Karl Berry, Dave Bodenstab, @* 
Mark Wadsworth, Bill Trost, William Cook, Trip Becket,
Alan Knight, Alistair Grant, Michael Richardson, Andrew Gelsey,
Kevin Hester, David MacKenzie, Doug Peters, Michael Bushnell,
Florin Spanachi, David England, Charles Johnson, David B. Serafini,
R James Noble, David Duke, Mark S. Johnson, Gary Campbell, 
Peter Dobcsany, Kent Williams, Wilson Ho, Karl Kleinpaste, 
Len Tower, Paul Regenhardt, Joe Pallas, Peter Kropf, Mark Bush, 
Per Bothner, Kevin Rigotti, Lance Norskog, Pascal Meheut, 
Richard Goerwitz, Horst Duchene, Olivier Blanc
and especially Jeff Baird.

(I apologize if I've left anyone out).

Some have contributed code, others have helped out with discussing 
implementation issues, and others have done ports to various machines.
@emph{I appreciate all of your efforts!!!}

I must also thank the FSF for providing a wonderful set of tools with
which GNU Smalltalk was built.  Although I don't do it currently, I believe
it is the case that all of the tools that are needed for the construction
and development of GNU Smalltalk are now available from FSF (including
make, tar, diff, and other random tools).  My world is a significantly 
better place thanks to the hard work of GNU people.  @emph{THANK YOU!!!!}


@contents

@comment should put in index support in next release

@bye

Local Variables:
compile-command: "makeinfo -fc 72 gst.txi"
fill-column: 72
End:
