Installing Larceny


Outline:
    How to install (short version)
    System requirements for 64-bit Larceny
    System requirements for 32-bit Larceny
    How to install (long version)
    Petit Larceny is a little different
    The scheme-script feature


How to install (short version):

Put Larceny's main directory wherever you like, and give it
whatever name you like.

Copy the executable scripts (larceny and scheme-script) wherever
you like, and edit them to set LARCENY_ROOT to the absolute
path of Larceny's main directory.  (On Linux systems, you can
just create links to those scripts instead of copying them, and
you don't need to edit them.)  You may also want to copy or
create links to the compile-larceny and compile-stale scripts.

If the directory that contains the executable scripts is not
already part of your path, then add it to your path.

If that doesn't work, or you want to install both native Larceny
and Petit Larceny on the same machine, then keep reading.


System requirements for 64-bit Larceny:

Larceny v2.0 is a 64-bit implementation of Scheme.

Prebuilt distributions of Larceny v2.0 are available for:

    macOS machines with Apple Silicon (AArch)
    Linux machines with x86-64 processors

To build Larceny from source code, see HOWTO-BUILD.


System requirements for 32-bit Larceny (v1.5 or older):

Prebuilt binary distributions of 32-bit Larceny (v1.5 or older)
are still available for machines with ARMv7 or Intel IA32 and
compatible (i386 or x86-32) processors running the following
operating systems:

    Linux
    MacOS X (but no later than version 10.14)
    Windows XP or later

Although Larceny v1.5 still uses 32-bit pointers, it will run
on 64-bit machines provided the necessary 32-bit compatibility
libraries have been installed.

On Linux machines, the 32-bit libraries can be installed by
incanting something like

    sudo apt-get install lib32z1
    sudo apt-get install libc6-i386

(The second of those should be unnecessary because libc6-i386
should be installed automatically when lib32z1 is installed.)
To build Larceny from source, you would also need to install
libc6-dev-i386.

Apple dropped support for 32-bit applications on its Intel
machines somewhere around version 10.14 of its operating
system.  On older Macintoshes with Intel processors, whose
operating system has not been updated past 10.14, the 32-bit
libraries may already be installed.  If they aren't, then
installing the Apple Developer command-line tools might fix
the problem.

On Windows, the DEP feature must be told to allow Larceny to
opt-out.  (See below.)


How to install (long version):

After you download a binary distribution of Larceny or build from
source, there will be several scripts for starting Larceny in the root
of the Larceny tree.  These can be run from that location, regardless of
where you keep the tree.  If you want to make Larceny available to other
users of your system, however, or if you want to install the executables
in a standard place, this document will tell you how.

Larceny is usually started by a script, which has two functions:

 - It sets an environment variable LARCENY_ROOT to the absolute path of
   the Larceny tree, which is assumed to be the same as the directory
   that the script is in.

 - It dispatches on the name of the script, to choose both a Larceny
   executable (such as larceny.bin) and a heap image (such as
   larceny.heap).

Which scripts you have depends on what platform you are using:

 - Windows: Batch files "larceny.bat" and "twobit.bat"
 - Linux, Mac OS X: Shell scripts "larceny", "scheme-script",
    compile-larceny, and "compile-stale"

Note that "twobit" and "twobit.heap" are no longer distributed
as part of Larceny's binary distributions.

If you would like to move a larceny or twobit script to another
directory but not rename it, it is sufficient to hard-code the
location of Larceny's root directory into the script.  For
example, to install Petit Larceny into /usr/local on Linux,
untar the Larceny tree as /usr/local/lib/larceny.  Then copy
the scripts "larceny", "scheme-script", "compile-stale", and
"compile-larceny" to /usr/local/bin, editing the first two by
uncommenting the line that sets LARCENY_ROOT, and setting it to
/usr/local/lib/larceny.

If you would like to change something else, such as the name of
a script, editing the script should not be too difficult.


Petit Larceny is a little different:

The pre-built distribution of Petit Larceny is only partially
pre-built.  Its R5RS mode has been pre-compiled and linked
into the petit-larceny.heap file, which is loaded and executed
by the petit-larceny.bin runtime system.  Those two files, like
the larceny script within the same directory, can be moved with
abandon so long as they all stay within the same directory.

Petit Larceny's R7RS/R6RS modes consist of a great many separate
libraries, each of which is compiled into multiple files that
must be able to find each other.  Those files use absolute paths
to find each other.  That means you can't move those files after
you have compiled the R7RS/R6RS runtime system.  It also means
we can't supply Petit Larceny's R7RS/R6RS modes in pre-compiled
form.  You have to compile the R7RS/R6RS libraries yourself,
as described in Section 2.5 of Larceny's user manual.

If you don't need to install both Petit Larceny and native
Larceny on your machine, you can install Petit Larceny just as
you'd install native Larceny, and then compile Petit Larceny's
R7RS/R6RS libraries.

If you want to install both Petit Larceny and native Larceny on
the same machine, we suggest you do what we do on Linux:

    unpack both pre-built distributions
    move (don't copy!) the unpacked directories to /usr/local/lib
    create /usr/local/lib/larceny as a symbolic link
        pointing to the native Larceny directory
    create /usr/local/lib/petit as a symbolic link
        pointing to the Petit Larceny directory
    copy the executable larceny script to /usr/local/bin/larceny
    copy the executable larceny script to /usr/local/bin/petit
    edit /usr/local/bin/larceny to make its LARCENY_ROOT
        point to /usr/local/lib/larceny
    edit /usr/local/bin/petit to make its LARCENY_ROOT
        point to /usr/local/lib/petit
    in the Petit Larceny directory, compile the R7RS/R6RS system
        as described in Section 2.5 of Larceny's user manual

With operating systems other than Linux, the symbolic links
might not work, in which case you can just move the appropriate
directories to /usr/local/lib/petit and /usr/local/lib/larceny
(or to wherever you want those directories to live).


The scheme-script feature:

Larceny is one of the few implementations of R6RS Scheme that
provides the scheme-script feature proposed by the R6RS editors,
but other implementations may define their own scheme-script.  If
you want Larceny to execute your Scheme scripts, then you should
use the which command to make sure Larceny's scheme-script comes
before any others in your execution path.  (By the way, Larceny's
scheme-script feature now executes programs in R7RS mode rather
than R6RS.  Because Larceny's implementation of the R7RS acts as
a superset of the R6RS standard, all programs that run in R7RS
mode should also run in R6RS mode, but the reverse is not true.)


Windows and DEP:

Larceny will not run if the DEP feature of Windows is set to
AlwaysOn.  To set the DEP feature to OptOut, which we recommend,
someone with administrative privileges must do the following:

    Click on the Start icon
    Type "cmd" into the search box.
    In the list of search results, right click the "cmd" program.
    Choose "Run as administrator".
    When asked whether you want to allow the program to make
        changes to this computer, answer Yes.
    Type the following command:

        bcdedit.exe /set nx OptOut

    Restart Windows.
