Fcalva/cyclone
1
0
Fork 0
mirror of https://github.com/justinethier/cyclone.git synced 2025-05-21 14:49:17 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
cyclone/docs/User-Manual.md
Justin Ethier 9921a6f3a7 WIP
2016-01-12 22:34:23 -05:00

5.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 M.T.A.) and implemented first by CHICKEN Scheme. The difference here 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 performs 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

TODO: installation procedure for cyclone-bootstrap TODO: installation procedure for development????

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

TODO

Foreign Function Interface

TODO

Licensing

Cyclone is available under the MIT license.

References and Further Reading