Building Larceny
18 August 2009


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: either Larceny itself (recommended) or MzScheme 37x [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].

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 (either another Larceny or MzScheme), and change to
the root directory of the Larceny tree.

    > (load "setup.sch")
    > (setup 'scheme: ${SCHEME} 'host: ${HOST} [ 'native | '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 | 'solaris | 'linux86 | 'win32
        STRING-REP  ::= 'flat4  |  'flat1

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

The optional 'native flag will build native Larceny (SPARC)
on Solaris.

The optional 'sassy flag will build native Larceny (x86-32) on
Linux, Windows, or Mac OS 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 [3].

[FIXME: support for Common Larceny is just a prototype.]
The optional 'common flag will build Common Larceny for the CLR
on Windows, and might work for Mono on other operating systems.
If you are building Common Larceny, however, then you should
follow the steps outlined in doc/CommonLarceny/user-manual.txt
instead of the steps described below.

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
Common Larceny or Petit Larceny.  The flat1 representation
of strings uses 1 byte per character, which limits it to
strings of Latin-1 characters.  Native Larceny (SPARC or
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.  (In the
future, we expect to support yet another representation
of Unicode strings.)

Some useful examples which are known to work:

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

To build Petit Larceny:
    > (setup 'scheme: 'mzscheme 'host: 'linux86)
    > (setup 'scheme: 'larceny  'host: 'solaris)
    > (setup 'scheme: 'mzscheme 'host: 'macosx)


2. Build Larceny components

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

    > (build-config-files)              ; [4]
    > (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)



3. Create heap images

Step 2 above creates a bootstrap heap (petit.heap, sparc.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 Native Larceny (SPARC):

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

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

On IAssassin Larceny (Intel) [5]:

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

    % "./larceny.bin" -stopcopy -- src/Build/iasn-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

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



4. Compile the ERR5RS/R6RS standard libraries.

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

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

    > (require 'r6rsmode)
    > (larceny:compile-r6rs-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 recommend using a prebuilt version of
Larceny itself.  MzScheme 37x seems to work.  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 may work, but we regard Larceny's support
for v4.x.x as experimental; see src/Compat/PLT-R5RS/README.

[2] http://sourceforge.net/projects/nasm

Some versions of nasm may not work.  For Ubuntu Linux, we use
NASM version 2.05.01.  For MacOS X, we use NASM version 0.98.40.

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

[3] 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.

[4] 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.

[5] 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.
