chicken.texi

Scheme跨平台编译器

@end verbatim
We can compile this program using @code{csc}, creating an executable named @code{palindrome}. 

@verbatim
$ csc -o palindrome palindrome.scm
$ ./palindrome level
level is a palindrome
$ ./palindrome liver
liver isn't a palindrome
@end verbatim
Chicken supports separate compilation, using some extensions to Scheme. Let's divide our palindrome program into a library module (@code{pal-proc.scm}) and a client module (@code{pal-user.scm}). 

Here's the external library. We @code{declare} that @code{pal-proc} is a `unit', which is the basis of separately-compiled modules in Chicken. (Units deal with separate compilation, but don't involve separated namespaces; namespaced module systems are available as eggs.)

@verbatim
;;; Library pal-proc.scm
(declare (unit pal-proc))
(define (palindrome? x)
  (define (check left right)
    (if (>= left right)
        #t
        (and (char=? (string-ref x left) (string-ref x right))
             (check (add1 left) (sub1 right)))))
  (check 0 (sub1 (string-length x))))
@end verbatim
Next we have some  client code that `uses' this separately-compiled module.  

@verbatim
;;; Client pal-user.scm
(declare (uses pal-proc))
(let ((arg (car (command-line-arguments))))
  (display 
   (string-append arg 
                  (if (palindrome? arg) 
                      " is a palindrome\n"
                      " isn't a palindrome\n"))))
@end verbatim
Now we can compile and link everything together. (We show the compile and link operations separately, but they can of course be combined into one command.) 

@verbatim
$ csc -c pal-proc.scm
$ csc -c pal-user.scm
$ csc -o pal-separate pal-proc.o pal-user.o
$ ./pal-separate level
level is a palindrome
@end verbatim
@node Getting started - Installing an egg, Getting started - Accessing C libraries, Getting started - The compiler, Getting started
@section Installing an egg


Installing eggs is quite straightforward on systems that support dynamic loading (again, that would include *BSD, Linux, Mac OS X, Solaris, and Windows).  The command @code{chicken-setup} will fetch an egg from the master Chicken repository, and install it on your local system.

In this example, we install the @code{uri} egg, for parsing Uniform Resource Identifiers. The installation produces a lot of output, which we have edited for space reasons.

@verbatim
$ chicken-setup uri
@end verbatim
@verbatim
The extension uri does not exist.
Do you want to download it ? (yes/no/abort) [yes] yes
downloading uri.egg from (www.call-with-current-continuation.org eggs/3 80) 
  gzip -d -c ../uri.egg | tar xf -
.  /Users/vmanis/local/bin/csc -feature compiling-extension 
     -s -O2 -d1 uri.scm -o uri.so -check-imports -emit-exports uri.exports
... (lots of stuff elided)
.  rm -fr /Users/vmanis/project/chicken/uri.egg
@end verbatim
First, @code{chicken-setup} asks us if we want to download the egg. It then uncompresses the egg, compiles the code, and installs the egg in the local Chicken repository. 

Now we can use our new egg. 

@verbatim
#;1> (use uri)
; loading /Users/vmanis/local/lib/chicken/3/uri.so ...
; loading /Users/vmanis/local/lib/chicken/3/coerce-support.so ...
; loading /Users/vmanis/local/lib/chicken/3/misc-extn-list-support.so ...
; loading /Users/vmanis/local/lib/chicken/3/synch-support.so ...
; loading /Users/vmanis/local/lib/chicken/3/lookup-table.so ...
; loading /Users/vmanis/local/lib/chicken/3/misc-extn-control-support.so ...
#;2> (uri-host (uri "uref{http://www.foobar.org/blah, http://www.foobar.org/blah}"))
"www.foobar.org"
@end verbatim
@node Getting started - Accessing C libraries,  , Getting started - Installing an egg, Getting started
@section Accessing C libraries


Because Chicken compiles to C, and because a foreign function interface is built into the compiler, interfacing to a C library is quite straightforward. This means that nearly any facility available on the host system is accessible from Chicken, with more or less work. 

Let's create a simple C library, to demonstrate how this works. Here we have a function that will compute and return the @b{n}th Fibonacci number. (This isn't a particularly good use of C here, because we could write this function just as easily in Scheme, but a real example would take far too much space here.) 

@verbatim
int fib(int n) {
  int prev = 0, curr = 1;
  int next; 
  int i; 
  for (i = 0; i < n; i++) {
    next = prev + curr;
    prev = curr;
    curr = next; 
  }
  return curr;
} 
@end verbatim
Now we can call this function from Chicken. 

@verbatim
#>
  extern fib(int n);
<# 
(define xfib (foreign-lambda int "fib" int))
(do ((i 0 (+ i 1))) ((> i 10))
  (printf "~A " (xfib i)))
(newline)
@end verbatim
The syntax @code{#>...<#} allows you to include literal C (typically external declarations) in your Chicken code. We access @code{fib} by defining a @code{foreign-lambda} for it, in this case saying that the function takes one integer argument (the @code{int} after the function name), and that it returns an integer result (the @code{int} before.) Now we can invoke @code{xfib} as though it were an ordinary Scheme function. 

@verbatim
$ gcc -c fib.c
$ csc -o fib-user fib.o fib-user.scm
$ ./fib-user
0 1 1 2 3 5 8 13 21 34 55 
@end verbatim
Those who are interfacing to substantial C libraries should consider using the  easyffi egg, or SWIG. 

Back to @ref{The User's Manual, The User's Manual} Next: @ref{Basic mode of operation, Basic mode of operation} 

@node Basic mode of operation, Using the compiler, Getting started, Top
@chapter 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 @emph{unit}s.  A unit is a single compiled object module that contains a number of toplevel expressions that are executed either when the unit is the @emph{main} unit or if the unit is @emph{used}.  To use a unit, the unit has to be @emph{declare}ed as used, like this:

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

@example
(declare (unit UNITNAME))
@end example
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 @code{unit} declaration.

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

@example
(include @strong{"FILENAME"})
@end example
Macro definitions are only available when processed by @code{include} or @code{require-for-syntax}. 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 @code{define-macro} in @ref{Non-standard macros and special forms, Substitution forms and macros}).

On platforms that support dynamic loading of compiled code ( Windows, most ELF based systems like Linux or BSD, MacOS X, and others) code can be compiled into a shared object @code{.dll}, @code{.so}, @code{.dylib}) and loaded  dynamically into a running application.

Previous: @ref{Getting started, Getting started} Next: @ref{Using the compiler, Using the compiler}  

@node Using the compiler, Using the interpreter, Basic mode of operation, Top
@chapter Using the compiler

@menu
* Using the compiler - Compiler command line format::
* Using the compiler - Runtime options::
* Using the compiler - Examples::
* Using the compiler - Extending the compiler::
* Using the compiler - Distributing compiled C files::

@end menu


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

@verbatim
csc -help
@end verbatim
on the command line for more information.

@node Using the compiler - Compiler command line format, Using the compiler - Runtime options,  , Using the compiler
@section Compiler command line format


@verbatim
chicken FILENAME {OPTION}
@end verbatim
@code{FILENAME} is the complete pathname of the source file that is to be translated into C. A filename argument of @code{-} specifies that the source text should be read from standard input. Note that the filename has to be the first argument to @code{chicken}.

Possible options are:

@table @b
@item -analyze-only

Stop compilation after first analysis pass.
@item -benchmark-mode

Equivalent to @code{-no-trace -no-lambda-info -optimize-level 3} @code{-fixnum-arithmetic -disable-interrupts -block -lambda-lift}.
@item -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 @code{eval} and unused toplevel bindings are removed.
@item -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 @code{case-insensitive} feature identifier.
@item -check-imports

Search for references to undefined global variables. For each library unit accessed via @code{(declare (uses ...))}, the compiler will search a file named @code{UNITNAME.exports} in the current include path and load its contents into the @emph{import-table} (if found). Also, export-information for extensions (accessed through @code{(require-extension ...)}) will be searched and stored in the import-table. If a required extension does not provide explicit export-information a @code{.exports} file is searched (as with used units). After the analysis phase of the compiler, referenced toplevel variables for which no assignment was found will generate a warning. Also, re-assignments of imported variables will trigger a warning.
@item -check-syntax

Aborts compilation process after macro-expansion and syntax checks.
@item -debug MODES

Enables one or more compiler debugging modes. @code{MODES} is a string of characters that select debugging information about the compiler that will be printed to standard output.

@end table
@verbatim
    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
    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
    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
@end verbatim
@table @b
@item -debug-level LEVEL

Selects amount of debug-information. @code{LEVEL} should be an integer.