How do Spheres work?

This document explains how Spheres are built and their internal structure. This will allow you to customize or create your own spheres, so they could be included in SchemeSpheres releases.

The philosophy

SchemeSpheres is born with one premise: the project must be useful to the Scheme Community even if it eventually gets stalled. The code compiled and created in this project should be highly usable by any other Scheme implementation or similar project for Gambit. For this reason, a very important aspect of SchemeSpheres is that it aims at being non-intrusive to R5RS code. Modules in SchemeSpheres should work seamlessly in Gambit (with macro expansion and provided you supply the necessary dependencies).

Features and Parts of SchemeSpheres

SchemeSpheres, as a project, is comprised of three complementary parts:

Hygienic macros expansion, modules and conditional compilation. These features must be usually solved together, as they all transform the code at compile-time. Many compilers, as is the case with Gambit, leave hygienic macros and related syntax expansion to the user implementation.

Workflow tool-chain. This is perhaps the most distinctive feature of SchemeSpheres in comparison with package systems. Essentially, the framework provides a set of tools for creating workflows, instead of forcing the user through a generic one. The workflow is divided into three parts: project skeleton generation, task running, and dependency management. These are handled currently by three tools:

Ecosystem. The set of aspects that help SchemeSpheres build community and collaboration around the project. Such a project benefits from the contribution of any Scheme developer that may desire to, so it must be prepared to integrate modules, tests, generators and tasks. The main points that fall under this category are:

In summary, Spheres is a set of tools/scripts and libraries on top of Gambit that will take care of the most tedious work of developing software with Gambit. Some examples are:

Hygienic Macros and Modules

SchemeSpheres uses a custom version of Psyntax, developed by Matt Hastie. It loads fast and expands code fast, and can be used when remotely debugging mobile devices. It supports syntax-rules and syntax-case (define-macro is defined in terms of syntax-case, thus is supported as well). This opens us to full R5RS compatibility, and much of the SRFIs and amazing community code that relies on syntax-rules.

There is no module system currently in SchemeSpheres, so namespaces can be used instead. That will be improved in the near future.

Importing modules in the interactive REPL

The macros ##spheres-load and ##spheres-include take care of loading and including the necessary files to make the dependencies work:

Alternative syntax: for modules local to the current spheres, you can use the syntax (##spheres-load module).

Importing for compilation and cross-compilation

Dependencies in the process of (cross-)compilation are handled by ssake, via the tasks defined in sakefile.scm. Details regarding the implementation of this file are given bellow. Basically, it works by expanding all the code before compilation, and setting module files in order, so headers, FFI, macro expansion and code are handled in order for every platform.

Structure of a Sphere

A sphere is Git repository, named starting with sphere-. This allows the remote fetching and installation of the spheres, along all its versions. The versioning system will eventually be based on the tags functionality given by Git.

This repository consists of the following mandatory items:

Also, you will generally find the following items:

Module files

Modules can be comprised of up to four kinds of files:

Inside config.scm

This file holds the basic information about the sphere. It includes:

It's probably better to look at the code:

500 Server Error

Error: Server Error

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

Please try again in 30 seconds.

Only the files declared as dependencies in a stage (include, prelude, load) will become available. You probably will use the prelude file for including declarations concerning the FFI (necessary only at compile-time), the macros file for including hygienic macros, and the base file for the standard code (R5RS Scheme code, which can in turn use any of the functionality or structures defined in the previous two files).

You may wonder why the dependencies are defined in this file, instead of inside each module, what can lead to a long config.scm file. The main reason is to make the modules seamlessly portable among plain Gambit and SchemeSpheres. If R7RS modules get implemented in Gambit, this will change.

Inside sakefile.scm

This file contains a series of tasks that can be invoked from the command-line via the command ssake.

Let's take a look inside an example:

500 Server Error

Error: Server Error

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

Please try again in 30 seconds.

Each of these tasks can be invoked like this:

ssake <task>

Ssake comes with predefined tasks, sub-tasks and useful functions. All ssake extension modules are installed in sake-extensions directory in Spheres' installation path.

How to create a new Sphere

Basically, it all boils downs to these steps:

This is probably best achieved by copying the structure from a simple Sphere. You may also want to take a look at how to document spheres, as an uniform and consistent documentation is one of the targets of this project.