.TH OAKLISP 1
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac

.SH NAME
oaklisp \- An implementation of the Oaklisp object-oriented Scheme dialect

\" This file is part of Oaklisp.
\"
\" This program is free software; you can redistribute it and/or modify
\" it under the terms of the GNU General Public License as published by
\" the Free Software Foundation; either version 2 of the License, or
\" (at your option) any later version.
\"
\" This program is distributed in the hope that it will be useful,
\" but WITHOUT ANY WARRANTY; without even the implied warranty of
\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
\" GNU General Public License for more details.
\"
\" The GNU GPL is available at http://www.gnu.org/licenses/gpl.html
\" or from the Free Software Foundation, 59 Temple Place - Suite 330,
\" Boston, MA 02111-1307, USA

.SH SYNOPSIS
.B oaklisp
[ emulator-options ... [ \-\- oaklisp-options ... ]]

.SH DESCRIPTION
.I Oaklisp
is an object-oriented dialect of Scheme.  This implementation is quite
portable, compiling to a virtual machine which is emulated by a C
program.  Nevertheless, reasonable speed is achieved through a variety
of sophisticated techniques.

.SH OPTIONS
Options are all long, and it makes no difference if you start them
with one or two dashes (`-').  All options can be abbreviated to a
unique prefix.  There are two sorts of options: for the bytecode
emulator, and for the Oaklisp world.  You must use a -- to separate
them.

.SS EMULATOR OPTIONS

.TP
.B \-\-help
Show summary of emulator options and exit
.TP
.B \-\-version
Print version of emulator and exit
.TP
.B \-\-world file
file is world to load
.TP
.B \-\-dump file
dump world to file upon exit
.TP
.B \-\-d file
synonym for \-\-dump
.TP
.B \-\-dump-base b
0=ascii, 2=binary; default=2
.TP
.B \-\-predump-gc b
0=no, 1=yes; default=1
.BR
.TP
.B \-\-size-heap n
n is in kilo-refs, default 128
.TP
.B \-\-size-val-stk n
value stack buffer, n is in refs
.TP
.B \-\-size-cxt-stk n
context stack buffer, n is in refs
.TP
.B \-\-size-seg-max n
maximum flushed segment len, n is in refs
.BR
.TP
.B \-\-trace-gc v
0=quiet, 3=very detailed; default=0
.TP
.B \-\-verbose-gc v
synonym for \-\-trace-gc
.TP
.B \-\-trace-traps
.TP
.B \-\-trace-files
trace filesystem operations

.SS UNOPTIMIZED EMULATOR OPTIONS

.TP
.B \-\-trace-segs
trace stack segment writes/reads
.TP
.B \-\-trace-valcon
print entire value stack at each instr
.TP
.B \-\-trace-cxtcon
print entire context stack at each instr
.TP
.B \-\-trace-stks
print the size of the stacks at each instr
.TP
.B \-\-trace-instructions
trace each bytecode executed
.TP
.B \-\-trace-methods
trace each method lookup
.TP
.B \-\-trace-mcache
trace method cache

.SS OAKLISP OPTIONS

.TP
.B \-\-help
Show summary of Oaklisp options

.TP
.B \-\-eval expr
Evaluate Oaklisp expression, which is one arg so
be sure to quote for shell.

.TP
.B \-\-load file
Load a file.

.TP
.B \-\-compile file
Compile file.oak yielding file.oa

.TP
.B \-\-locale x
Switch to locale x, eg system-locale (default),
compiler-locale, scheme-locale (for RnRS
compatibility).

.TP
.B \-\-exit
Exit upon processing this option.

.SH EXAMPLES

This will compile the file myfile.oak in the scheme locale and then
leave the user in a read-eval-print loop in the scheme locale.

.B oaklisp \-\- \-\-locale scheme\-locale \-\-compile myfile

.SH ENVIRONMENT
The environment variable OAKWORLD will override the default compiled
into the executable, but itself can be overridden on the command line.

.SH FILES
@pkglibdir@/oakworld.bin holds the world image.  It is portable
between machines of the same endianity.  The location can vary
depending upon installation-time decisions.

.SH BUGS
Floating point numbers are not implemented.  Rationals can be used to
make up for this lack because rationals can be told to print in
floating point format and floating point format input can be made to
read as rational numbers.  (There are a couple floating point
implementations, but they are not merged into the distributed
release.)

In contrast to the error handling system, which is Industrial
Strength, the debugger is virtually nonexistent.

There is no foreign function interface for loading and calling C
routines from a running Oaklisp.  (Again, there are a couple
implementations of foreign function interfaces which are not merged
in.)

The memory format does not support uninterpreted "blobs".

Porting the system to 64-bit machines has not been done, and would be
quite difficult.

POSIX threads in the emulator never got quite finished.

Bug reports and enhancements can be filed on the
.URL https://github.com/barak/oaklisp "github issue tracker" .

.SH REFERENCES

The programs are documented more fully in the language and
implementation manuals lang.pdf and lim.pdf, along with
OaklispSummary.pdf, whose source is included with the distribution,
and installed in @pdfdir@/.

The Oaklisp home page is
.URL http://barak.pearlmutter.net/oaklisp/ "old location"
to
.URL https://github.com/barak/oaklisp github .

.I The Implementation of Oaklisp
is a chapter in
.I Topics in Advanced Language Implementation
edited by Peter Lee, pp 189-215, MIT Press, 1991.

.I Oaklisp: an Object-Oriented Dialect of Scheme
appears in the journal
.I Lisp and Symbolic Computation
1(1):39-51, published by Klewer Associates, May 1988.

.I Oaklisp: an Object-Oriented Scheme with First Class Types
appeared in proceedings of the ACM conference OOPSLA-86, pp30-37,
published as a special issue of
.I SIGPLAN Notices.

.I Garbage collection with pointers to single cells,
an article on the Oaklisp garbage collector, appeared in
.I Communications of the ACM,
39(12):202-206 (online edition), December 1996.

.I The Revised^n Report on Scheme
is a useful piece of documentation, and is widely available online.

.SH DISTRIBUTION
The
.I Oaklisp
copyright belongs to its authors.  It is distributed under the
.I GNU General Public License,
a copy of which is included in the source distribution in the file
.I COPYING.
For further information or to make alternate arrangements please
contact the authors, who are surprisingly reasonable people.

.SH AUTHOR
Oaklisp was originally designed, implemented, and documented by Barak
A. Pearlmutter and Kevin J. Lang.
