cyclone/docs/User-Manual.md

[<img src="images/cyclone-logo-04-header.png" alt="cyclone-scheme">](http://justinethier.github.com/cyclone)

# User Manual

- [Introduction](#introduction)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
  - [Compiling Scheme Programs](#compiling-scheme-programs)
  - [Compiling Scheme Libraries](#compiling-scheme-libraries)
  - [Command Line Options](#command-line-options)
  - [Generated Files](#generated-files)
  - [Interpreter](#interpreter)
- [Language Details](#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](#foreign-function-interface)
- Debugging
  include profiling instructions?
- Limitations???
- [Licensing](#licensing)
- [References and Further Reading](#references-and-further-reading)


# Introduction
Cyclone is an experimental Scheme-to-C compiler that uses a variant of the [Cheney on the MTA](http://www.pipeline.com/~hbaker1/CheneyMTA.html) 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](https://github.com/justinethier). 

Bug reports and patches are welcome! Please report any issues using the [Issues Page](https://github.com/justinethier/cyclone/issues).

# Requirements

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

The following packages are required:

- make
- gcc
- [Concurrency Kit](http://concurrencykit.org/)

    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](http://www.opensource.org/licenses/mit-license.php).

# References and Further Reading

- [CONS Should Not CONS Its Arguments, Part II: Cheney on the M.T.A.](http://www.pipeline.com/~hbaker1/CheneyMTA.html), by Henry Baker
- [CHICKEN Scheme](http://www.call-cc.org/)
- [Chibi Scheme](https://github.com/ashinn/chibi-scheme)
- [Compiling Scheme to C with closure conversion](http://matt.might.net/articles/compiling-scheme-to-c/), by Matt Might
- Implementing an on-the-fly garbage collector for Java, by Domani et al
- [Lisp in Small Pieces](http://pagesperso-systeme.lip6.fr/Christian.Queinnec/WWW/LiSP.html), by Christian Queinnec
- Portable, Unobtrusive Garbage Collection for Multiprocessor Systems, by Damien Doligez and Georges Gonthier
- [R<sup>5</sup>RS Scheme Specification](http://www.schemers.org/Documents/Standards/R5RS/HTML/)
- [R<sup>7</sup>RS Scheme Specification](http://trac.sacrideo.us/wg/wiki)
- [Structure and Interpretation of Computer Programs](https://mitpress.mit.edu/sicp/full-text/book/book.html), by Harold Abelson and Gerald Jay Sussman
- [The 90 minute Scheme to C compiler](http://churchturing.org/y/90-min-scc.pdf), by Marc Feeley