Introductory material
---------------------

anchor:TheIntroduction[the introduction]

Installing and Running Twobit and Larceny

If you are installing or running Common Larceny, please
consult the
http://larceny.ccs.neu.edu[Common Larceny User Manual]
instead of becoming confused by the instructions below.

=== Installing the programs

Twobit and Larceny are distributed in two forms: as a precompiled
binary, or as source code that can be used to reconstruct
any of the precompiled binary distributions.
Unless you intend to modify Larceny yourself, you do not
need to download the source code.

Unpack the distribution files with an appropriate command such
as one of the following:


        tar -xzf larceny-X.Y-bin-native-sparc-solaris.tar.gz
        tar -xzf larceny-X.Y-bin-native-ia32-macosx.tar.gz
        tar -xzf larceny-X.Y-bin-native-ia32-linux86.tar.gz
        tar -xzf larceny-X.Y-bin-native-ia32-win32.tar.gz
        tar -xzf larceny-X.Y-bin-petit-stdc-macosx.tar.gz
        tar -xzf larceny-X.Y-src.tar.gz
    

This will create a directory called "larceny" in your current working
directory.  Assuming you have unpacked a binary distribution, that
directory will contain the following files:
    
    
        larceny.bin         Run-time system
        larceny.heap        Heap image with all libraries, FFI, and compiler
        twobit.heap         Heap image with some libraries and compiler
        larceny             Shell script that runs larceny.heap
        twobit              Shell script that runs twobit.heap
        startup.sch         Pathnames for the require feature
    

If you unpacked the source code there will be many other files and
directories, but "larceny.bin", "larceny.heap", and "twobit.heap"
will not be present.  You can reconstruct those files from their
source code, but that process requires a working version of Larceny
or MzScheme; unless you're porting Larceny or Petit Larceny to a
brand new target architecture, it's easier to obtain those three
files from a binary distribution of Larceny.

The scripts and heap images are discussed in the following section. 

You should decide where you want to install Larceny;
let's suppose you want to install it in /usr/local/bin and
/usr/local/lib/larceny.  Copy the files larceny, twobit,
and scheme-script to /usr/local/bin and edit the definition of the
variable LARCENY_PATH at the head of each file to point to the correct
directory:
    
    
        LARCENY_PATH=/usr/local/lib/larceny
    

Then move or copy larceny.bin, larceny.heap, twobit.heap,
startup.sch, and the lib directory to /usr/local/lib/larceny.

You should now be able to run Larceny by typing "`larceny`" at a
Unix prompt, and similarly you should be able to run the Twobit
compiler by typing "`twobit`".  On Windows, type "`larceny.bat`"
or "`twobit.bat`".

Before you can run Larceny in ERR5RS or R6RS modes, you may
have to compile the ERR5RS/R6RS runtime and standard libraries.
Step 4 of doc/HOWTO-BUILD tells how to do this.

=== Larceny or Twobit?

Unless you are doing compiler development, you should use the
"`larceny`" script, not the "`twobit`" script. The difference
is that `larceny` runs the heap image named "larceny.heap"
while `twobit` runs the heap image named "twobit.heap".

Both of these heap images contain the Twobit compiler and the
`compile-file` procedure that is used to compile files of Scheme code,
but they differ in other ways.

In "larceny.heap", every expression is compiled before it is
evaluated, but the internals of the Twobit compiler are hidden (except
for compilation switches).

In "twobit.heap", some of the libraries that are present in
"larceny.heap" are missing, and the internals of Twobit are exposed:
every top-level name in Twobit is bound in the interaction environment
and may be changed interactively, with immediate effect. Since
compiler development can be a risky business, "twobit.heap" uses the
interpreter for evaluation -- the interpreter is unaffected by changes
to Twobit.

Using the "twobit.heap" is probably not useful unless you are doing
compiler development, in which case you will need the source code as
well as the binaries, or using Petit Larceny.


=== Using Larceny

==== Running Scheme files as scripts

To run Scheme scripts or R6RS top-level programs, follow
the instructions in doc/HOWTO-SCRIPT.

On Unix systems, the following command line will run the
R5RS code in "myprogram.sch":

    larceny -nobanner -- -e '(load "myprogram.sch")'

To exit after normal termination of the program, change
the Scheme expression above to


    (begin (load "myprogram.sch") (exit))


Pre-compiled programs will load faster.  See compile-file.

==== Interactive work

To use Larceny's new ERR5RS-compatible read/eval/print
loop, follow the instructions in doc/HOWTO-ERR5RS.

When you start Larceny in R5RS mode (the default), you
will be presented with a banner message and the
read-eval-print loop's prompt:

------------------------------------------------------------
% larceny
Larceny vX.Y <version_name> (MMM DD YYYY HH:MM:SS, precise:SunOS5:split)
        
>
------------------------------------------------------------
    

You can enter a Scheme expression at the prompt.
After a complete expression has been read, it will
be evaluated and its results printed.

==== Dealing with errors

Larceny has a crude debugger. If your program crashes, the point of
error will be saved, and back at the prompt you can start the
debugger:
    
    
        (debug)
    

There is some help available on-line in the debugger. (The debugger is
pretty much a prototype; you don't need to tell us how bad it is.)

==== Performance

By default, the Twobit compiler assumes that Scheme's standard
procedures will not be redefined, which allows the compiler to
generate inline code for many calls to standard procedures. If you
want to be able to redefine standard procedures, then you should
evaluate the expression
    
    
        (integrate-procedures #f)
    

After this expression has been evaluated, the compiler will generate
slower code.

To make the compiler generate faster code, you can promise not to
redefine standard procedures _and_ not to redefine any top-level
procedure while it is running. To make this promise, evaluate
    
    
        (compiler-switches 'fast-safe)

To view the current settings of Twobit's numerous compiler switches,
evaluate
    
    
        (compiler-switches)

All of Twobit's compiler switches are procedures whose setting
can be changed by passing the new value of the switch as an
argument.

// benchmark-block-mode broken for a long time; commenting out below

////////////////////////////////////////////////////////////////////////
To make `compile-file` generate faster code, you can promise that none
of the top-level variables that are defined within a file of Scheme
code are redefined or assigned outside of that file unless they are
redefined or assigned within the file. To make this promise, evaluate
    
    
        (benchmark-block-mode #t)
////////////////////////////////////////////////////////////////////////
    

For more information, evaluate
    
    
        (help)

Some of the help information that will be printed is out of
date or may be irrelevant to the heap image you are using,
but most of it is still true.
For still more information about compiler switches, see the
<<DevelopingSwitches,developer documentation>>.

=== Troubleshooting

==== Error messages when starting Larceny

When attempting to run an R6RS program, you may see
a warning about "loading source in favor of stale
fasl file: .../lib/R6RS/r6rs-standard-libraries.sch",
following by a long series of error messages about
syntactic keywords used as a variable, ending with
the kind of error you'd expect to see when a large
R6RS program is fed to a Scheme compiler that was
expecting to see R5RS-compatible code.  That means
the R6RS runtime and standard libraries were not
installed correctly, or their source files have been
touched or modified since they were last compiled.
To fix the problem, repeat step 4 of doc/HOWTO-BUILD.

The precompiled binary forms of Larceny should run on
most machines with the appropriate processor and operating
system, but the executable program "larceny.bin" may be
incompatible with very old or with very new versions of
the processor or operating system.  If that appears to be
the case, you can use MzScheme v37x to recompile larceny.bin
from source.  First, though, you should report the problem
to us (larceny@ccs.neu.edu).  Please report success stories
as well.

==== Crashes

Please report all crashes with as much information is possible;
a backtrace from a debugger or a core dump is ideal (but please
do not mail the core dump without contacting us first).
Larceny's run-time system is compiled with full debugging
information by default and a debugger like GDB should be able
to provide at least some clues.
