Fcalva/cyclone
1
0
Fork 0
mirror of https://github.com/justinethier/cyclone.git synced 2025-05-20 14:19:17 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
cyclone/docs/User-Manual.md
Justin Ethier 1312d1819a WIP
2016-01-13 23:32:59 -05:00

7.9 KiB
Raw Blame History

cyclone-scheme

User Manual

Introduction

Cyclone is an experimental Scheme-to-C compiler that uses a variant of the Cheney on the MTA technique to implement full tail recursion, continuations, generational garbage collection, and native threads.

Cyclone works by converting a Scheme program to continuation passing style and compiling each continuation to a C function. At runtime these functions never return and are allowed to fill up the stack until they trigger a minor garbage collection. Live stack objects are then copied to the heap and longjmp is used to return to the beginning of the stack. This is the same technique proposed by Henry Baker (Cheney on the MTA) and implemented first by CHICKEN Scheme. The difference in our compiler is that multiple native threads are allowed, each with their own stack. A tracing garbage collector is used to manage the second-generation heap and perform major collections without "stopping the world".

Cyclone is developed by Justin Ethier.

Bug reports and patches are welcome! Please report any issues using the Issues Page.

Requirements

Cyclone has been tested under Linux on both x86 (32-bit) and ARM.

The following packages are required:

  • make

  • gcc

  • Concurrency Kit

    The best way to install libck is via a package manager such as apt-get. But if a package is not available for this library it can also be built from source. Just replace 0.5.0 below with the latest version available from their website:

      wget http://concurrencykit.org/releases/ck-0.5.0.tar.gz
  tar xfz ck-0.5.0.tar.gz ; cd ck-0.5.0 ; ./configure && make all && sudo make install
  sudo ldconfig

Installation

Cyclone cannot be built directly on a system that does not have Cyclone binaries installed because the compiler is self-hosting. The easiest way to install Cyclone binaries is to build from source using cyclone-bootstrap:

$ git clone git@github.com:justinethier/cyclone-bootstrap.git
$ cd cyclone-bootstrap
$ ./install.sh

Once Cyclone is installed, it can be rebuilt directly from the cyclone repository:

$ make
$ make test
$ sudo make install

Usage

Compiling Scheme Programs

A Scheme program may be compiled using the cyclone command:

$ cyclone  examples/fac.scm
$ examples/fac
3628800

Compiling Scheme Libraries

Scheme code can be organized into libraries that are compiled separately from programs. Cyclone intends a library to represent a single C module (or file) when compiled.

Each library must be placed into a .sld file that corresponds to the library name. For example, the library

(scheme cyclone util)

would be defined in its .sld file as:

(define-library (scheme cyclone util)
  ... )

and should be located in the file

scheme/cyclone/util.sld

Cyclone will not automatically generate libraries when compiling a program. Each library will need to be built separately prior to building the program.

Command Line Options

cyclone has the following command line options:

Option Notes
-t Show intermediate trace output in generated C files
-d Only generate intermediate C files, do not compile them
-h, --help Display usage information
-v Display version information

Generated Files

The following files are generated during the Cyclone compilation process:

File Extension Notes
.meta These text files contain the expanded version of any macros exported by a Scheme library, and allow other modules to easily use those macros during compilation. This file is not generated when compiling a program.
.c C code file generated by Cyclone.
.o Object file generated by the C compiler from the corresponding .c file.
(None) Final executable file generated by the C compiler when compiling a program.

Interpreter

Scheme code can be evaluated interactively using the icyc command:

    $ icyc
    cyclone> (write 'hello-world)
    hello-world

Language Details

Cyclone implements the Scheme language as documented by the R7RS Scheme Specification. There is a R7RS Compliance chart that lists the differences between the specification and Cyclone's implementation.

API Documentation is available for the libraries provide by Cyclone.

Foreign Function Interface

The define-c special form can be used to define a function containing user-defined C code. This code will be carried through from the Scheme file all the way to the compiled C file. For example:

 (define-c Cyc-add-exception-handler
   "(void *data, int argc, closure _, object k, object h)"
   " gc_thread_data *thd = (gc_thread_data *)data;
     make_cons(c, h, thd->exception_handler_stack);
     thd->exception_handler_stack = &c;
     return_closcall1(data, k, &c); ")

The arguments to define-c are:

  • Function name. These functions can be used in Scheme code just like any other function.
  • A string with C function arguments, enclosed in parentheses. Some of these are required:
    • data - Internal thread data. Do not modify this unless you know what you are doing!
    • argc - Number of function arguments.
    • A closure, typically unused in this context.
    • k - Current continuation, typically the code will call into k with a result.
  • A string containing the C function body. Remember that runtime functions are not allowed to return. In the example above, the return_closcall1 macro is used to "return" a newly-allocated list to the current continuation.

The Cyclone runtime can be used as a reference for how to write your own C functions. A good starting point would be runtime.c and types.h.

Licensing

Cyclone is available under the MIT license.

References and Further Reading