= Common Larceny User Manual

The most recent revision of this manual can always be found at
http://www.ccs.neu.edu/home/will/Larceny/CommonLarceny/user-manual.html[].

== Background

=== What Is Common Larceny?

Common Larceny is a variant of Larceny, a simple and efficient run-time system
for Scheme. It is built to run on the ECMA Common Language Infrastructure 
(CLI). In Common Larceny, Scheme code is compiled to Common Intermediate
Language, and is then assembled into bytecode for execution by native 
just-in-time (JIT) compilers.

When used in conjunction with Microsoft's .NET Framework, which includes an 
implementation of the CLI, the Common Language Runtime, Common Larceny provides
an interface to the .NET Framework class library, allowing developers to take 
full advantage of dozens of predefined classes designed to facilitate 
application development.

/////////////////////////////////////
This section needs to be filled in

=== Why Was Common Larceny Developed?

???
/////////////////////////////////////

=== Who Developed Common Larceny?

Common Larceny was initially developed between 2002 and 2004 by Ryan Culpepper,
Joe Marshall, Dale Vaillancourt, and others under the direction of Will Clinger
and Matthias Felleisen at Northeastern University. Felix Klock, Jesse Tov, and 
Chris Burns have contributed to the latest development of Common Larceny.

== Obtaining Common Larceny

The easiest way to start using Common Larceny is to download a binary 
distribution bundle. Each bundle contains a Common Larceny executable file, 
and the libraries required by the executable. If you'd like to build from 
source, you can do that, too. However, first you must ensure that your system 
meets certain requirements.

=== System Requirements

Currently, this software is distributed for Windows on Intel x86 machines, 
Microsoft .NET Framework 2.0.

Common Larceny 'may' work on other platforms (e.g. Mac OS X
with the Mono Framework 1.1) but we do not yet provide support for
those systems.

==== Common Language Infrastructure

Common Larceny requires the 
http://www.ecma-international.org/publications/standards/Ecma-335.htm[
Common Language Infrastructure]. It is known to work with the 
http://www.microsoft.com/net/[Microsoft .NET Framework] implementation.
In the past, some releases of Common Larceny have worked with
http://www.mono-project.com/downloads/[Mono] also, but we have
not tested the current release with Mono.
It is also conceivable that Common Larceny might work with
http://www.dotgnu.org/pnet.html[DotGNU Portable.NET] or
http://msdn.microsoft.com/net/sscli/[Microsoft Shared Source CLI (Rotor)],
but it hasn't been tried.

When using the Microsoft .NET Framework implementation of the CLI, you only 
need the .NET redistributable package, but the .NET SDK contains a much richer 
set of utilities and documentation.

==== Environment Variables

Common Larceny requires you to have the environment variable `LARCENY_ROOT`
defined as the root directory of your larceny distribution, e.g. `C:\Larceny\`.

For more information on managing environment variables in Windows XP, see 
http://support.microsoft.com/kb/310519[Microsoft Knowledge Base Article 
310519].

=== Binary Distribution

Choose one of these binary distribution bundles:

 * http://www.ccs.neu.edu/home/will/Larceny/CommonLarceny/LarcenySDK.zip[
   Larceny SDK (Zip bundle)]
 * http://www.ccs.neu.edu/home/will/Larceny/CommonLarceny/LarcenySDK.tgz[
   Larceny SDK (Gzipped TAR file)]

The `CommonLarceny.exe` executable is a console program. When it is started, 
it will print a number of diagnostic lines and then enter a `read-eval-print`
loop.

_Note:_ The distributed bundles also include the `Larceny.exe`
executable. This is not a standalone application so no attempt should be 
made to run the file on its own.

=== Source Distribution

If you would like to build Common Larceny from source, download the source 
distribution
(http://www.ccs.neu.edu/home/will/Larceny/LarcenyReleases/\
larceny-0.93-src.tar.gz[Gzipped TAR File]). Once you have downloaded the 
source distribution, the instructions below should enable you to build 
Common Larceny yourself.

== Building from Source

=== Setup

To build Common Larceny from source, you will need a working version
of regular Larceny.  (You might be able to use Petite Chez or MzScheme
instead, but they have not been tested recently and are not recommended.)

You will also need to have a couple of executable programs available in your 
path. You may need to edit `src\Rts\DotNet\makefile` to use appropriate programs
on your system.

 * You will need a working version of `make` or `nmake`. 
 * You will need the Intermediate Language Assembler (ILAsm). Usually, 
   `ilasm.exe` is located under 
   `\Windows\Microsoft.NET\Framework\v?.?.?\ilasm.exe`.
 * You will need some version of a C preprocessor. Visual Studio comes with 
   `cl.exe`, the Microsoft C/C++ Compiler, which has a command-line 
   switch that enables it to preprocess files. Alternatively, you can use 
   `cpp`. See options for `larceny-setup` below.

Once you have ensured the above requirements are met, start your host Scheme
system, and change to the root of the Larceny distribution, if necessary. The 
`current-directory` procedure should do the trick. Then, load the 
configuration file for Common Larceny: `(load "src/Build/dotnet.sch")`

Next, you need to inform the build tool of the specifics of the host
environment. Invoke `larceny-setup` with three or four arguments:

  > (larceny-setup <host-scheme> <os> <endianness> <codegen-options>)

where: 

   - `<host-scheme>` is a string corresponding to your Scheme system; it
     must match one of the subdirectories of Compat, eg `"Petite"`,
    `"MzScheme"`, `"Larceny"`
   - `<os>` is a symbol, one of `'win32`, `'unix`, `'macosx`
   - `<endianness>` is a symbol, one of `'little`, `'big`
   - `<codegen-options>` is an optional combination of the following symbols:
     * `$$'mono$$` - to build Larceny using the 'Mono' implementation of the 
       CLI,
     * `$$'rotor$$` - to build Larceny using the 'Rotor' implementation of the 
       CLI,
     * `$$'debug$$` - to build a debugged version of the runtime-system, and
     * `$$'use-cl$$` - to use the 'Miscrosoft C/C++ Compiler', cl.exe, to 
       preprocess certain files needed to build the runtime-system. Without 
       this flag, `cpp` will be used.

For example, to build under Larceny on a Windows machine, using Microsoft's 
C/C++ Compiler, you would use:

  > (larceny-setup "Larceny" 'win32 'little 'use-cl)

After setting up the environment for building Larceny, evaluate the following:

  > (build-config-files)
  > (load-compiler)

The first procedure builds the config files (`Rts\\*.cfg`), and the second 
loads the Twobit compiler. You can't load the compiler until after you have 
run `larceny-setup` and `build-config-files`.

=== The .NET Heap

The next step involves building the .NET heap. After loading the compiler in 
the previous step, simply evaluate: 

  > (make-dotnet-heap)

This procedure loads the Scheme files needed to build the .NET heap and 
compiles and assembles their contained code to MSIL code in three stages. First
it compiles Scheme code to MacScheme code (`.lap` files), then assembles the
MacScheme code into s-expressions representing MSIL code, (`.lop` files), and 
finally dumps these s-expressions as raw MSIL code (`.code-il` files).

Evaluating `make-dotnet-heap` produces a file in the root of the Larceny 
distribution, `dotnet.heap.exe`. This is the executable file that you will run
to load Common Larceny. In bundled distributions, we rename this to 
`CommonLarceny.exe`.

=== The Runtime System

Lastly, you will need to build the runtime system:

  > (build-runtime-system)

This procedure will create `Scheme.dll` in the `src\Rts\DotNet` directory. The
`Scheme.dll` library contains the classes that make up the Common Larceny
runtime. Copy `Scheme.dll` into the root directory of the Larceny Distribution.

You should now have a working copy of Common Larceny in your `LARCENY_ROOT`
directory. Rename `dotnet.heap.exe` to `CommonLarceny.exe` (not necessary but
suggested) and run it to enter the interactive `read-eval-print` loop. 

[[X1]]
=== CompileOnLoad

Running the `CommonLarceny.exe` executable alone loads Common Larceny as an
interpreted Scheme system. It is also possible to load Common Larceny so that
it compiles Scheme code upon load. This creates slightly longer load times, 
but can improve execution times by quite a bit.

To build the fast-loading (`.fasl`) and `.exe` files used to invoke the 
CompileOnLoad version of Common Larceny, first build the heap and the
runtime-system as described above.  Then run:

 > (build-larceny)

This will create new files in the root of your Common Larceny distribution, 
namely `Larceny.exe` and `Larceny.fasl`. These files are required to run the 
CompileOnLoad version of Common Larceny.

To use the CompileOnLoad version of Common Larceny, invoke the runtime with: 

 CommonLarceny Larceny.fasl.

=== Compiling the R6RS and ERR5RS Runtime Libraries

If you want to use Common Larceny to run R6RS or ERR5RS programs,
then you will need to compile the R6RS runtime system and the R6RS
standard libraries.

To do so, first remove any and all `.fasl` and `.slfasl` files from
the `lib/R6RS` directory and its subdirectories.  Then:

    CommonLarceny Larceny.fasl
    > (require 'r6rsmode)
    > (larceny:compile-r6rs-runtime)

This will take a very long time, and will print numerous messages
to the screen about files not found.

== Using Common Larceny

Common Larceny can be run in any of three modes:

 * r5rs    --  default read/eval/print loop for R5RS programs
 * err5rs  --  read/eval/print loop for debugging R6RS programs
 * r6rs    --  batch-mode execution of R6RS programs

=== R5RS Mode

To run Common Larceny in its default R5RS mode, just run the
`CommonLarceny.exe` like this:

    CommonLarceny

To compile files as they are loaded, add `Larceny.fasl` to the
command line, like this:

    CommonLarceny Larceny.fasl

=== ERR5RS Mode

To run Common Larceny in ERR5RS mode, add the `--err5rs`
command-line option, like this:

    CommonLarceny Larceny.fasl --err5rs

=== R6RS Mode

To run R6RS programs in Common Larceny, you will need to specify
the `--r6rs` and `--program` command-line options, and may also
need to use the `--path` option.

Suppose, for example, that you want to run an R6RS program named
`myprogram.sps` that may use some of the standard R6RS libraries,
some of the ERR5RS/R6RS libraries provided by Common Larceny, and
some of the ERR5RS/R6RS SRFI libraries provided by Common Larceny,
but does not define or use any other libraries.  Then you can run
the program like this:

    CommonLarceny Larceny.fasl --r6rs --program myprogram.sps

If the program defines its own libraries, or uses libraries other
than those provided by Common Larceny, then you will need to tell
Common Larceny where those libraries reside by using the `--path`
command-line option or the `LARCENY_LIBPATH` environment variable,
both of which are documented in the Larceny User Manual, which is
online at http://larceny.ccs.neu.edu/doc/

=== Compiling Code to Run within Common Larceny

The same compiler that is used to compile files as they are loaded
can also be used to compile files ahead of time, which makes them
load faster.

Compiling a file with Common Larceny is now done the same way as
in native Larceny.  See the Larceny User Manual, which is online
at http://larceny.ccs.neu.edu/doc/

Suppose, for example, that you want to compile two files that
contain R5RS code, `even.sch` and `odd.sch`.  You can compile
them as follows:

    CommonLarceny Larceny.fasl
    > (compile-file "even.sch")
    > (compile-file "odd.sch")
    > (exit)

After the files have been compiled, you can load them into
a new session of Common Larceny by listing the names of the
compiled files on the command line, like this:

    CommonLarceny Larceny.fasl even.fasl odd.fasl

You can also use the `load` procedure to load the compiled files
into a session of Common Larceny that is already running:

    CommonLarceny Larceny.fasl
    > (load "even.fasl")
    > (load "odd.fasl")

Once compiled, a compiled file cannot be moved because its
absolute path name is wired into the compiled file.  This
restriction may be removed in some future version of Common
Larceny.
