source: project/wiki/man/5/Using the compiler @ 37689

Last change on this file since 37689 was 37689, checked in by sven, 5 months ago
File size: 21.6 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Using the compiler
5
6The {{csc}} compiler driver provides a convenient interface to
7the basic Scheme-to-C translator ({{chicken}}) and takes care
8for compiling and linking the generated C files into executable
9code. Enter
10
11 csc -help
12
13on the command line for a list of options.
14
15=== Compiler command line format
16
17 chicken FILENAME OPTION ...
18
19{{FILENAME}} is the pathname of the source file that is to
20be compiled. A filename argument of {{-}} (a single dash) specifies that
21the source text should be read from standard input.
22
23==== Basic command-line options
24
25; -analyze-only : Stop compilation after first analysis pass.
26
27; -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.
28
29; -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.
30
31; -check-syntax : Aborts compilation process after macro-expansion and syntax checks.
32
33; -clustering : Combine groups of local procedures into dispatch-loops, if possible.
34
35; -consult-inline-file FILENAME : load file with definitions for cross-module inlining generated by a previous compiler invocation via {{-emit-inline-file}}. Implies {{-inline}}.
36
37; -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.
38
39; -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}}.
40
41; -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.
42
43; -disable-stack-overflow-checks : Disables detection of stack overflows. This is equivalent to running the compiled executable with the {{-:o}} runtime option.
44
45; -dynamic : This option should be used when compiling files intended to be loaded dynamically into a running Scheme program.
46
47; -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.
48
49; -emit-all-import-libraries : emit import libraries for all modules defined in the current compulation unit (see also: {{-emit-import-library}}).
50
51; -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.
52
53; -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).
54
55; -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.
56
57; -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.
58
59; -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.
60
61; -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.
62
63; -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.
64
65; -feature SYMBOL : Registers {{SYMBOL}} to be a valid feature identifier for {{cond-expand}}. Multiple symbols may be given, if comma-separated.
66
67; -fixnum-arithmetic : Equivalent to the {{(fixnum-arithmetic)}} declaration. Assume all mathematical operations use small integer arguments.
68
69; -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.
70
71; -help : Print a summary of available options and the format of the command line parameters and exit the compiler.
72
73; -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.
74
75; -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).
76
77; -inline : Enable procedure inlining for known procedures of a size below the threshold (which can be set through the {{-inline-limit}} option).
78
79; -inline-global : Enable cross-module inlining (in addition to local inlining). Implies {{-inline}}. For more information, see also [[Declarations]].
80
81; -inline-limit THRESHOLD : Sets the maximum size of a potentially inlinable procedure. The default threshold is {{20}}.
82
83; -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}}.
84
85; -keep-shadowed-macros : Do not remove macro definitions with the same name as assigned toplevel variables (the default is to remove the macro definition).
86
87; -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.
88
89; -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.
90
91; -lfa2 : Does an additional lightweight flow-analysis pass on the fully optimized program to remove more type checks.
92
93; -module NAME : wraps the compiled code in an implicit module of the given {{NAME}}, importing the {{scheme}} and {{chicken}} modules.
94
95; -no-argc-checks : disable argument count checks
96
97; -no-bound-checks : disable bound variable checks
98
99; -no-feature SYMBOL : Disables the predefined feature-identifier {{SYMBOL}}. Multiple comma-separated symbols may be given.
100
101; -no-lambda-info : Do not emit additional information for each {{lambda}} expression (currently the argument-list, after alpha-conversion/renaming).
102
103; -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}}).
104
105; -no-parentheses-synonyms : Disables list delimiter synonyms, [..] and {...} for (...).
106
107; -no-procedure-checks : disable procedure call checks
108
109; -no-procedure-checks-for-usual-bindings :  disable procedure call checks only for usual bindings
110
111; -no-procedure-checks-for-toplevel-bindings :  disable bound and procedure call checks for calls to procedures referenced through a toplevel variable.
112
113; -no-symbol-escape : Disables support for escaped symbols, the |...| form.
114
115; -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.
116
117; -no-warnings : Disable generation of compiler warnings.
118
119; -nursery NUMBER :
120; -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.
121
122; -optimize-leaf-routines : Enable leaf routine optimization.
123
124; -optimize-level LEVEL : Enables certain sets of optimization options. {{LEVEL}} should be an integer. Level {{0}} is equivalent to {{-no-usual-integrations -no-compiler-syntax}} (no optimization), level {{1}  is equivalent to {{-optimize-leaf-routines}} (minimal optimization), level {{2}} is equivalent to {{-optimize-leaf-routines -inline}} (enable optimizations that do not break standard compliance, this is the default), level {{3}} is equivalent to {{-optimize-leaf-routines -local -inline -inline-global -specialize}} (maximal optimization, while still "safe"), level {{4}} is equivalent to {{-optimize-leaf-routines -local -inline -inline-global -specialize -unsafe}} (maximal optimization, "unsafe") and any higher level is equivalent to {{-optimize-leaf-routines -block -inline -inline-global -specialize -unsafe -disable-interrupts -no-trace -no-lambda-info -clustering -lfa2}} (all possible optimizations, "unsafe").
125
126; -output-file FILENAME : Specifies the pathname of the generated C file. Default is to use the source filename with the extension replaced by {{.c}}.
127
128; -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}}.
129
130; -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}}.
131
132; -profile :
133; -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|"Runtime options"]] below for statistical profiling support.
134
135; -profile-name FILENAME : Specifies name of the generated profile information (which defaults to {{PROFILE.<randomnumber>}}. Implies {{-profile}}.
136
137; -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.
138
139; -r5rs-syntax : Disables the CHICKEN extensions to R5RS syntax. Does not disable non-standard read syntax.
140
141; -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.
142
143; -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.
144
145; -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.
146
147; -specialize : Enable simple flow-analysis for doing some type-directed optimizations.
148
149; -static : Link extensions statically, if possible.
150
151; -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.
152
153; -consult-types-file FILENAME : load additional type database from {{FILENAME}}. Type-definitions in {{FILENAME}} will override previous type-definitions.
154
155; -compile-syntax : Makes macros also available at run-time. By default macros are not available at run-time.
156
157; -to-stdout : Write compiled code to standard output instead of creating a {{.c}} file.
158
159; -unit NAME : Compile this file as a library unit. Equivalent to {{-prelude "(declare (unit NAME))"}}
160
161; -unsafe : Disable runtime safety checks.
162
163; -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).
164
165; -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)}}.
166
167; -version : Prints the version and some copyright information and exit the compiler.
168
169; -verbose : enables output of notes that are not necessarily warnings but might be of interest.
170
171The environment variable {{CHICKEN_OPTIONS}} can be set to a string
172with default command-line options for the compiler.
173
174==== Further options
175
176Enter
177
178  csc -help
179
180to see a list of all supported options and short aliases to basic options.
181
182=== Runtime options
183
184After successful compilation a C source file is generated and can be
185compiled with a C compiler. Executables generated with CHICKEN (and the
186compiler itself) accept a small set of runtime options. These are filtered out
187by the startup code and will not be contained in the result of
188{{(command-line-arguments)}}.
189
190; {{-:?}} : Shows a list of the available runtime options and exits the program.
191
192; {{-:aNUMBER}} : Specifies the length of the buffer for recording a trace of the last invoked procedures. Defaults to 16.
193
194; {{-: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.
195
196; {{-:b}} : Enter a read-eval-print-loop when an error is encountered.
197
198; {{-:B}} : Sounds a bell (by writing ASCII 7 to stdout) on every major garbage collection.
199
200; {{-: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).
201
202; {{-:d}} : Prints some debug-information at runtime.
203
204; {{-:D}} : Prints some more debug-information at runtime.
205
206; {{-:g}} : Prints information about garbage-collection.
207
208; {{-:G}} : Force GUI mode (show error messages in dialog box if running under MacOS X or Windows).
209
210; {{-:H}} : Before terminating, dump heap usage to stderr.
211
212; {{-:fNUMBER}} : Specifies the maximal number of currently pending finalizers before finalization is forced.
213
214; {{-:hNUMBER}} : Specifies fixed heap size
215
216; {{-: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.
217
218; {{-:hiNUMBER}} : Specifies the initial heap size
219
220; {{-:hmNUMBER}} : Specifies a maximal heap size. The default is (2GB - 15).
221
222; {{-: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).
223
224; {{-:o}} : Disables detection of stack overflows at run-time.
225
226; {{-: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.
227
228; {{-:PFREQUENCY}} : Same as {{-:p}} but set the sampling frequency in microseconds (default is 10000 microseconds or every 10 milliseconds).
229
230; {{-:r}} : Writes trace output to stderr. This option has no effect in files compiled with the {{-no-trace}} options.
231
232; {{-:sNUMBER}} : Specifies stack size.
233
234; {{-:tNUMBER}} : Specifies symbol table size.
235
236; {{-: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.
237
238Runtime argument values should be given as integers, optionally followed
239by a unit modifier for kilobytes (suffixed with {{K}} or {{k}}),
240megabytes (suffixed with {{M}} or {{m}}), or gigabytes (suffixed with
241{{G}} or {{g}}).
242
243Runtime options may be combined, like {{-:dc}}, but everything following
244an argument is ignored. So {{-:oh64m}} is OK, but {{-:h64mo}} will not
245disable stack overflow checks.
246
247=== Extending the compiler
248
249The compiler supplies a couple of hooks to add user-level passes to the
250compilation process. Before compilation commences any Scheme source files
251or compiled code specified using the {{-extend}} option are loaded
252and evaluated. The parameters {{user-options-pass}}, {{user-read-pass}},
253{{user-preprocessor-pass}}, {{user-pass}} and {{user-post-analysis-pass}}
254can be set to procedures that are called to perform certain compilation
255passes in addition to the usual processing.
256
257These parameters are provided by the {{(chicken compiler user-pass)}}
258module.
259
260<parameter>user-options-pass</parameter>
261
262Holds 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.
263
264<parameter>user-read-pass</parameter>
265
266Holds 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.
267
268<parameter>user-preprocessor-pass</parameter>
269
270Holds 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.
271
272<parameter>user-pass</parameter>
273
274Holds 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.
275
276<parameter>user-post-analysis-pass</parameter>
277
278Holds 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.
279
280Note that the macroexpansion/canonicalization phase of the compiler adds
281certain forms to the source program. These extra expressions are not
282seen by {{user-preprocessor-pass}}, but are seen by {{user-pass}}.
283
284---
285Previous: [[Using the interpreter]]
286
287Next: [[Deviations from the standard]]
Note: See TracBrowser for help on using the repository browser.