Reference Manual

STklos documentation is provided with the source distribution. The reference manual is also available online as

Installing STklos

STklos can be fully installed from sources or it can also run it from a Docker image. Both methods

Running a Docker image

Running a pre-built image

To run a Docker image of STklos, you can choose the version you want to use from https://hub.docker.com/r/stklos/stklos. Version with the tag latest is built from the Git repository and can be unstable. Versions with a numbered tag correspond to the versions built from a stable release. Both images weight approximately 15Mb.

Example:

$ docker pull stklos/stklos:1.40          # grab the 1.40 version of STklos
$ docker run -ti stklos/stklos:1.40       # and run it
...
stklos> (version)
"1.40"
stklos> (exit)

If you want to run a script file against such an image, you can bind the directory containing your script to the /home directory (the current directory of the docker image). For instance if you have a script called hello.stk in your current directory, you can easily run it with a particular version of STklos:

$ cat hello.stk
(display "Hello, world!\n")
$ docker run -v$(pwd):/home -ti stklos/stklos:1.40 \
        stklos -f hello.stk
Hello, world!

Build your own Docker image

If you want to build your own Docker image, two docker files are provided in the ./etc/Docker directory of the source release. They contain the instructions to build each image.

The Scheme containers project

The Scheme containers project provides a large list of Docker images for various Scheme implementations. The project offers nearly 50 implementations which are all based on the same GNU/Linux distribution and an uniform interface. It is a great way to test different implementations and compare them on the same code. To run the STklos image built by this project:

$ docker pull schemers/stklos              # grab the latest version of STklos
$ docker run -ti schemers/stklos           # and run it

Installing from sources

STklos is configured/built thanks to the GNU autotools. Installing STklos is three (or four) step process:

  1. You first need to run the configure script. By default, this script will try to use the libraries installed on your system. When a library is absent, a version of the library embedded with the source distribution will be used.

    The main options of the configure script are

    • --prefix=PATH: place where the files will be installed (default to /usr/local)
    • --with-provided-gc: use the provided Boehm GC library
    • --with-provided-bignum: use the provided Bignum (GMPlite) library
    • --with-provided-regexp: use the provided Regexp (PCRE) library
    • --with-provided-ffi: use the provided FFI library
    • --enable-case-insensitive: be case insensitive by default as in R5RS
    • --enable-threads=TYPE: choose threading package (value can be ‘none’ or ‘pthreads’, the default)

    You can also choose the compiler and the compiler options to use for building STklos with the CC and CFLAGS parameters:

    $ ./configure --prefix=/opt --with-provided-gc CC=clang CFLAGS="-O3 -Wall"

    A summary will be printed at the end of the execution of the script as shown below:

    SUMMARY
    *******
                   System:  Linux-5.6.15-1-MANJARO
                  OS nick:  LINUX_5_6
                  OS type:  unix
          Install prefix :  /opt
               C compiler:  clang
        Compilation flags:  -O3 -Wall
                   Loader:  ld
           Thread support:  pthreads
         Case sensitivity:  true (by default)
    System libraries used:  libffi libpcre libgmp
       Compiled libraries:  libgc
  2. If everything is correct, you can just type make now at your shell prompt. Note that STklos supports parallel execution for faster builds. For instance, you can enter make -j 8 to build 8 recipes simultaneously.

  3. Optionally, you can type make tests to run some internal tests

  4. To install the version just compiled in the place you have chosen previously, type make install for a full install. The size of a full installation is approximately 6.5Mb (on a x86 64 bits architecture).
    On machines with a more limited space, you can use the following Makefile installation targets:

    • install-base to install only the VM and all the compiled Scheme files (size is ~2.0Mb). The installation is fully functional (except the help function which will yield an error).
    • install-base-no-strip is identical to install-base, except that the stklos binary is not stripped (this could be useful when cross compiling STklos or when generating packages with debug symbols).
    • install-sources to install the Scheme source files used whence building the system (adds ~1.5Mb to the installation)
    • install-doc to install the documentation (for the help command, manual pages, and reference manual in HTML and PDF formats). This adds ~3.0Mb) to the installation).

Note: make install is equivalent to make install-base install-sources install-docs

Running STklos

You can run STklos in a terminal from the command line. If you have the GNU library readline (or the Editline Library (aka libedit)) installed, you will be able to do line editing as in usual shells.

Using GNU Emacs as your IDE

GNU Emacs offers a wide range of functionality beyond text editing. In particular, it can be used as an IDE to build STklos programs.

There are two recommended tools for that purpose: 

Enjoy.