Copyright © 2000-2005, Felix L. Winkelmann All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

CHICKEN - A practical and portable Scheme system. Version 2, Build 228

CHICKEN - A practical and portable Scheme system. Version 2, Build 228

Table of Contents

Next: , Up: (dir)

CHICKEN

CHICKEN - A practical and portable Scheme system User's manual (Version 2, Build 228)

(c) 2000-2005, Felix L. Winkelmann All rights reserved. Translated to LaTeX by Peter Keller. Translated to texinfo by Linh Dang.

--- The Detailed Node Listing ---

Using the compiler

Using the interpreter

Supported language

Non-standard macros and special forms

Unit library

Unit eval

Unit extras

Unit posix

Unit utils

Unit lolevel

Unit tinyclos

Interface to external functions and variables

The Easy Foreign Function Interface

chicken-setup

Additional files

Next: , Previous: Top, Up: Top

1 Introduction

CHICKEN is a compiler that translates Scheme source files into C, which in turn can be fed to a C-compiler to generate a standalone executable. This principle, which is used by several existing compilers, achieves high portability because C is implemented on nearly all available platforms.

This package is distributed under the BSD license and as such is free to use and modify. An interpreter is also available and can be used as a scripting environment or for testing programs before compilation.

The method of compilation and the design of the runtime-system follow closely Henry Baker's CONS Should Not CONS Its Arguments, Part II: Cheney on the M.T.A. paper and expose a number of interesting properties: consing (creation of data on the heap) is relatively inexpensive, because a generational garbage collection scheme is used, in which short-lived data structures are reclaimed extremely quickly. Moreover, call-with-current-continuation is practically for free and CHICKEN does not suffer under any performance penalties if first-class continuations are used in complex ways. The generated C code is fully tail-recursive.

Some of the features supported by CHICKEN:

This manual is merely a reference for the CHICKEN system and assumes a working knowledge of Scheme.

Next: , Previous: Introduction, Up: Top

2 Basic mode of operation

The compiler translates Scheme source code into fairly portable C that can be compiled and linked with most available C compilers. CHICKEN supports the generation of executables and libraries, linked either statically or dynamically. Compiled Scheme code can be loaded dynamically, or can be embedded in applications written in other languages. Separate compilation of modules is fully supported.

The most portable way of creating separately linkable entities is supported by so-called units. A unit is a single compiled object module that contains a number of toplevel expressions that are executed either when the unit is the main unit or if the unit is used. To use a unit, the unit has to be declareed as used, like this: 

(declare (uses UNITNAME))

The toplevel expressions of used units are executed in the order in which the units appear in the uses declaration. Units may be used multiple times and uses declarations may be circular (the unit is initialized at most once). To compile a file as a unit, add a unit declaration: 

(declare (unit UNITNAME))

When compiling different object modules, make sure to have one main unit. This unit is called initially and initializes all used units before executing its toplevel expressions. The main-unit has no unit declaration.

Another method of using definitions in separate source files is to include them. This simply inserts the code in a given file into the current file: 

(include "FILENAME")

Macro definitions are only available when processed by include. Macro definitions in separate units are not available, since they are defined at compile time, i.e the time when that other unit was compiled (macros can optionally be available at runtime, see define-macro in Substitution forms and macros).

On platforms that support dynamic loading of compiled code (like Windows and most ELF based systems like Linux or BSD) code can be compiled into a shared object (.so) and loaded dynamically into a running application.

Next: , Previous: Basic mode of operation, Up: Top

3 Using the compiler

The interface to chicken is intentionally simple. System dependent makefiles, shell-scripts or batch-files should perform any necessary steps before and after invocation of chicken. A program named csc provides a much simpler interface to the Scheme- and C-compilers and linker. Enter 

csc -help

on the command line for more information.

Next: , Up: Using the compiler

3.1 Command line format

chicken FILENAME {OPTION}

FILENAME is the complete pathname of the source file that is to be translated into C. A filename argument of “-” specifies that the source text should be read from standard input. Note that the filename has to be the first argument to chicken. Possible options are:

-analyze-only
Stop compilation after first analysis pass.
-benchmark-mode
Equivalent to -no-trace -no-lambda-info -optimize-level 3 -fixnum-arithmetic -disable-interrupts -block -lambda-lift.
-block
Enable block-compilation. When this option is specified, the compiler assumes that global variables are not modified outside this compilation-unit. Specifically, toplevel bindings are not seen by eval and unused toplevel bindings are removed.
-case-insensitive
Enables the reader to read symbols case insensitive. The default is to read case sensitive (in violation of R5RS). This option registers the case-insensitive feature identifier.
-check-syntax
Aborts compilation process after macro-expansion and syntax checks.
-compress-literals THRESHOLD
Compiles quoted literals that exceed the size THRESHOLD as strings and parse the strings at run-time. This reduces the size of the code and speeds up compile-times of the host C compiler, but has a small run-time performance penalty. The size of a literal is computed by counting recursively the objects in the literal, so a vector counts as 1 plus the count of the elements, a pair counts as the counts of the car and the cdr, respectively. All other objects count 1.
-debug MODES
Enables one or more compiler debugging modes. MODES is a string of characters that select debugging information about the compiler that will be printed to standard output.
t
show time needed for compilation
b
show breakdown of time needed for each compiler pass
o
show performed optimizations
r
show invocation parameters
s
show program-size information and other statistics
a
show node-matching during simplification
p
show execution of compiler sub-passes
l
show lambda-lifting information
m
show GC statistics during compilation
n
print the line-number database
c
print every expression before macro-expansion
e
lists all exported toplevel bindings
u
lists all unassigned global variable references
x
display information about experimental features
D
when printing nodes, use node-tree output
N
show the real-name mapping table
U
show expressions after the secondary user pass
0
show database before lambda-lifting pass
L
show expressions after lambda-lifting
F
show output of “easy” FFI parser
P
show execution of outer partitioning
Q
show execution of middle partitioning
R
show execution of inner partitioning
M
show unit-information and syntax-/runtime-requirements
1
show source expressions
2
show canonicalized expressions
3
show expressions converted into CPS
4
show database after each analysis pass
5
show expressions after each optimization pass
6
show expressions after each inlining pass
7
show expressions after complete optimization
8
show database after final analysis
9
show expressions after closure conversion

-debug-level LEVEL
Selects amount of debug-information. LEVEL should be an integer.
-disable-c-syntax-checks
Disable basic syntax checking of embedded C code fragments.
-disable-interrupts
Equivalent to the (disable-interrupts) declaration. No interrupt-checks are generated for compiled programs.
-disable-stack-overflow-checks
Disables detection of stack overflows. This is equivalent to running the compiled executable with the -:o runtime option.
-dynamic
This option should be used when compiling files intended to be loaded dynamically into a running Scheme program.
-epilogue FILENAME
Includes the file named FILENAME at the end of the compiled source file. The include-path is not searched. This option may be given multiple times.
-emit-external-prototypes-first
Emit prototypes for callbacks defined with define-external before any other foreign declarations. This is sometimes useful, when C/C++ code embedded into the a Scheme program has to access the callbacks. By default the prototypes are emitted after foreign declarations.
-explicit-use
Disables automatic use of the units library, eval and extras. Use this option if compiling a library unit instead of an application unit.
-extend FILENAME
Loads a Scheme source file or compiled Scheme program (on systems that support it) before compilation commences. This feature can be used to extend the compiler. This option may be given multiple times. The file is also searched in the current include path and in the extension-repository.
-extension
Mostly equivalent to -prelude '(define-extension <NAME>)', where <NAME> is the basename of the currently compiled file.
-feature SYMBOL
Registers SYMBOL to be a valid feature identifier for cond-expand.
-ffi
Parse C/C++ code and generate Scheme bindings. This is effectively equivalent to wrapping the code in #>! ... <#.
-ffi-parse
Parse C/C++ code and embed as if wrapped inside #>? ... <#.
-ffi-define SYMBOL
Defines a macro that will be accessible in foreign-parse declarations.
-ffi-include-path PATH
Set include path for “easy” FFI parser.
-ffi-no-include
Don't parse include files when encountered by the FFI parser.
-fixnum-arithmetic
Equivalent to (fixnum-arithmetic) declaration. Assume all mathematical operations use small integer arguments.
-heap-size NUMBER
Sets a fixed heap size of the generated executable to NUMBER bytes. The parameter may be followed by a M (m) or K (k) suffix which stand for mega- and kilobytes, respectively. The default heap size is 5 kilobytes. Note that only half of it is in use at every given time.
-heap-initial-size NUMBER
Sets the size that the heap of the compiled application should have at startup time.
-heap-growth PERCENTAGE
Sets the heap-growth rate for the compiled program at compile time (see: -:hg).
-heap-shrinkage PERCENTAGE
Sets the heap-shrinkage rate for the compiled program at compile time (see: -:hs).
-help
Print a summary of available options and the format of the command line parameters and exit the compiler.
-include-path PATHNAME
Specifies an additional search path for files included via the include special form. This option may be given multiple times. If the environment variable CHICKEN_INCLUDE_PATH is set, it should contain a list of alternative include pathnames separated by “;”. The environment variable CHICKEN_HOME is also considered as a search path.
-inline
Enable procedure inlining for known procedures of a size below the threshold (which can be set through the -inline-limit option).
-inline-limit THRESHOLD
Sets the maximum size of a potentially inlinable procedure. This option is only effective when inlining has been enabled with the -inline option. The default threshold is 10.
-keyword-style STYLE
Enables alternative keyword syntax, where STYLE may be either prefix (as in Common Lisp), suffix (as in DSSSL) or none. Any other value is ignored. The default is suffix.
-lambda-lift
Enable the optimization known as lambda-lifting.
-no-lambda-info
Don't emit additional information for each lambda expression (currently the argument-list, after alpha-conversion/renaming).
-no-trace
Disable generation of tracing information. If a compiled executable should halt due to a runtime error, then a list of the name and the line-number (if available) of the last procedure calls is printed, unless -no-trace is specified. With this option the generated code is slightly faster.
-no-warnings
Disable generation of compiler warnings.
-nursery NUMBER
-stack-size NUMBER
Sets the size of the first heap-generation of the generated executable to NUMBER bytes. The parameter may be followed by a M (m) or K (k) suffix. The default stack-size depends on the target platform.
-optimize-leaf-routines
Enable leaf routine optimization.
-optimize-level LEVEL
Enables certain sets of optimization options. LEVEL should be an integer.
-output-file FILENAME
Specifies the pathname of the generated C file. Default is FILENAME.c.
-postlude EXPRESSIONS
Add EXPRESSIONS after all other toplevel expressions in the compiled file. This option may be given multiple times. Processing of this option takes place after processing of -epilogue.
-prelude EXPRESSIONS
Add EXPRESSIONS before all other toplevel expressions in the compiled file. This option may be given multiple times. Processing of this option takes place before processing of -prologue.
-profile
-accumulate-profile
Instruments the source code to count procedure calls and execution times. After the program terminates (either via an explicit exit or implicitly), profiling statistics are written to a file named PROFILE. Each line of the generated file contains a list with the procedure name, the number of calls and the time spent executing it. Use the chicken-profile program to display the profiling information in a more user-friendly form. Enter chicken-profile with no arguments at the command line to get a list of available options.

The -accumulate-profile option is similar to -profile, but the resulting profile information will be appended to any existing PROFILE file. chicken-profile will merge and sum up the accumulated timing information, if several entries for the same procedure calls exist.

-profile-name FILENAME
Specifies name of the generated profile information (which defaults to PROFILE. Implies -profile.
-prologue FILENAME
Includes the file named FILENAME at the start of the compiled source file. The include-path is not searched. This option may be given multiple times.
-quiet
Disables output of compile information.
-raw
Disables the generation of any implicit code that uses the Scheme libraries (that is all runtime system files besides runtime.c and chicken.h).
-require-extension NAME
Loads the extension NAME before the compilation process commences. This is identical to adding (require-extension NAME) at the start of the compiled program.
-run-time-macros
Makes macros also available at run-time. By default macros are not available at run-time.
-split NUMBER
Splits output into multiple C files that can be compiled separately. The generated C files will be named filename0, ..., filename<NUMBER-1> with as many files as given in NUMBER.
-split-level NUMBER
Specifies how hard the partitioning algorithm should work:
-to-stdout
Write compiled code to standard output instead of creating a .c file.
-unit NAME
Compile this file as a library unit. Equivalent to 
     
     -prelude "(declare (unit NAME))"

-unsafe
Disable runtime safety checks.
-unsafe-libraries
Marks the generated file for being linked with the unsafe runtime system. This should be used when generating shared object files that are to be loaded dynamically. If the marker is present, any attempt to load code compiled with this option will signal an error.
-uses NAME
Use definitions from the library unit NAME. This is equivalent to 
     
     -prelude "(declare (uses NAME))"

-no-usual-integrations
Specifies that standard procedures and certain internal procedures may be redefined, and can not be inlined. This is equivalent to declaring (not usual-integrations).
-version
Prints the version and some copyright information and exit the compiler.
-verbose
Prints progress information to standard output during compilation.

The environment variable CHICKEN_OPTIONS can be set to a string with default command-line options for the compiler.

Next: , Previous: Compiler command line format, Up: Using the compiler

3.2 Runtime options

After successful compilation a C source file is generated and can be compiled with a C compiler. Executables generated with CHICKEN (and the compiler itself) accept a small set of runtime options:

-:?
Shows a list of the available runtime options and exits the program.
-:b
Enter a read-eval-print-loop when an error is encountered.
-:c
Forces console mode. Currently this is only used in the interpreter (csi) to force output of the #;N> prompt even if stdin is not a terminal (for example if running in an emacs buffer under Windows).
-:d
Prints some debug-information during startup.
-:hNUMBER
Specifies fixed heap size
-:hiNUMBER
Specifies the initial heap size
-:hgPERCENTAGE
Sets the growth rate of the heap in percent. If the heap is exhausted, then it will grow by PERCENTAGE. The default is 200.
-:hmNUMBER
Specifies a maximal heap size. The default is (2GB - 15).
-:hsPERCENTAGE
Sets the shrink rate of the heap in percent. If no more than a quarter of PERCENTAGE of the heap is used, then it will shrink to PERCENTAGE. The default is 50. Note: If you want to make sure that the heap never shrinks, specify a value of 0. (this can be useful in situations where an optimal heap-size is known in advance).
-:o
Disables detection of stack overflows at run-time.
-:sNUMBER
Specifies stack size.
-:tNUMBER
Specifies symbol table size.
-:fNUMBER
Specifies the maximal number of currently pending finalizers before finalization is forced.
-:aNUMBER
Specifies the length of the buffer for recording a trace of the last invoked procedures. Defaults to 16.
-:w
Enables garbage collection of unused symbols. By default unused and unbound symbols are not garbage collected.
-:r
Writes trace output to stderr. This option has no effect with in files compiled with the -no-trace options.
-:x
Raises uncaught exceptions of separately spawned threads in primordial thread. By default uncaught exceptions in separate threads are not handled, unless the primordial one explicitly joins them. When warnings are enabled (the default) and -:x is not given, a warning will be shown, though.
-:B
Sounds a bell (ASCII 7) on every major garbage collection.

The argument values may be given in bytes, in kilobytes (suffixed with K or k), in megabytes (suffixed with M or m), or in gigabytes (suffixed with G or g). Runtime options may be combined, like -:dc, but everything following a NUMBER argument is ignored. So -:wh64m is OK, but -:h64mw will not enable GC of unused symbols.

Next: , Previous: Runtime options, Up: Using the compiler

3.3 An example

To compile a Scheme program (assuming a UNIX-like environment) perform the following steps:

If multiple bodies of Scheme code are to be combined into a single executable, then we have to compile each file and link the resulting object files together with the runtime system:

The declarations specify which of the compiled files is the main module, and which is the library module. An executable can only have one main module, since a program has only a single entry-point. In this case foo.scm is the main module, because it doesn't have a unit declaration.

Next: , Previous: An example, Up: Using the compiler

3.4 Extending the compiler

The compiler supplies a couple of hooks to add user-level passes to the compilation process. Before compilation commences any Scheme source files or compiled code specified using the -extend option are loaded and evaluated. The parameters user-options-pass, user-read-pass, user-preprocessor-pass, user-pass, user-pass-2 and user-post-analysis-pass can be set to procedures that are called to perform certain compilation passes instead of the usual processing (for more information about parameters see: Parameters.

— parameter: user-options-pass

Holds a procedure that will be called with a list of command-line arguments and should return two values: the source filename and the actual list of options, where compiler switches have their leading - (hyphen) removed and are converted to symbols. Note that this parameter is invoked before processing of the -extend option, and so can only be changed in compiled user passes.

— parameter: user-read-pass

Holds a procedure of three arguments. The first argument is a list of strings with the code passed to the compiler via -prelude options. The second argument is a list of source files including any files specified by -prologue and -epilogue. The third argument is a list of strings specified using -postlude options. The procedure should return a list of toplevel Scheme expressions.

— parameter: user-preprocessor-pass

Holds a procedure of one argument. This procedure is applied to each toplevel expression in the source file before macro-expansion. The result is macro-expanded and compiled in place of the original expression.

— parameter: user-pass

Holds a procedure of one argument. This procedure is applied to each toplevel expression after macro-expansion. The result of the procedure is then compiled in place of the original expression.

— parameter: user-pass-2

Holds a procedure of three arguments, which is called with the canonicalized node-graph as its sole argument. The result is ignored, so this pass has to mutate the node-structure to cause any effect.

— parameter: user-post-analysis-pass

Holds a procedure that will be called after the last performed program analysis. The procedure (when defined) will be called with three arguments: the program database, a getter and a setter-procedure which can be used to access and manipulate the program database, which holds various information about the compiled program. The getter procedure should be called with two arguments: a symbol representing the binding for which information should be retrieved, and a symbol that specifies the database-entry. The current value of the database entry will be returned or #f, if no such entry is available. The setter procedure is called with three arguments: the symbol and key and the new value.

For information about the contents of the program database contact the author.

Loaded code (via the -extend option) has access to the library units extras, srfi-1, srfi-4, utils, regex and the pattern matching macros. Multithreading is not available.

Note that the macroexpansion/canonicalization phase of the compiler adds certain forms to the source program. These extra expressions are not seen by user-preprocessor-pass but by user-pass.

Previous: Extending the compiler, Up: Using the compiler

3.5 Distributing compiled C files

It is relatively easy to create distributions of Scheme projects that have been compiled to C. The runtime system of CHICKEN consists of only two handcoded C files (runtime.c and chicken.h), plus the file chicken-config.h, which is generated by the build process. All other modules of the runtime system and the extension libraries are just compiled Scheme code. The following example shows a minimal application, which should run without changes on the most frequent operating systems, like Windows, Linux or FreeBSD:

Let's take a simple “Hello, world!”: 

; hello.scm

(print "Hello, world!")

Compiled to C, we get hello.c. We need the files chicken.h and runtime.c, which contain the basic runtime system, plus the three basic library files library.c, eval.c and extras.c which contain the same functionality as the library linked into a plain CHICKEN-compiled application, or which is available by default in the iinterpreter, csi: 

% csc hello.scm -O2 -d1

A simple makefile is needed as well: 

# Makefile for UNIX systems

hello: hello.o runtime.o library.o eval.o extras.o
       $(CC) -o hello hello.o runtime.o library.o eval.o extras.o -lm

hello.o: chicken.h
runtime.o: chicken.h
library.o: chicken.h
eval.o: chicken.h
extras.o: chicken.h

Now we have all files together, and can create an tarball containing all the files: 

% tar cf hello.tar Makefile hello.c runtime.c library.c eval.c extras.c chicken.h
% gzip hello.tar

This is of naturally rather simplistic. Things like enabling dynamic loading, estimating the optimal stack-size and selecting supported features of the host system would need more configuration- and build-time support. All this can be addressed using more elaborate build-scripts, makefiles or by using autoconf/automake/libtool.

Note also that the size of the application can still be reduced by removing extras and eval and compiling hello.scm with the -explicit-use option.

For more information, study the CHICKEN source code and/or get in contact with the author.

Next: , Previous: Using the compiler, Up: Top

4 Using the interpreter

CHICKEN provides an interpreter named csi for evaluating Scheme programs and expressions interactively.

Next: , Up: Using the interpreter

4.1 Command line format

  csi {FILENAME|OPTION}

where FILENAME specifies a file with Scheme source-code. If the extension of the source file is .scm, it may be omitted. The runtime options described in Compiler command line format are also available for the interpreter. If the environment variable CSI_OPTIONS is set to a list of options, then these options are additionally passed to every direct or indirect invocation of csi. Please note that runtime options (like -:...) can not be passed using this method. The options recognized by the interpreter are:

--
Ignore everything on the command-line following this marker. Runtime options (“-:...”) are still recognized.
-i -case-insensitive
Enables the reader to read symbols case insensitive. The default is to read case sensitive (in violation of R5RS). This option registers the case-insensitive feature identifier.
-b -batch
Quit the interpreter after processing all command line options.
-e -eval EXPRESSIONS
Evaluate EXPRESSIONS. This option implies -batch and -quiet, so no startup message will be printed and the interpreter exits after processing all -eval options and/or loading files given on the command-line.
-D -feature SYMBOL
Registers SYMBOL to be a valid feature identifier for cond-expand.
-h -help
Write a summary of the available command line options to standard output and exit.
-I -include-path PATHNAME
Specifies an alternative search-path for files included via the include special form. This option may be given multiple times. If the environment variable CHICKEN_INCLUDE_PATH is set, it should contain a list of alternative include pathnames separated by “;”. The environment variable CHICKEN_HOME is also considered as a search path.
-k -keyword-style STYLE
Enables alternative keyword syntax, where STYLE may be either prefix (as in Common Lisp) or suffix (as in DSSSL). Any other value is ignored.
-n -no-init
Do not load initialization-file. If this option is not given and the file ./.csirc or $(HOME)/.csirc exists, then it is loaded before the read-eval-print loop commences.
-w -no-warnings
Disables any warnings that might be issued by the reader or evaluated code.
-q -quiet
Do not print a startup message.
-s -script PATHNAME
This is equivalent to -batch -quiet -no-init PATHNAME. Arguments following PATHNAME are available by using command-line-arguments and are not processed as interpreter options. Extra options in the environment variable CSI_OPTIONS are ignored.
-R -require-extension NAME
Equivalent to evaluating (require-extension NAME).
-v -version
Write the banner with version information to standard output and exit.

Next: , Previous: Interpreter command line format, Up: Using the interpreter

4.2 Writing Scheme scripts