chicken.texi

Scheme跨平台编译器

Specifies symbol table size.
@item @code{-:w}

Enables garbage collection of unused symbols. By default unused and unbound symbols are not garbage collected.
@item @code{-: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 @code{-:x} is not given, a warning will be shown, though.

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

@node Using the compiler - Examples, Using the compiler - Extending the compiler, Using the compiler - Runtime options, Using the compiler
@section Examples

@menu
* Using the compiler - Examples - A simple example ;with one source file;::
* Using the compiler - Examples - An example with multiple files::

@end menu


@node Using the compiler - Examples - A simple example ;with one source file;, Using the compiler - Examples - An example with multiple files,  , Using the compiler - Examples
@subsection A simple example (with one source file)

@menu
* Using the compiler - Examples - A simple example ;with one source file; - Writing your source file::
* Using the compiler - Examples - A simple example ;with one source file; - Compiling your program::
* Using the compiler - Examples - A simple example ;with one source file; - Running your program::

@end menu


To compile a Scheme program (assuming a UNIX-like environment) consisting of a single source file, perform the following steps.

@node Using the compiler - Examples - A simple example ;with one source file; - Writing your source file, Using the compiler - Examples - A simple example ;with one source file; - Compiling your program,  , Using the compiler - Examples - A simple example ;with one source file;
@subsubsection Writing your source file


In this example we will assume your source file is called @code{foo.scm}:

@example
@emph{;;; foo.scm
}
(@strong{define} (@strong{fac} n)
  (@strong{if} (zero? n)
      1
      (* n (fac (- n 1))) ) )

(write (fac 10))
(newline)
@end example
@node Using the compiler - Examples - A simple example ;with one source file; - Compiling your program, Using the compiler - Examples - A simple example ;with one source file; - Running your program, Using the compiler - Examples - A simple example ;with one source file; - Writing your source file, Using the compiler - Examples - A simple example ;with one source file;
@subsubsection Compiling your program


Compile the file @code{foo.scm}:

@verbatim
% csc foo.scm
@end verbatim
This will produce the @code{foo} executable:

@verbatim
% ls
foo  foo.scm
@end verbatim
@node Using the compiler - Examples - A simple example ;with one source file; - Running your program,  , Using the compiler - Examples - A simple example ;with one source file; - Compiling your program, Using the compiler - Examples - A simple example ;with one source file;
@subsubsection Running your program


To run your newly compiled executable use:

@verbatim
% foo
3628800
@end verbatim
If you get a @code{foo: command not found} error, you might want to try with @code{./foo} instead (or, in Unix machines, modify your @code{PATH} environment variable to include your current directory).

@node Using the compiler - Examples - An example with multiple files,  , Using the compiler - Examples - A simple example ;with one source file;, Using the compiler - Examples
@subsection An example with multiple files

@menu
* Using the compiler - Examples - An example with multiple files - Writing your source files::
* Using the compiler - Examples - An example with multiple files - Compiling and running your program::

@end menu


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.

Let's consider an example where your program consists of multiple source files.

@node Using the compiler - Examples - An example with multiple files - Writing your source files, Using the compiler - Examples - An example with multiple files - Compiling and running your program,  , Using the compiler - Examples - An example with multiple files
@subsubsection Writing your source files


The declarations in these files 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 @code{foo.scm} is the main module, because it doesn't have a @code{unit} declaration:

@example
@emph{;;; foo.scm
}
@emph{; The declaration marks this source file as dependant on the symbols provided
}@emph{; by the bar unit:
}(declare (uses bar))

(write (fac 10)) (newline)
@end example
@code{bar.scm} will be our library:

@example
@emph{;;; bar.scm
}
@emph{; The declaration marks this source file as the bar unit.  The names of the
}@emph{; units and your files don't need to match.
}(declare (unit bar))

(@strong{define} (@strong{fac} n)
  (@strong{if} (zero? n)
      1
      (* n (fac (- n 1))) ) )
@end example
@node Using the compiler - Examples - An example with multiple files - Compiling and running your program,  , Using the compiler - Examples - An example with multiple files - Writing your source files, Using the compiler - Examples - An example with multiple files
@subsubsection Compiling and running your program


You should compile your two files with the following commands:

@verbatim
% csc -c bar.scm
% csc -c foo.scm
@end verbatim
That should produce two files, @code{bar.o} and @code{foo.o}. They contain the code from your source files in compiled form.

To link your compiled files use the following command:

@verbatim
% csc foo.o bar.o -o foo
@end verbatim
This should produce the @code{foo} executable, which you can run just as in the previous example. At this point you can also erase the @code{*.o} files.

You could avoid one step and link the two files just as @code{foo.scm} is compiled:

@verbatim
% csc -c bar.scm
% csc foo.scm bar.o -o foo
@end verbatim
Note that if you want to distribute your program, you might want it to follow the GNU Coding Standards.  One relatively easy way to achieve this is to use Autoconf and Automake, two tools made for this specific purpose. 

@node Using the compiler - Extending the compiler, Using the compiler - Distributing compiled C files, Using the compiler - Examples, Using the compiler
@section 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 @code{-extend} option are loaded and evaluated.  The parameters @code{user-options-pass, user-read-pass, user-preprocessor-pass, user-pass, user-pass-2} and @code{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: @ref{Supported language, Supported language}.

@table @b
@item [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 @code{-} (hyphen) removed and are converted to symbols.  Note that this parameter is invoked @b{before} processing of the @code{-extend} option, and so can only be changed in compiled user passes.
@item [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 @code{-prelude} options. The second argument is a list of source files including any files specified by @code{-prologue} and @code{-epilogue}. The third argument is a list of strings specified using @code{-postlude} options. The procedure should return a list of toplevel Scheme expressions.
@item [parameter] user-preprocessor-pass

Holds a procedure of one argument. This procedure is applied to each toplevel expression in the source file @b{before} macro-expansion. The result is macro-expanded and compiled in place of the original expression.
@item [parameter] user-pass

Holds a procedure of one argument. This procedure is applied to each toplevel expression @b{after} macro-expansion.  The result of the procedure is then compiled in place of the original expression.
@item [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.
@item [parameter] user-post-analysis-pass

Holds a procedure that will be called after every performed program analysis pass. The procedure (when defined) will be called with seven arguments: a symbol indicating the analysis pass, the program database, the current node graph, 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, a pass iteration count, and an analysis continuation flag. 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 @code{#f}, if no such entry is available. The setter procedure is called with three arguments: the symbol and key and the new value. The pass iteration count currently is meaningful only for the 'opt pass. The analysis continuation flag will be @code{#f} for the last 'opt pass. For information about the contents of the program database contact the author.

@end table
Loaded code (via the @code{-extend} option) has access to the library units @code{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 @code{user-preprocessor-pass} but by @code{user-pass}.

@node Using the compiler - Distributing compiled C files,  , Using the compiler - Extending the compiler, Using the compiler
@section 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 (@code{runtime.c} and @code{chicken.h}), plus the file @code{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 example.

@example
@emph{; hello.scm
}
(print @strong{"Hello, world!"})
@end example
@verbatim
 % chicken hello.scm -optimize-level 3 -output-file hello.c
@end verbatim
Compiled to C, we get @code{hello.c}. We need the files @code{chicken.h} and @code{runtime.c}, which contain the basic runtime system, plus the three basic library files @code{library.c}, @code{eval.c} and @code{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 interpreter, @code{csi}:

@verbatim
 % cd /tmp
 %echo '(print "Hello World.")' > hello.scm
 % cp $CHICKEN_BUILD/runtime.c .
 % cp $CHICKEN_BUILD/library.c .
 % cp $CHICKEN_BUILD/eval.c    .
 % cp $CHICKEN_BUILD/extras.c  .
 % gcc -static -Os -fomit-frame-pointer runtime.c library.c eval.c \
   extras.c hello.c -o hello -lm
@end verbatim
Now we have all files together, and can create an tarball containing all the files:

@verbatim
% tar cf hello.tar Makefile hello.c runtime.c library.c eval.c extras.c chicken.h
% gzip hello.tar
@end verbatim
This is 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.

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

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

Previous: @ref{The User's Manual, The User's Manual}

Next: @ref{Using the interpreter, Using the interpreter}  

@node Using the interpreter, Supported language, Using the compiler, Top
@chapter Using the interpreter

@menu
* Using the interpreter - Interpreter command line format::
* Using the interpreter - Writing Scheme scripts::
* Using the interpreter - Toplevel commands::
* Using the interpreter - toplevel-command::
* Using the interpreter - History access::
* Using the interpreter - set-describer!::
* Using the interpreter - Auto-completion and edition::
* Using the interpreter - Accessing documentation::

@end menu


CHICKEN provides an interpreter named @code{csi} for evaluating Scheme programs and expressions interactively.

@node Using the interpreter - Interpreter command line