localbuilds.adoc

Local builds

Introduction

This guide explains how to make your own local builds of various Scheme implementations. That’s useful if you want to:

• use pre-release versions to get the very latest features

• use custom build options

• use an operating system that does not have a ready-to-run package of the Scheme you want

Installation prefix

On Unix-like operating systems, programs intended for all users are usually installed into /usr or /usr/local.

For your own personal use, an emerging convention is to install into ~/.local, i.e. a directory named .local under your home directory. This guide adopts that convention.

Most Schemes have a prefix option in their build system that can be used to set the installation prefix to any directory you like. Hence, if you want something different than ~/.local, just change the prefix.

Chibi-Scheme

Implementation language:	C interpreter and OS interface, Scheme libraries
Version control:	Git
Build system:	GNU make
Full build with bootstrap:	2 minutes
Documentation:	doc/chibi.scrbl (Installation section)

git clone https://github.com/ashinn/chibi-scheme.git
cd chibi-scheme
make PREFIX=$HOME/.local
make install PREFIX=$HOME/.local

To run installed chibi you need to setup $CHIBI_MODULE_PATH (running uninstalled does not need this because chibi can detect in that case).

export CHIBI_MODULE_PATH=$HOME/.local/share/chibi:$HOME/.local/lib/chibi

You may need to adjust $LD_LIBRARY_PATH as well because chibi-scheme binary does not have a default path for libchibi-scheme.so (you should see "error while loading shared libraries" if it’s the case)

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/.local/lib

Testing uninstalled versions

./tools/chibi-run

Troubleshooting

Chibi requires GNU make. On BSD systems, use gmake in place of make.

When you first run make it creates the file include/chibi/install.h. The constant sexp_default_module_path in that file is seeded from the PREFIX you gave to make. If you later run make with a different PREFIX that .h file will not be regenerated and will have a stale library path. Even make clean won’t get rid of it. The solution is make cleaner.

CHICKEN

Implementation language:	Scheme, some C
Version control:	Git
Build system:	GNU make
Full build with bootstrap:	7 minutes
Documentation:	README (Bootstrapping section)

The CHICKEN project occasionally publishes prerelease development snapshots which you can use to bootstrap from when you want to build from Git.

These snapshots require just a C compiler and specifically GNU make. If you are on a system where make refers to BSD make, use gmake or gnumake instead of make in the command below.

To make things easy, there’s a script in the git repository which will perform the bootstrapping for you:

git clone git://code.call-cc.org/chicken-core
PLATFORM=linux ./scripts/bootstrap.sh

When the bootstrap script is done, it prints instructions on what to do next:

Now, build chicken by passing "CHICKEN=./chicken-boot" to make,
in addition to PREFIX, PLATFORM, and other parameters.

Let’s do just that:

make PLATFORM=linux CHICKEN=./chicken-boot PREFIX=$HOME/.local install

Testing uninstalled versions

LD_LIBRARY_PATH=. ./csi

Cyclone

Implementation language:	TBD
Version control:	Git
Build system:	make
Full build with bootstrap:	TBD
Documentation:	TBD

Cyclone requires an installed version to bootstrap. If you haven’t had any, get it from cyclone-bootstrap repository

git clone https://github.com/justinethier/cyclone-bootstrap.git
cd cyclone-boostrap
make PREFIX=$HOME/.local
make PREFIX=$HOME/.local install

Now you can build latest cyclone version, the steps are exactly the same:

git clone https://github.com/justinethier/cyclone.git
cd cyclone
make PREFIX=$HOME/.local
make PREFIX=$HOME/.local install

Gambit

Implementation language:	Scheme, with C for system interface
Version control:	Git
Build system:	GNU autotools & make
Full build with bootstrap:	30 minutes

The bootstrap process

Gambit requires a pre-built version of its gsc compiler in order to bootstrap itself. gsc is written in Scheme, then transpiled into C which is compiled into native executables using the system C compiler. The C files are committed into Gambit’s Git repository so that a builder does not necessarily need to obtain a binary executable of gsc to build Gambit on a new computer. It’s enough to obtain the Gambit Git repository and a C compiler.

The bootstrap compiler is an executable at the root of its source directory by the name gsc-boot. If gsc-boot does not exist, make tries to find a suitable compiler in the history of the local git clone. For this reason, a shallow clone (git clone --depth 1) of Gambit generally does not work.

The usual way to get Gambit going on a new machine is to first install the latest release version, then use that to bootstrap the latest git master.

git clone https://github.com/gambit/gambit.git
cd gambit
./configure --prefix=$HOME/.local
make
make modules
make install

Testing uninstalled versions

gsc/gsc ...
gsi/gsi ...

Performance

Parallel builds

make -j can significantly speed up Gambit builds if you have a fast multi-core CPU and lots of RAM.

Optimized single-host build

./configure --enable-single-host generates a version of Gambit on which a good C compiler is able to do whole-program optimization. The resulting Gambit binaries can be significantly faster for performance-sensitive software. However, building Gambit this way takes a lot longer and requires more than a gigabyte of RAM.

For pedestrian Scheme code there is little to no perceptible speed difference, so a non-single-host build is fine. Even a non-single-host Gambit is easily one of the fastest Scheme implementations available.

Pre-packaged binaries of Gambit are generally single-host builds.

GCC vs clang

GNU’s gcc compiler builds Gambit significantly faster than LLVM’s clang compiler. Once Gambit has been built, there can be also substantial speed difference (about 2x in some cases) between the resulting executables.

On some operating systems, notably MacOS, the gcc command actually runs clang (whose command-line interface is largely compatible with GNU gcc). You can check this with gcc --version: the output should say LLVM if it’s actually clang.

On MacOS, you can install the real GNU GCC from Homebrew with:

brew install gcc

Homebrew installs GCC as gcc-9 (where 9 is GCC’s major version number). You can find the precise command name with:

brew list gcc | grep -E '/bin/gcc-[0-9]+$' | xargs basename

You can set the compiler used to build Gambit like so:

./configure CC=gcc-9

Troubleshooting

Sometimes big changes are made to Gambit which break your build, causing compiler errors (or in rare cases, a crashing gsc or gsi executable). In that case, try deleting the boot directory and the gsc-boot executable within Gambit’s source directory (rm -rf boot/ gsc-boot). That forces make to do a full bootstrap. Beware that this can take 30 minutes or more.

Gauche

Implementation language:	C and Scheme
Version control:	Git
Build system:	GNU autotools & make
Full build with bootstrap:	5 minutes
Documentation:	HACKING.adoc

Gauche requires the latest released version installed before you can build from Git repository. Follow the documentation link below to get the tarball and install. Remember to add --prefix when you configure:

# Browse http://practical-scheme.net/gauche/download.html
tar -xf Gauche-0.9.9.tgz
cd Gauche-0.9.9
./configure --prefix=$HOME/.local
make
make install

After this, make sure "gosh" is available. If not adjust $PATH for the current shell:

export PATH=$PATH:$HOME/.local/bin

Now you can build from Git, the steps are almost identical as before, except the new step ./DIST gen.

git clone https://github.com/shirok/Gauche.git gauche
cd gauche
./DIST gen
./configure --prefix=$HOME/.local
make
make install

Testing uninstalled versions

src/gosh -ftest

Gerbil

Implementation language:	TBD
Version control:	Git
Build system:	Scheme
Full build with bootstrap:	TBD
Documentation:	doc/guide/README.md and .travis.yml

Gerbil requires latest(?) Gambit Scheme installed. See above for more instructions. After that the build instructions are quite simple.

git clone https://github.com/vyzo/gerbil.git
cd gerbil/src
./build.sh stage0
./build.sh stage1 final
./build.sh stdlib
./build.sh lang
./build.sh tools

Note that because parallel builds are not supported and build.sh simply rebuilds everything. If you make changes in one part, stdlib for instance, just run build.sh for that part only. Otherwise it make take a long time.

Note sure about installation. Gerbil documents seem to encourage running directly from source. The binaries are bin/gxi and bin/gxc.

Guile

You may need to install required packages. See README for details.

git clone git://git.sv.gnu.org/guile.git
cd guile
./autogen.sh
./configure --prefix=$HOME/.local
make
make install

Testing uninstalled versions

meta/guile

Larceny

Implementation language:	Scheme
Version control:	Git
Build system:	Scheme and gcc
Full build without bootstrap:	3 minutes
Documentation:	doc/HOWTO-BUILD and doc/HOWTO-INSTALL

To build Larceny you need a Scheme system that can host Larceny. The easiest option is the prebuilt Larceny from http://www.larcenists.org/download.html if you don’t have Larceny installed.

The below build instructions are for linux on x86, taken from doc/HOWTO-BUILD. See that document for more details. The instructions are made for copy-pasting (or even put in a script and just run)

tar -xf larceny-1.3-bin-native-ia32-linux86.tar.gz
git clone https://github.com/larcenists/larceny.git
cd larceny
../larceny-1.3-bin-native-ia32-linux86/larceny <<EOF
(load "setup.sch")
(setup 'scheme: 'larceny 'host: 'linux86 'sassy)
(build-config-files)
(load-compiler)
(build-heap)
(build-runtime)
(build-executable)
(build-larceny-files)
(build-twobit)
(exit)
EOF
./larceny.bin -stopcopy -- src/Build/iasn-larceny-heap.fasl <<EOF
(exit)
EOF
./larceny.bin -stopcopy -- src/Build/iasn-twobit-heap.fasl <<EOF
(exit)
EOF
# At this point, you can delete the prebuilt binaries
cp larceny twobit
./larceny <<EOF
(require 'r7rsmode)
(larceny:compile-r7rs-runtime)
(exit)
EOF

At this point you can just use larceny directly without installing (e.g. adjust $PATH to search for larceny script). See doc/HOWTO-INSTALL if you really want to install it.

Testing uninstalled versions

./larceny

Sagittarius

Implementation language:	C and Scheme
Version control:	Git
Build system:	cmake & make
Full build with bootstrap:	TBD
Documentation:	README.md and HACKING

Sagittarius requires the latest released version installed before you can build from Git repository. Follow the documentation link below to get the tarball and install. Remember to add prefix when you run cmake:

tar -xf sagittarius-0.9.5.tar.gz
cd sagittarius-0.9.5
cmake -DCMAKE_INSTALL_PREFIX:PATH=$HOME/.local .
make
make install

Now you can build from Git, the steps are almost identical as before except the new step ./dist.sh gen:

git clone https://bitbucket.org/ktakashi/sagittarius-scheme.git
cd sagittarius-scheme
./dist.sh gen
cmake -DCMAKE_INSTALL_PREFIX:PATH=$HOME/.local .
make
make install

STklos

Implementation language:	C and Scheme
Version control:	Git
Build system:	GNU autotools & make
Full build with bootstrap:	5 minutes
Documentation:	HACKING.md

git clone https://github.com/egallesio/STklos.git stklos
cd stklos
./configure --prefix=$HOME/.local
make
make install

Troubleshooting

If you made changes to the Scheme code (or pulled changes from Git) and they are not being propagated to the final executable when you run make, try touch lib/boot.stk.