chickadee » csc

Using the compiler

The csc compiler driver provides a convenient interface to the basic Scheme-to-C translator (chicken) and takes care for compiling and linking the generated C files into executable code. Enter

csc -help

on the command line for a list of options.

Compiler command line format

chicken FILENAME OPTION ...

FILENAME is the pathname of the source file that is to be compiled. A filename argument of - (a single dash) specifies that the source text should be read from standard input.

Basic command-line options

-analyze-only
Stop compilation after first analysis pass.
-block
Enable block-compilation. When this option is specified, the compiler assumes that global variables are not modified outside of 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.
-clustering
Combine groups of local procedures into dispatch-loops, if possible.
-consult-inline-file FILENAME
load file with definitions for cross-module inlining generated by a previous compiler invocation via -emit-inline-file. Implies -inline.
-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. Use -debug h to see a list of available debugging options.
-debug-level LEVEL
Selects amount of debug-information. LEVEL should be an integer, where 0 is equivalent to -no-trace -no-lambda-info, 1 is equivalent to -no-trace, 2 is the default behaviour and 3 is equivalent to -debug-mode.
-disable-interrupts
Equivalent to the (disable-interrupts) declaration. No interrupt-checks are generated for compiled programs, which disables thread context switches in this (and only this) compilation unit.
-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-all-import-libraries
emit import libraries for all modules defined in the current compilation unit (see also: -emit-import-library).
-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.
-regenerate-import-libraries
Always emit new import libraries, even when their contents haven't changed. The default behaviour is to preserve existing import libraries.
-emit-import-library MODULE
Specifies that an import library named MODULE.import.scm for the named module should be generated (equivalent to using the emit-import-library declaration).
-emit-inline-file FILENAME
Write procedures that can be globally inlined in internal form to FILENAME, if global inlining is enabled. Implies -inline -local. If the inline-file would be empty (because no procedure would be inlinable) no file is generated and any existing inline-file with that name is deleted.
-emit-link-file FILENAME
write a list of statically linked extensions to FILENAME, used for identifying the static objects that need to be linked to an executable.
-emit-types-file FILENAME
Write type-information for declarations of user-defined and globally visible variables to a file of the given name. The generated file is suitable for use with the -consult-types-file option.
-explicit-use
Disables automatic use of the units library, eval and expand. 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.
-feature SYMBOL
Registers SYMBOL to be a valid feature identifier for cond-expand. Multiple symbols may be given, if comma-separated.
-fixnum-arithmetic
Equivalent to the (fixnum-arithmetic) declaration. Assume all mathematical operations use small integer arguments.
-heap-size NUMBER
Sets a fixed heap size of NUMBER bytes for the generated executable. 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 500 kilobytes. Note that only half of it is in use at every given time. Note also that by default the heap is dynamically resized unless this option is given.
-help
Print a summary of available options and the format of the command line parameters and exit the compiler.
-ignore-repository
Do not load any extensions from the repository (treat the repository as empty). Also do not consult compiled (only interpreted) import libraries in import forms.
-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 : (UNIX) or ; (Windows).
-inline
Enable procedure inlining for known procedures of a size below the threshold (which can be set through the -inline-limit option).
-inline-global
Enable cross-module inlining (in addition to local inlining). Implies -inline. For more information, see also Declarations.
-inline-limit THRESHOLD
Sets the maximum size of a potentially inlinable procedure. The default threshold is 20.
-keyword-style STYLE
Enables alternative keyword syntax, where STYLE may be either prefix (as in Common Lisp, e.g. :keyword), suffix (as in DSSSL, e.g. keyword:) or none (where only the #:KEYWORD is allowed). Any other value is ignored. The default is suffix.
-keep-shadowed-macros
Do not remove macro definitions with the same name as assigned toplevel variables (the default is to remove the macro definition).
-link NAME
Links the extension NAME with the compiled program and uses it as a unit. Multiple names may be given and should be separated by commas.
-local
Assume toplevel variables defined in the current compilation unit are not externally modified. This gives the compiler more opportunities for inlining. Note that this may result in counter-intuitive and non-standard behaviour: an asssignment to an exported toplevel variable executed in a different compilation unit or in evaluated code will possibly not be seen by code executing in the current compilation unit.
-lfa2
Does an additional lightweight flow-analysis pass on the fully optimized program to remove more type checks.
-module NAME
wraps the compiled code in an implicit module of the given NAME, importing the scheme and chicken modules.
-no-argc-checks
disable argument count checks
-no-bound-checks
disable bound variable checks
-no-feature SYMBOL
Disables the predefined feature-identifier SYMBOL. Multiple comma-separated symbols may be given.
-no-lambda-info
Do not emit additional information for each lambda expression (currently the argument-list, after alpha-conversion/renaming).
-no-module-registration
Do not generate module-registration code in the compiled code. This is needed if you want to use an import library that is generated by other means (manually, for example), or when you do not intend to use modules in the program at runtime (using eval).
-no-parentheses-synonyms
Disables list delimiter synonyms, [..] and {...} for (...).
-no-procedure-checks
disable procedure call checks
-no-procedure-checks-for-usual-bindings
disable procedure call checks only for usual bindings
-no-procedure-checks-for-toplevel-bindings
disable bound and procedure call checks for calls to procedures referenced through a toplevel variable.
-no-symbol-escape
Disables support for escaped symbols, the |...| form.
-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.
LEVELEquivalent flagsExplanation
0 -no-usual-integrations -no-compiler-syntax No optimization
1 -optimize-leaf-routines Minimal optimization
2 (Default) -optimize-leaf-routines -inline -lfa2 Enable optimizations that do not break standard compliance
3 -optimize-leaf-routines -local -inline -lfa2 -inline-global -specialize Maximal optimization, while still "safe"
4 -optimize-leaf-routines -local -inline -lfa2 -inline-global -specialize -unsafe Maximal optimization, "unsafe"
5 (or higher) -optimize-leaf-routines -block -inline -lfa2 -inline-global -specialize -unsafe -disable-interrupts -no-trace -no-lambda-info -clustering All possible optimizations, "unsafe"
-output-file FILENAME
Specifies the pathname of the generated C file. Default is to use the source filename with the extension replaced by .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.<randomnumber>. 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 -help 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. Only profiling information for global procedures will be collected. See the -:p option under "Runtime options" below for statistical profiling support.
-profile-name FILENAME
Specifies name of the generated profile information (which defaults to PROFILE.<randomnumber>. 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.
-r5rs-syntax
Disables the CHICKEN extensions to R5RS syntax. Does not disable non-standard read syntax.
-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). Use this only when you know what you are doing.
-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. If -uses NAME is also given on the command line, then any occurrences of -require-extension NAME are replaced with (declare (uses NAME)). Multiple names may be given and should be separated by commas.
-setup-mode
When locating extension, search the current directory first. By default, extensions are located first in the extension repository, where chicken-install stores compiled extensions and their associated metadata.
-specialize
Enable simple flow-analysis for doing some type-directed optimizations.
-static
Link extensions statically, if possible.
-strict-types
Assume that the type of variables is not changed by assignments. This gives more type-information during specialization, but violating this assumption will result in unsafe and incorrectly behaving code. Use with care.
-consult-types-file FILENAME
load additional type database from FILENAME. Type-definitions in FILENAME will override previous type-definitions.
-compile-syntax
Makes macros also available at run-time. By default macros are not available at run-time.
-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.
-uses NAME
Use definitions from the library unit NAME. This is equivalent to -prelude "(declare (uses NAME))". Multiple arguments may be given, separated by , (comma).
-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).
-unroll-limit LIMIT
Specifies how often direct recursive calls should be "unrolled" by inlining the procedure body at the call site. The default limit is 1.
-version
Prints the version and some copyright information and exit the compiler.
-verbose
enables output of notes that are not necessarily warnings but might be of interest.

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

Further options

Enter

 csc -help

to see a list of all supported options and short aliases to basic options.

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. These are filtered out by the startup code and will not be contained in the result of (command-line-arguments).

-:?
Shows a list of the available runtime options and exits the program.
-:aNUMBER
Specifies the length of the buffer for recording a trace of the last invoked procedures. Defaults to 16.
-:ANUMBER
Specifies fixed temporary stack size. This is used mostly for apply. If you supply a zero size (the default), the temporary stack will be dynamically reallocated as needed.
-:b
Enter a read-eval-print-loop when an error is encountered.
-:B
Sounds a bell (by writing ASCII 7 to stdout) on every major garbage collection.
-: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 at runtime.
-:D
Prints some more debug-information at runtime.
-:g
Prints information about garbage-collection.
-:G
Force GUI mode (show error messages in dialog box if running under MacOS X or Windows).
-:H
Before terminating, dump heap usage to stderr.
-:fNUMBER
Specifies the maximal number of currently pending finalizers before finalization is forced.
-:hNUMBER
Specifies fixed 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.
-:hiNUMBER
Specifies the initial heap size (this number includes both heap semispaces, therefore only half of it is actually available to the program).
-:hmNUMBER
Specifies a maximal heap size (including both semispaces). The default is (2GB - 15).
-:hfNUMBER
If the free heap space is less than this number (8M by default), then the heap is grown. This is approximately the amount of generated heap garbage in bytes after which a major garbage collection will happen.
-:hsPERCENTAGE
Sets the shrink rate of the heap in percent. The heap is shrunk to PERCENTAGE when the watermark is reached. 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).
-:huPERCENTAGE
Sets the memory usage watermark below which heap shrinking is triggered. The default is 25.
-:o
Disables detection of stack overflows at run-time.
-:p
Enable collection of statistics for profiling purposes and write to PROFILE.pid on exit. This functions at a granularity defined by the trace information in the binary and libraries: each traced function will show up in the output. See the -profile compiler option for instrumentation-based profiling. The PROFILE.pid format is compatible with the format generated by instrumentation-based profiling.
-:PFREQUENCY
Same as -:p but set the sampling frequency in microseconds (default is 10000 microseconds or every 10 milliseconds).
-:r
Writes trace output to stderr. This option has no effect in files compiled with the -no-trace options.
-:RNUMBER
Specifies the initial number passed to seed the rand() PRNG (which is currently only used to randomize the symbol table). If not supplied, the current system time is used. This can be useful when debugging or benchmarking because it removes a source of nondeterminism which can affect how soon or how often the GC is triggered.
-:sNUMBER
Specifies stack size.
-:tNUMBER
Specifies symbol table size.
-: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.

Runtime argument values should be given as integers, optionally followed by a unit modifier for kilobytes (suffixed with K or k), megabytes (suffixed with M or m), or gigabytes (suffixed with G or g).

Runtime options may be combined, like -:dc, but everything following an argument is ignored. So -:oh64m is OK, but -:h64mo will not disable stack overflow checks.

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 and user-post-analysis-pass can be set to procedures that are called to perform certain compilation passes in addition to the usual processing.

These parameters are provided by the (chicken compiler user-pass) module.

user-options-passparameter

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.

user-read-passparameter

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.

user-preprocessor-passparameter

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.

user-passparameter

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.

user-post-analysis-passparameter

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 #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 #f for the last 'opt pass. For information about the contents of the program database contact the author.

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 are seen by user-pass.


Previous: Using the interpreter

Next: Deviations from the standard

Contents »