[[InstallationChapter]]

Installing Larceny
------------------

[[VarietiesSection]]

Varieties of Larceny
~~~~~~~~~~~~~~~~~~~~

There are two main varieties of Larceny.

Native Larceny is the fastest and most convenient variety
of Larceny.  It compiles directly to native machine code
for Intel x86 or ARMv7 microprocessors running Linux and
for x86 machines running Apple's macOS or Microsoft Windows.

Petit Larceny compiles to C instead of machine code.  It
can be made to run on most Unix machines.

////////////////////////////////////////////////////////////////////////
Common Larceny compiles to JIT-compiled IL on Microsoft's
Common Language Runtime (CLR) or Mono.  It provides access
to the .NET libraries from Scheme.
////////////////////////////////////////////////////////////////////////


[[SystemRequirementsSection]]

System requirements
~~~~~~~~~~~~~~~~~~~

Binary distributions of native Larceny are available for
just about any Intel x86-compatible microprocessor
running a Linux, macOS, or Windows operating system,
and for ARMv7 microprocessors running Linux.
Although Larceny still uses 32-bit pointers, it will run
on 64-bit machines provided the appropriate 32-bit
libraries have been installed.

Binary distributions of Petit Larceny are available for
x86 machines running Linux.  Petit Larceny requires the `gcc`
compiler as well as the appropriate 32-bit libraries.

Unless you intend to modify Larceny yourself, you do not
need its source code, which is available at
https://github.com/larcenists/larceny[Larceny's GitHub site].

////////////////////////////////////////////////////////////////
To use some features of the FFI, you'll need the appropriate
C compiler (`gcc` except on Windows) and 32-bit libraries.
////////////////////////////////////////////////////////////////

For more details, see
https://github.com/larcenists/larceny/blob/master/doc/HOWTO-INSTALL[`doc/HOWTO-INSTALL`].
If you want to build Larceny or Petit Larceny from source code, see
http://larceny.ccs.neu.edu/doc/HOWTO-BUILD[`doc/HOWTO-BUILD`].

////////////////////////////////////////////////////////////////
To build Larceny or Petit Larceny from source code, you
will need a binary distribution of Larceny for your build
machine plus the C compiler and 32-bit libraries appropriate
for your target machine.
To build the native variety of Larceny, you will also need
the http://www.nasm.us/[Netwide Assembler] (`nasm`).
For more details, see
http://larceny.ccs.neu.edu/doc/HOWTO-BUILD[`doc/HOWTO-BUILD`].
////////////////////////////////////////////////////////////////


[[DownloadingSection]]

Downloading
~~~~~~~~~~~

The current versions of Larceny are available for
download at
http://www.larcenists.org/[Larceny's main web page].

Larceny is 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.


[[InstallationSection]]

Installing the programs
~~~~~~~~~~~~~~~~~~~~~~~

Unpack the distribution files with an appropriate command such
as one of the following, substituting the version number (such
as 1.3) for "X.Y":


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

That will create a directory with a similar name (but without
the `.tar.gz` suffix) in your current working directory.
That is the Larceny root directory, which you may rename
to something shorter, such as `larceny`; the rest of this
section will refer to it by that name.

Assuming you have unpacked a binary distribution for Linux or
macOS, the `larceny` directory will contain the following files:
    
    
        larceny.bin         Run-time system
        larceny.heap        Heap image with preloaded libraries and compiler
        larceny             Shell script that runs the two files listed above
        scheme-script       Shell script that runs Scheme scripts
        compile-stale       Scheme script that compiles R7RS/R6RS libraries
        compile-larceny     Scheme script that compiles a R7RS/R6RS program
        startup.sch         Pathnames for the autoload and require features
    

If you unpacked a binary distribution, then you should be able to
run it immediately by making the `larceny` directory your current
working directory and invoking `./larceny`.
(If that does not work, you may need to install some 32-bit libraries
on your machine.  See
http://larceny.ccs.neu.edu/doc/HOWTO-INSTALL[`doc/HOWTO-INSTALL`].)

Binary distributions for Windows will include a `larceny.bat` file
in addition to the files listed above, so you can run Larceny by
invoking `larceny`.
(If that does not work, you may need to tell the
http://www.thewindowsclub.com/turn-off-data-execution-prevention-dep[DEP
 feature]
to let Larceny opt out.)

If you unpacked the source code there will be many other files and
directories, but `larceny.bin` and `larceny.heap` will not be present.

[TIP]
================================================================
You can reconstruct the `larceny.bin` and `larceny.heap` files from their
source code, but that process requires a working version of Larceny.
Unless you're porting Larceny or Petit Larceny to a
brand new target architecture, it's easier to obtain those
files from a binary distribution of Larceny.
================================================================

You may add the `larceny` directory to your standard path,
or you may install Larceny into a directory that is already
part of your standard path.

Suppose, for example, that you want to install Larceny
in `/usr/local/bin` and `/usr/local/lib/larceny`.
To do that, move the entire `larceny` directory to `/usr/local/lib/larceny`.
Then copy the `larceny`, `scheme-script`, `compile-stale`,
and `compile-larceny` files to `/usr/local/bin`.

If you are using macOS or some other non-Linux operating system,
you will need to edit the definition of `LARCENY_ROOT` at the head
of the `larceny` and `scheme-script` files to point to the correct
directory:
    
    
        LARCENY_ROOT=/usr/local/lib/larceny
    

You should now be able to run Larceny from any directory
by typing "`larceny`" at a prompt.


[[CompilingStdLibSection]]

=== Compiling the R7RS/R6RS standard libraries

If you are installing Petit Larceny, then you will have to
compile the R7RS/R6RS runtime and standard libraries before
you can run Larceny in R7RS or R6RS modes.

This step is also required if you are building any variety of
Larceny from source code.
With the prebuilt native varieties of Larceny, however, this step
should not be necessary unless you change one of the files in
+lib/R7RS+, +lib/R6RS+, or +lib/SRFI+.

[TIP]
================================================================
If the +lib/R7RS+, +lib/R6RS+, and +lib/SRFI+ directories are
read-only, you will be less likely to touch, modify, or compile
the standard libraries by accident.
================================================================

Compiling the R7RS/R6RS runtime and standard libraries is
accomplished as follows:

----------------------------------------------------------------
    $ ./larceny
    Larceny v0.98 "General Ripper" (...)
    > (require 'r7rsmode)
    > (larceny:compile-r7rs-runtime)
    > (exit)
----------------------------------------------------------------


[WARNING]
================================================================
Compiling the R7RS/R6RS runtime as shown above causes
all previously compiled R7RS/R6RS libraries and top-level
programs to become <<CompilingChapter,stale>>.  That means
those previously compiled files will need to be recompiled
or removed.
================================================================

////////////////////////////////////////////////////////////////////////
=== 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 all 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 an
interpreter to evaluate the Scheme code you load and type -- the
interpreter is unaffected by changes to Twobit.

If you are using "`twobit.heap`" for compiler development,
you will need the source code as well as a binary distribution
of Larceny.
////////////////////////////////////////////////////////////////////////

