Documentation Files

STklos documentation is provided with the source distribution as well as online:

Installing STklos

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

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:2.10          # grab the 2.10 version of STklos
$ docker run -ti stklos/stklos:2.10       # and run it
...
stklos> (version)
"2.10"
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.

    • --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
    • --with-gmp-light: a synonym for --with-provided-bignum

    By default the following options are enabled, but can be disabled with the following configure options

    • --disable-threads: disable Posix threads support
    • --disable-control-fast-math: do not verify that parameters of fx/fl functions are correct fixnums/flonums
    • --disable-ffi: disable FFI (Foreign Function Interface) support

    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-18 CFLAGS="-O3 -Wall"

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

    SUMMARY
*******
                System:  Linux-6.10.9-arch1-1
               OS nick:  LINUX_6_10
               OS type:  unix
        Install prefix:  /opt
     C compiler binary:  clang-18
    C compiler version:  clang version 18.1.8
     Compilation flags:  -O3 -Wall
                Loader:  ld
        Thread support:  yes
           FFI support:  yes
 Control fx parameters:  yes
 System libraries used:  ffi (3.4.6) pcre2 (10.44) gmp (6.3.0)
    Compiled libraries:  gc
    STklos load prefix:  /opt
      Binary load path:  /opt/lib/stklos/2.10
      Scheme load path:  /opt/share/stklos/2.10
     Documentation dir:  /opt/share/doc/stklos/2.10
  Documentation update:  yes (since Asciidoctor is installed)

If this is correct, you can just type 'make' now at your shell prompt.
Otherwise, re-run 'configure' with correct options.

  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 18Mb (on a GNU/Linux x86 64 bits architecture). On machines with a more limited space, you can use the following Makefile installation targets:

    • install-base (or install-base-no-strip) permits to install the VM and all the compiled Scheme files. The installation is fully functional (except the help function which will yield an error, since the documentation is not installed). Size used is approximately 5Mb.
    • install-base-strip is identical to install-base, except that the symbols of the stklos binary stripped to save some disk space. Note that stripping the stklos executable could be a problem with dynamic loading on macOS, when cross compiling STklos or when generating packages with debug symbols). Approximate size of installation is nearly 4Mb.
    • install-sources to install the Scheme source files used whence building the system (adds ~3Mb 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 ~11Mb 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.