cyclone/docs/User-Manual.md

User Manual for the Cyclone Scheme-to-C Compiler

• Introduction
• Requirements
• Installation
• Usage
  • Compiling Scheme Programs
  • Compiling Scheme Libraries
  • Command Line Options
  • Generated Files
  • Interpreter
• Language Details
  • explain how programs are setup
  • outline scheme language based on r7rs, link to it. explain differences between cyclone implementation and r7rs, or again at least link to them
  • provide API, or at least links to the API
  • what else?
• Foreign Function Interface
• Debugging include profiling instructions?
• Limitations???
• Licensing
• References and Further Reading

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.

TODO: Contact

• include information on bug reports (or should that go towards the beginning?)

Requirements

Tested on Linux, x86 (32-bit) and ARM

Required packages:

• 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
  

• make

• gcc

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

• CONS Should Not CONS Its Arguments, Part II: Cheney on the M.T.A., by Henry Baker
• CHICKEN Scheme
• Chibi Scheme
• Compiling Scheme to C with closure conversion, by Matt Might
• Implementing an on-the-fly garbage collector for Java, by Domani et al
• Lisp in Small Pieces, by Christian Queinnec
• Portable, Unobtrusive Garbage Collection for Multiprocessor Systems, by Damien Doligez and Georges Gonthier
• R⁵RS Scheme Specification
• R⁷RS Scheme Specification
• Structure and Interpretation of Computer Programs, by Harold Abelson and Gerald Jay Sussman
• The 90 minute Scheme to C compiler, by Marc Feeley