Building and using Petit Larceny
23 November 2004 / lth


HOW TO BUILD PETIT LARCENY AND USE THE BUILD ENVIRONMENT

General build instructions are in HOWTO-BUILD.  There may also be
platform specific instructions for your platform.  Have a look at the
files HOWTO-WIN32, HOWTO-MACOSX, and HOWTO-UNIX for status on the
various ports and special instructions for building on specific systems.


BUILDING AN APPLICATION

It is possible to create an application that contains more compiled code
than the standard heap image.  In this case, the object code for your
program is linked statically into the Larceny executable but the
program's data are available in code-less FASL files.  This may seem a
little strange and unnecessary but it simplifies things overall, because
scripts for native Larceny will work unaltered in Petit Larceny.

    > (build-application "petit" <list-of-lop-files>)

(On Win32 the executable name would be "petit.exe".)  The command
above generates an executable called "petit" and a bunch of FASL
files.  For convenience, one can just catenate all these FASL files
into a single FASL file that can be loaded with one command, making it
easier to package a lot of compiled code into an application-like
bundle.

Be aware that BUILD-APPLICATION will create a working file called
"exename.c" in the current directory, for whatever name you choose for
the executable ("petit.c" in the example above).  Do be sure not to
have a file "exename.lop" in the list of files passed to
BUILD-APPLICATION, the .c file generated from the .lop file will be
clobbered and you will see strange link errors.


COMPILING TWOBIT

A facility built on BUILD-APPLICATION is called BUILD-TWOBIT:

    > (build-twobit)

The BUILD-TWOBIT command compiles all the Twobit source files and
creates an executable "twobit" ("twobit.exe" on Windows; "twobit.app"
on MacOS X) that contains the code for Twobit, as well as FASL files
for all these files.

If you build Twobit using BUILD-TWOBIT, and then start "twobit" and
follow the directions above (loading "Util/petit-unix-el.sch", say, and
then running LOAD-COMPILER), you will have a development environment
with a compiled compiler, suitable mainly for compiler development.

See a later section for how to turn Twobit into a standalone compiler
for other kinds of development.


BUILDING STANDARD HEAP IMAGES

The two standard heap images (described in HOWTO-BUILD) are created by
first building executables that contain their compiled code, then
dumping heaps containing additional data.

Util/petit-r5rs-heap.sch

  Creates a minimal heap image called petit-r5rs.heap: like the heap
  generated by BUILD-HEAP but with a pretty-printer installed.

  To set up for this script, evaluate

    > (build-r5rs-files)

  in the development environment to compile the pretty-printer and
  create an executable called "petit-r5rs".

  Now run:

    petit-r5rs -stopcopy petit.heap

  and then load Util/petit-r5rs-heap.sch; this will create a new heap
  image petit-r5rs.heap that can be used with the petit-r5rs
  executable.

Util/petit-larceny-heap.sch

  Creates a maximal heap image called petit-larceny.heap: it contains
  the compiler, many useful procedures and macros, the debugger, the
  pretty printer, and a foreign function interface.

  In addition, the internals of the compiler are hidden, and the
  interpreter and the compiler share macro definitions.  Thus this
  heap image is easy to use both for interactive work and compilation,
  and macros loaded interactively will be applied to all files
  compiled subsequently.

  To set up for this script, evaluate

    > (build-larceny-files)

  in the development environment to compile the compiler; once it has
  been loaded by the script it takes care of compiling everything else.

  Now run:

    petit-larceny -stopcopy petit.heap

  Then load the development environment in the normal manner, loading
  first a file from Util/ and then evaluating:

    (LOAD-COMPILER 'RELEASE)

  Finally, load Util/petit-larceny-heap.sch.  This script will create
  a new heap image petit-larceny.heap that can be used with the
  petit-larceny executable.


COMPILING AND LOADING YOUR OWN PROGRAMS

On some systems it is possible to load compiled Scheme code
dynamically.  A driver routine called COMPILE-FILES compiles a group
of Scheme files into a single shared object and a group of code-less
FASL files.  Loading the FASL files with LOAD will load and link the
shared object:

    > (compile-files '("fib.sch") "fib.fasl")
    > (load "fib.fasl")
    > (fib 10)
    55

A single C source file is generated from all the Scheme source files in
the input list.  Be aware that some C compilers have problems with very
large files at high optimization settings.

On some systems the run-time system must be compiled as a shared library
in order for dynamic loading to work.  See HOWTO-UNIX.


BOOTSTRAPPING

There is an *example* Makefile called 'bootstrap.mak' that you can use
to build Petit Larceny from C sources.  This requires that you cross
compile to C on some other host.  Cross compilation is supported in
the same build environment as described above; for example, the file
"Util/petit-macosx-on-win32.sch" was used to cross-compile to C for
MacOS X from a Win32 system.


INSTALLING TWOBIT ON YOUR SYSTEM

Installing Twobit outside the Larceny build directory is complicated,
and it requires that Petit Larceny be able to dump a heap image on your
system, which generally means that a program must always be loaded at
the same address every time it is executed.  Systems that do not obey
this rule include the old MacOS and probably most operating systems on
machines without paged memory support -- handhelds, phones, and other
embedded-type devices.

Anyway, to create a standalone compiler do the following:

  (1) Create directories /usr/lib/larceny/include and /usr/lib/larceny/lib
  (2) In the development directory, start twobit:
         ./twobit -stopcopy
      and load the development environment in the normal manner
      with LOAD-COMPILER.
  (3) Incant
         > (install-twobit "/usr/lib/larceny")
         > (dump-interactive-heap "twobit.heap")
      This copies a bunch of files to your new directories and creates
      a heap image containing twobit, but also changes some global
      settings internally about where twobit will look for include files
      and libraries
      [Hint: you need write access to that directory.]
  (4) Exit.  There should be a file twobit.heap in the current
      directory.
  (5) Test it by starting the twobit executable with twobit.heap
      as its argument, then evaluate
         > COMPILE313
      The REPL should print #<PROCEDURE compile313>.
  (6) Exit.  Copy the twobit executable and twobit.heap as well as
      petit.heap to /usr/lib/larceny, then create another script in 
      /usr/bin called "twobit" which contains
        /usr/lib/larceny/twobit /usr/lib/larceny/twobit.heap
      You should now be able to type 'twobit' anywhere, and you should
      be able both to compile to FASL and to create entire applications
      using BUILD-APPLICATION.


--- Local Variables: ---
--- mode: text ---
--- indent-tabs-mode: nil ---
--- End: ---
