Total Pageviews

Friday, 15 July 2016


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:
  • A basic development environment (Git, a C/C++ compiler). We recommend a code editor such as Emacs with Paredit).
  • The Gambit Scheme Compiler. You can get the latest version from Github, or just use your distribution's package. We recommend using the latest version.
  • cURL (probably installed in your system already).

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.
(##spheres-load core: testing)
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 (emergepacmanapt-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:
(##spheres-load sphere: module)
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:
(##spheres-load fabric: algorithm/list)
(fold + 0 '(1 2 3 4 5))
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:
  • The default, generated config.scm and sakefile.scm files.
  • The ones found in current release Spheres.
  • The How do Spheres Work guide.

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.

SchemeSpheres v0.6 Release

  • Support for Android.
  • New generators, with Android support: (minimal, remote REPL, SDL OpenGL application with remote inspection/debugging).
  • Fusion/Sake tasks handle Scheme/C/Java avoiding recompilation whenever possible.
  • Full SDL2 bindings.
  • Full OpenGL/ES2 bindings.
  • General improvements to the overall infrastructure and bug fixes.
  • More functionality in several spheres.
If you want to try it out follow these quick instructions (or check out the Quickstart and Installation Guide):
  • This release has been developed for Gambit v4.7.2.
  • Download the v0.6 release of Core Sphere.
  • Run:

sudo ./bootstrap

  • Install the rest of the spheres in this release:

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

  • Create an SDL/OpenGL(ES) skeleton:

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

  • See all available tasks:


  • Run interpreted or compile it on the Host platform (Linux / OS X):

sake host

  • Compile and Run it on Android:

sake android:setup
sake android

If you are running the program called sense at the same time you run your Android App, and the IP address in src/app.scm points to your computer’s local IP, you’ll be connected remotely with a terminal running a Gambit REPL inside your Android device. Now you are free to develop interactively on Android.
Happy hacking! :)