Building Larceny 21 December 2007 WHAT YOU NEED If you want to recompile the Scheme sources entirely from source, you will need a Scheme system to host the Larceny build process: MzScheme 37x or Larceny itself [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. Get the Larceny development environment working. 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 ] 'string-rep: ${STREP}) > (build-config-files) ; [3] > (load-compiler) 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 ::= 'mzscheme | 'larceny | '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 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.) The optional 'native flag will build native Larceny (SPARC) on Solaris; 'sassy 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 [4]. 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-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. On Native Larceny (SPARC): % ./larceny.bin -stopcopy -- src/Build/sparc-larceny-heap.fasl > (exit) % ./larceny.bin -stopcopy -- src/Build/sparc-twobit-heap.fasl > (exit) % cp larceny twobit 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 *NIX: % cp larceny twobit On Windows: > copy larceny.bat twobit.bat On Petit Larceny: % ./petit-larceny.bin -stopcopy -- src/Build/petit-larceny-heap.sch > (exit) % ./twobit.bin -stopcopy -- src/Build/petit-twobit-heap.sch > (exit) You can now run "./larceny" or "./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.96 "Fluoridation" (...) > (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. [2] http://sourceforge.net/projects/nasm For the 'sassy backend on 'win32, Microsoft's development tools and NASM must both be in your search path. [3] 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. [4] 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. [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.