]Building Larceny


WHAT YOU NEED

Most users of Larceny will never need to build Larceny from source,
and can ignore this documentation.

If you want to recompile the Scheme sources entirely from source, you
will need the source code plus a Scheme system that can host Larceny's
build process.  At this time, that means you need to start with a
binary distribution of Larceny [1].  See README-FIRST.txt for more
details.

If you want to build Larceny or Petit Larceny entirely from source,
you will also need a C compiler (such as gcc).  For x86-32 targets,
you will also need the NASM assembler [2] and the necessary 32-bit
library packages [3].

To build Common Larceny, see the Common Larceny documentation in
doc/CommonLarceny/user-manual.txt.


WHAT TO DO

Building Larceny has four major steps:

1. Set up the Larceny development environment.

Run your host Scheme (a prebuild version of Larceny [1]), and change
to the root directory of the Larceny tree.

    > (load "setup.sch")
    > (setup 'scheme: ${SCHEME} 'host: ${HOST} [ 'sassy | 'common ]
             'string-rep: ${STREP})

The call to setup (above) has several options that let you
declare which implementation of Scheme you want to use for
the build process (SCHEME) and which OS you are using as
both the host and target of the build (HOST):

        SCHEME      ::= 'larceny | 'mzscheme | 'petite | 'chez
        HOST        ::= 'macosx | 'macosx-el | 'linux86 | 'win32 | 'linux-arm-el
        STRING-REP  ::= 'flat4  |  'flat1

The HOST option macosx-el is for Intel-based Macintosh computers.
The HOST option macosx is for PowerPC-based Macintosh computers.

The HOST option linux-arm-el is for most ARM-based Linux systems.

The optional 'sassy flag will build native Larceny (x86-32) on
Linux, Windows, or MacOS X.  The 'sassy flag is necessary if
you want to use dynamic loading on Win32, and is strongly
recommended for that operating system.  There are several
other optional flags that change the compiler's behavior [4].

The STRING-REP option determines the representation used
for strings.  The flat4 representation uses 4 bytes per
character, is the default on all versions of Larceny, and
is the only representation that can be used when building
Petit Larceny or Common Larceny.  The flat1 representation
of strings uses 1 byte per character, which limits it to
strings of Latin-1 characters.  Native Larceny for x86-32
can be built to use either the flat4 or flat1 representations;
be sure to perform a full build when switching from one
representation to the other.  At present, native Larceny
on ARM can only be built with the flat4 representation.

Some useful examples which are known to work:

To build native Larceny:
    > (setup 'scheme: 'larceny 'host: 'win32 'sassy 'always-source)
    > (setup 'scheme: 'larceny 'host: 'linux86 'sassy)
    > (setup 'scheme: 'larceny 'host: 'linux86 'sassy 'string-rep: 'flat1)
    > (setup 'scheme: 'larceny 'host: 'macosx-el 'sassy)

To build native Larceny on little-endian ARMv7 on any Linux
system an explicit target: is required to specify the floating
point ABI for the runtime [5]:

  > (setup 'scheme: 'larceny
           'host: 'linux-arm-el
           'target: 'linux-arm-el-hardfp 'native)

To build Petit Larceny:
    > (setup 'scheme: 'larceny 'host: 'linux86 'always-source)


2. Build Larceny components

After the development environment is setup, you should compile the core
system:

    > (build-config-files)              ; [6]
    > (load-compiler)
    > (build-heap)
    > (build-runtime)
    > (build-executable)

You will now have a working Larceny interpreter and minimal heap image.

To build a complete Larceny user system, including the Twobit compiler:

    > (build-larceny-files)

You may want the Twobit compiler development environment; on
Petit, you must build it separately:

    > (build-twobit)

After all that, it's time to exit from your host Scheme:

    > (exit)

For Windows, you'll need to mark the larceny.bin.exe as incompatible
with NX:

    editbin.exe /NXCOMPAT:NO larceny.bin.exe

Larceny will not run under Windows with DEP set to AlwaysOn, but
Larceny will run with DEP set to OptOut, OptIn, or AlwaysOff.


3. Create heap images

Step 2 above creates a bootstrap heap (petit.heap, arm.heap, or
sasstrap.heap).  To create the user and development heap images, exit
the host Scheme back to your command shell.  Then perform one of the
following three sets of commands (omitting those for twobit unless
you want the Twobit compiler development environment):

On IAssassin Larceny (Intel) [7]:

    % "./larceny.bin" -stopcopy -- src/Build/iasn-larceny-heap.fasl
    > (exit)

    % "./larceny.bin" -stopcopy -- src/Build/iasn-twobit-heap.fasl
    > (exit)

On Native Larceny (ARM):

    % ./larceny.bin -stopcopy -- src/Build/arm-el-hardfp-larceny-heap.fasl
    > (exit)

    % ./larceny.bin -stopcopy -- src/Build/arm-el-hardfp-twobit-heap.fasl
    > (exit)

On Petit Larceny:

    % ./petit-larceny.bin -stopcopy -- src/Build/petit-larceny-heap.sch
    > (exit)

    % ./twobit.bin -stopcopy -- src/Build/petit-twobit-heap.sch
    > (exit)

Then, if you want the Twobit compiler development environment:

  On *NIX:
    % cp larceny twobit

  On Windows:
    > copy larceny.bat twobit.bat

On Windows machines, you will probably need to tell DEP to allow
larceny.bin to opt-out.

You can now run "./larceny" (and maybe "./twobit") in its default
-r5rs mode, but the -r7rs and -r6rs modes won't work until you
do step 4.



4. Compile the R7RS/R6RS/SRFI standard libraries.

Run Larceny in its default -r5rs mode, and compile the
R7RS/R6RS/SRFI standard libraries as follows.

    % ./larceny
    Larceny v0.98 "Funny in the Head" (...)

    > (require 'r7rsmode)
    > (larceny:compile-r7rs-runtime)
    > (exit)

Larceny should now run correctly in all modes.  If you want
to use Larceny to run Scheme scripts on a Unix system, then
you should make sure that the Larceny root directory is in
your execution path, ahead of any other directories that
may contain a file named scheme-script.



----------------------------------------------------------------

NOTES

[1] For the build process, we strongly recommend using a prebuilt
version of Larceny itself.  MzScheme 37x once worked, and might
work still.  In the past, several other implementations of Scheme
could be used for the build process, but they haven't been tested
lately and aren't likely to work any more.  MzScheme v4.x.x might
work, but we regard Larceny's support for v4.x.x as experimental;
see src/Compat/PLT-R5RS/README.

[2] http://www.nasm.us/

For Windows and Ubuntu Linux, we use NASM version 2.  For MacOS X,
we use NASM version 0.98.40, which is installed with the Apple
Developer command line tools.

For the 'sassy backend on 'win32, Microsoft's development tools
(including NMAKE) and NASM must both be in your search path.

[3] On Linux machines, you may need to do the following:

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

On MacOS X machines, you may need to install the Apple Developer
command line tools.

On Windows, the Microsoft Visual Studio Community 2013 download
contains everything you need (and a lot more than you need).  We
use the "VS2013 x86 Native Tools Command Prompt".

[4] Larceny requires CPU support for floating point instructions.
Several sub-ABIs exist for floating point on the ARM architecture.
The two APIs are known as "soft" (hardware instructions are generated but
the calling convention is as for software floating point; gcc calls
this "softfp") and "hard" (hardware instructions are generated and the
calling convention uses FPU registers).  Larceny needs to know the ABI
when it compiles C code, and the target name therefore contains either
"softfp" or "hardfp".  Generally the operating system sets the ABI and
all programs on the system use it; check your local documentation.

[5] Some other potentially useful flags, given optionally at the end of
the call to setup:

    'code-cov
        This enables loading of the instrumented files generated by the
        stcov tool when loading the compiler. Use this to test code
        coverage of the compiler testsuite

    'rebuild-code-cov
        This causes the stcov files to be regenerated before loading.
        This implies 'code-cov.

    'always-source
        Don't load compiled fasl files when loading the development
        environment under Larceny.  This is useful under Petit Larceny
        if the executable gets out of sync with the fasl files.

    'nasm
        Build a Petit Larceny which targets the NASM assembler (IA32)
        rather than Standard C.  This option is deprecated in favor of
        the Sassy backend; indeed, we suspect that it no longer builds
        correctly now that we have added the string-rep: parameter to
        setup.

[6] This is only strictly necessary the first time and when the options
given to setup have changed, but it should be safe to do every time.

[7] The quotation marks around "./larceny.bin" are a uniform syntax that
works on both Microsoft Windows and UNIX-like shells.  The reason is
left as an exercise for the reader.

