
			STONY BROOK PROLOG (SBP)
			    version 2.3.2
		  ported by David Roch and Scott Evernden
			maintained by David Roch


--- A Faery Tale :-) ---

Once upon a time, two programmers decided to port the same
program.  After many hours of hacking, they both arrived
at nearly the same result, a working Prolog system.  One
of the programmers (the clever one), turned his work over
to the other saying "Take this, and the headaches that go
with it."  The other programmer naively accepted.  He
discovered that the two programmers had both done similar
work.  In some areas, one shone while the other was bogged
down in the swamps of incomprehension and ignorance.  In
other areas, the reverse was true.  Eventually, after many
aeons, a unified version was complete, and they all lived
happily ever after --- at least until the bug reports
started pouring in.


--- A short note on the SBP 2.3.2 port ---

When Scott sent me his version of 2.2, he had added some
nice features to it which I have been unable to include
in 2.3.2.  I did not include these modifictations for
two reasons.  First, 2.3.2 is the second update to SBP
in less than a year.  Conversations with S.K. Debray
(the maintainer) lead me to believe that there will be
future upgrades.  It is my intention to keep porting newer
versions as simple as possible.  Secondly, and more importantly
(to me at least), my purpose in porting SBP was to use it
for work I'm doing on my thesis.  I do not have enough time
to maintain additions which are irrelevant to my current work.

	Major omissions from Scott's version -
		Manx C support - sorry, I don't have Manx
		Library support - ability to call Amiga library routines

Nearly all the documentation is by Scott.  His
documentation was much cleaner than mine, and I have
merely edited his documentation where it was inconsistent
with the merged version of the port.  Credit where credit's
due.  Also, any gripes about style (or compliments) should
be directed to me.  The additional code in the port is mine, 
I merely used some of Scott's ideas.

From the SB-Prolog System, Version 2.2 User Manual:

"SB-Prolog is a public-domain Prolog system for Unix(tm) based systems
originally developed at SUNY, Stony Brook.  The core of the system is an
emulator, written in C for portability, of a Prolog virtual machine that is
an extension of the Warren Abstract Machine.  The remainder of the system,
including the translator from Prolog to the virtual machine instructions,
is written in Prolog."

In addition to providing a compiler, SB-Prolog also offers advanced features
such as dynamic loading, mixing of compiled and interpreted code, macros,
extension tables, a debugging facility offering two levels of tracing,
profiling tools, and other utilities.

Introduction
------------
This is version 2.3.2 of SB-Prolog, originating from SUNY at Stony Brook.  It
provides an advanced logic programming environment on the Amiga, adequate
for experimentation in the areas of artificial intelligence and fifth
generation systems.

When running the naive-reverse benchmark, the SB-Prolog interpreter runs at
over 1000 LIPS (logical interences per second).  The compiler can produce
code that can be executed at over 3600 LIPS.

The complete Amiga SB-Prolog distribution is provided on 2 disks.  The
source code in C and Prolog is on the "PROLOG SOURCE:" disk;  executables
and ready-to-load Prolog objects are on the "PROLOG:" disk.  The source
disk is necessary only if you want to modify or add-to the operation of
the system, or if you want to understand how a Prolog-based
interpreter/compiler works.  Substantial portions of SB-Prolog, including
its compiler, are written in Prolog.

Starting SB-Prolog
------------------
A simple script on the SBP2.3.2: disk has been provided.  It runs SB-Prolog
with a set of default configuration parameters which should be adequate for
most medium sized tasks.  It can be 'Executed' to start SB-Prolog in this
default configuration.  From the CLI:

	> execute prolog:prolog

WARNING:  If you have a shell running, this may not work!  SBP uses
some characters e.g. $,! that are frequently used by shells as 
control characters.  If you have problems, try it without the shell.
(You should probably start a new cli anyway, the shell is useless
while SBP is running).

This will be followed by 30 seconds of much disk activity as the byte codes
for the interpreter are read from disk.  The a silent 20 second pause ensues
as the interpreter program adjusts itself to the impressive greatness of
the Amiga.  Finally, a message is printed, and SB-Prolog is running. I run
my system with 50000 bytes of Stack, and have never had problems with this
setting.

To quickly test the operation of the system, you can do the following, and
observe the results:

	| ?- consult('hanoi.P').
	| ?- hanoi(5, start, aux, end, Solution).

These statements demonstrates the performance of interpreted SB-Prolog while
solving the Towers of Hanoi problem.

	| ?- compile('hanoi.P','hanoi').
	| ?- load('hanoi').
	| ?- hanoi(5, start, aux, end, Solution).

Here we compile (takes about a minute), load, and then execute the
Towers of Hanoi program.

SBP supports break levels which are described in the documentation.
However, I'll point them out now in case you decide to do something
naive like hanoi(5000, s, a, e, S) which takes a long, long, long
time.  You can type ^C (Ctrl-C) during execution, and SBP will
suspend the current computation.  At the break level, you are
permitted to do anything normally permissible.  If you wish
to continue the suspended computation, you may do so by typing
^\ (end of file), or typing "abort." to abort the computation.

In SBP, you are not allowed to input predicates at the command
line level.  You can only consult existing files.  Once you begin
to feel comfortable with the system, you could define your own
input routine that asserts each fact as it is read in.  However,
assuming that you have enough memory to run an editor, this should
not pose any problem.  

You can access AmigaDOS; for example:

	| ?- system(list).
or
	| ?- system('list df1:').
		note the single quotes.

And finally, since you'll probably want to stop the program sometime:

	| ?- halt.
or
	| ?- end_of_file.
or
	| ?- ^\	 (control \ is the end of file character on the Amiga)
will return you to the CLI.


The complete syntax for running SB-Prolog directly, describing all
configuration parameters is detailed in the User Manual.  Briefly,
the command line:

SBP2.3.2:sbp/sim -i ".!sbplibs:modlib!sbplibs:lib!sbplibs:cmplib" -m 
	75000 -p 75000 SBP2.3.2:sbp/libraries/modlib/$readloop

means run SB-Prolog with 75K longwords of heap/stack (-m switch);
with 75K longwords of permanent space (-p switch), and provides
a path to the libraries (-i switch).  The last argument tells 
the byte code simulator (SBP) to load and execute the query evaluator
(user interface) $readloop.


IMPORTANT:
This program will not have available enough memory to operate on a 512K or
less Amiga.  It probably won't run on a one megabyte machine either
unless you decrease the default heap and memory space.  No guarantees
though, I haven't tried it.

The system is quite memory-intensive, requiring approximately 92K bytes for
the SB-Prolog 'simulator', and 2 contiguous 300K byte blocks of memory for
SB-Prolog's heap/stack, and permanent memory space.  You really will need
more than 1Meg to effectively use the program.  I find myself running out
of memory on my 2.5Meg setup!  If you see the "Not enought core!" message,
rebooting your Amiga will consolidate fragmented memory, and may allow the
program the elbow room it needs to run.


Documentation
-------------
The User Manual for SBP is SBProlog.doc and is located on this disk.
Scott has gone to the trouble of formatting it nicely.  Note that
the manual is for 2.2, not 2.3.2.  This is as the changes for 2.3.2
have nearly all been internal to the libraries and the simulator.
The only new feature is that files may be consulted with list notation.
That is, instead of typing 'consult(filename).' the user may type
'[filename]' as in some other Prolog implementations.

The original documentation (Troff/Nroff format) is available on
the archives disk for those who have access to UNIX (TM AT&T)
systems.  Scott used the following to sequence to produce his
copy:	cat sbprolog_doc.me | tbl | neqn | nroff -Me.

Differences from the UNIX version
---------------------------------
 The Amiga OS does not yet support environment variables, so I
needed to devise an alternate mechanism for this capability.  So, a new
switch (-i) has been added to pass the SIMPATH variable.  What SIMPATH
does for SBP is to tell the simulator where to find the programs
to be loaded.  This is very similar to the PATH variable in UNIX.
For example:
	-i .!SBPLIBS:lib!SBPLIBS:modlib!SBPLIBS:cmplib
tells the simulator to look first in the current directory (the '.'),
then in directory SBPLIBS:lib, and so on down the path for each
program that it needs to load.  Spaces are not allowed.  Note
that when the -i option is specified, any calls to the $getenv/2
primitive will return the path you specified via -i.  Currently,
the SIMPATH is limited to 256 characters (you can easily change
this if you have a C compiler).  No error will be given
should you exceed this.  

The system predicate syscall/3 has only three UNIX system calls
implemented:  chdir, chmod, and access.  Chdir can be extremely
useful to the user as it provides a method of changing directories
within SBP.  To use it, type the following:
	syscall(12, ['df1:some/directory/path'], Result).
If Result = 0, then the change was successful.  You may find it
useful to define the following in your files:
	cd(Dir) :- syscall(12, [Dir], X), X =:= 0.
then you can merely cd('directory/path').  The predicate will
fail if you specify an illegal directory.


Archive Disk:
-------------
The other disk that comes with this distribution is the archive
disk.  It contains C source code for the simulator (along with
a description in file changes of the changes I made), the
Prolog source code for the libraries, and benchmark programs.
These are all stored in the zoo archive format.  A copy of zoo
is also supplied so that you can unarchive them.

KNOWN BUGS:
-----------
	- The restore command will not work across seperate
	invocations of the simulator.  I believe that I have
	found the source of the problem, but I haven't had
	time to fix it.
	
	- When requesting a break level, if the system is
	requesting input, you must type some character after
	^C and press Return.  I usually use the comment 
	character % to avoid having SBP interpret this as
	a command when I return from the break level.

	- Timing statistics are frequently blatantly wrong.
	For example, the compiler may tell you that it only
	took 30 seconds to compile when in fact, it took over
	a minute.

	- Sometimes after consulting a file numerous times
	(e.g. during devlopment), the changes will not take
	effect.  This is a problem with SBP, not the port.
	I have so far been unable to come up with a consistent
	case to demonstrate this bug.  If anyone does, please
	send it to me and I'll see what can be done about it.
	In the mean time, you can exit SBP and restart.
