Importante notice: this documentation is pending update. Latest instructions can be found in current version's README.

0. Prerequisites

SchemeSpheres has been tested in GNU/Linux and OS X. You will need the following software installed:

Installing Gambit on Linux

Downloading the latest version and running the following commands should do:

cd gambit
./configure --enable-single-host --enable-c-opt
make -j4 from-scratch
make check
sudo make install

Installing Gambit on OSX

Gambit recommends using GCC instead of LLVM for compiling its source. We need to install it with Homebrew:

brew install gcc49

Now we can compile Gambit explicitly using GCC. Substitute with your GCC version.

cd gambit
CC=/usr/local/bin/gcc-4.9 ./configure --enable-single-host --enable-c-opt
make -j4 from-scratch
make check
sudo make install

Note: Even though Homebrew is a very convenient way of installing Gambit, unfortunately it changes the way Gambit's directories are organized. It also removes the ability to tune Gambit's configuration, so SchemeSpheres doesn't support this way of installing Gambit at the moment. We will use Homebrew just for GCC.

Note for Linux and OSX: If your system can't find Gambit after installing it, make sure to link the gsi and gsc binaries to /usr/bin. Another option is to have Gambit's bin directory (/usr/local/Gambit-C/bin by default) in your system's path (both for the user and root).

1. Core Sphere installation

First, get the latest release or the development version from the Github repository.

In the cloned or uncompressed folder, run:

sudo ./bootstrap

Note for Gambit users: ./configure will create a .gambcini initialization file for you, and overwrite any previous one.

Try it out in the REPL

Now you can start using Spheres for loading code and dependencies in the Gambit REPL. Run gsi and type this in the REPL to see if it works.

500 Server Error

Error: Server Error

The server encountered an error and could not complete your request.

Please try again in 30 seconds.

You should see:

-- including -- (core: testing-macros version: ())
-- loading -- (core: testing)

Which means that the module has been loaded, and its syntax macros are ready in the REPL. Now you can use the lightweight testing module directly in the REPL.

2. Installing spheres

If you are going to install OpenGL and SDL2 spheres, you need to have these libraries along with their C headers installed (all SDL libraries, the OpenGL implementation + GLEW). In OSX this can be achieved easily with Homebrew:

brew install sdl2 sdl2_image sdl2_mixer sdl2_net sdl2_ttf glew

In Linux, you need to use your distribution's package manager (emerge, pacman, apt-get...).

Spheres are installed using the sspheres program. These are the spheres in the latest release:

sudo sspheres install cairo codec crypto energy fabric fusion math object opengl sdl2 strings

3. Using SchemeSpheres

Interactive use

When coding interactively in the Gambit REPL, you have access to Spheres using the form:

500 Server Error

Error: Server Error

The server encountered an error and could not complete your request.

Please try again in 30 seconds.

This will take care of bringing and evaluating a module and its dependencies, for its immediate use in the REPL. Try running gsi and writing this code:

500 Server Error

Error: Server Error

The server encountered an error and could not complete your request.

Please try again in 30 seconds.

The result should be 15 which is the sum of the list of numbers from 1 to 5.

If you really need to run a Scheme program without creating a managed project, you can run it from the command line like this:

gsi -e '(expander:include "test.scm")'

Compiling unmanaged projects is not supported. You need to create a container project for your code to properly compile code with SchemeSpheres. It is highly recommended to work with managed projects.

Managed project

Creating a project gives you access to the full functionality in SchemeSpheres, allowing multiple source files and properly handling all dependencies. In this example, we will use the OpenGL 2d generator to create a project template that you can use to try out the OpenGL and SDL bindings.

sfusion new -g sdl-opengl my-new-program

Now you can compile and run it on the Host (Linux/OSX), and Android/iOS device. To see which tasks are available, run inside the root folder of the you just created:

cd my-new-program

Important: For the Android backend to work, you need both Android SDK and NDK, plus the ANDROID_SDK_PATH and ANDROID_NDK_PATH environment variables set up pointing at these directories.

You can check for more generators with Sfusion:

sfusion generators

The key to working with projects is the configuration of the sakefile.scm and config.scm files. Currently, the best source of information is found at:

4. Where to go from here

Soon, there will be more tutorials and guides. Meanwhile, you can start from the program skeletons provided with Sfusion, and check the spheres for lots of functionality ready to use.

If you want to create a new Sphere, and nicely integrate with SchemeSpheres, the best way to start would be knowing more about how spheres work.


Please visit the Troubleshooting guide.