[[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 AArch64 (aka ARM64) microprocessors running macOS
and for Intel x86 machines running Linux.

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
~~~~~~~~~~~~~~~~~~~

Prepackaged binary distributions of native Larceny are available
for x86 Linux machines and for Apple computers running macOS on
current Apple silicon (AArch64).

Prepackaged distributions of Petit Larceny may also be made
available for those machines.

To install a prepackaged distribution, please see
https://github.com/larcenists/larceny/blob/master/doc/HOWTO-INSTALL[`doc/HOWTO-INSTALL`].

Both native Larceny and Petit Larceny can be built from the
source code available at
https://github.com/larcenists/larceny[Larceny's GitHub site].
To build Larceny or Petit Larceny from source code, see
https://github.com/larcenists/larceny/blob/master/doc/HOWTO-BUILD[`doc/HOWTO-BUILD`].

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

////////////////////////////////////////////////////////////////
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 file with an appropriate command such
as one of the following, substituting the version number (such
as 2.0) for "X.Y":

        unzip larceny-X.Y-bin-native-x86-linux.zip
        unzip larceny-X.Y-bin-native-ARM-macos.zip
	unzip larceny-X.Y-bin-petit-stdc-linux.zip
        tar -xzf larceny-X.Y-bin-native-x86-linux.tgz
        tar -xzf larceny-X.Y-bin-native-ARM-macos.tgz
        tar -xzf larceny-X.Y-bin-native-ia32-linux86.tar.gz
	unzip larceny-X.Y-src.zip

That will create a directory with a similar name (but without
the `.zip` or `.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`.

We recommend the 64-bit versions of Larceny (version 2.0 or later),
but we are still distributing a 32-bit version, Larceny v1.5,
that runs on x86 machines under Linux.
If you have downloaded a 32-bit version of Larceny, as indicated
by the `ia32`, you may need to install some 32-bit libraries
on your machine.  See
https://github.com/larcenists/larceny/blob/master/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
or some other implementation of the R5RS, such as Racket's `plt-r5rs`.
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 vX.Y "<version_name>" (MMM DD YYYY HH:MM:SS, ...)
    > (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.
////////////////////////////////////////////////////////////////////////

