source: project/chicken/trunk/manual/Using the compiler @ 15896

Last change on this file since 15896 was 15896, checked in by Ivan Raikov, 10 years ago

merged manual from wiki

File size: 25.8 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Using the compiler
5
6The interface to {{chicken}} is intentionally simple.  System
7dependent makefiles, shell-scripts or batch-files should perform
8any necessary steps before and after invocation of {{chicken}}.
9A program named {{csc}} provides a more convenient and concise
10interface to the Scheme- and C-compilers and linker. Enter
11
12 csc -help
13
14on the command line for more information.
15
16=== Compiler command line format
17
18 chicken FILENAME {OPTION}
19
20{{FILENAME}} is the complete pathname of the source file that is to
21be translated into C. A filename argument of {{-}} specifies that
22the source text should be read from standard input. Note that the filename
23has to be the first argument to {{chicken}}.
24
25Possible options are:
26
27; -analyze-only : Stop compilation after first analysis pass.
28
29; -benchmark-mode : Equivalent to {{-no-trace -no-lambda-info -optimize-level 4}} {{-fixnum-arithmetic -disable-interrupts -block -inline -lambda-lift}}.
30
31; -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.
32
33; -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.
34
35; -check-syntax : Aborts compilation process after macro-expansion and syntax checks.
36
37; -consult-inline-file FILENAME : load file with definitions for cross-module inlining generated by a previous compiloer invocation via {{-emit-inline-file}}. Implies {{-inline}}.
38
39; -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.
40
41     t          show time needed for compilation
42     b          show breakdown of time needed for each compiler pass
43     o          show performed optimizations
44     r          show invocation parameters
45     s          show program-size information and other statistics
46     a          show node-matching during simplification
47     p          show execution of compiler sub-passes
48     l          show lambda-lifting information
49     m          show GC statistics during compilation
50     n          print the line-number database
51     c          print every expression before macro-expansion
52     u          lists all unassigned global variable references
53     d          lists all assigned global variables
54     x          display information about experimental features
55     D          when printing nodes, use node-tree output
56     N          show the real-name mapping table
57     0          show database before lambda-lifting pass
58     T          show expressions after converting to node tree
59     L          show expressions after lambda-lifting
60     M          show syntax-/runtime-requirements
61     1          show source expressions
62     2          show canonicalized expressions
63     3          show expressions converted into CPS
64     4          show database after each analysis pass
65     5          show expressions after each optimization pass
66     6          show expressions after each inlining pass
67     7          show expressions after complete optimization
68     8          show database after final analysis
69     9          show expressions after closure conversion
70
71; -debug-level LEVEL : Selects amount of debug-information. {{LEVEL}} should be an integer.
72
73     -debug-level 0             is equivalent to -no-trace -no-lambda-info
74     -debug-level 1             is equivalent to -no-trace
75     -debug-level 2             does nothing (the default)
76
77; -disable-interrupts : Equivalent to the {{(disable-interrupts)}} declaration. No interrupt-checks are generated for compiled programs.
78
79; -disable-stack-overflow-checks : Disables detection of stack overflows. This is equivalent to running the compiled executable with the {{-:o}} runtime option.
80
81; -disable-warning CLASS : Disables specific class of warnings, may be given multiple times. The following classes are defined:
82
83     usage              warnings related to command-line arguments
84     type               warnings related to type-conversion
85     ext                warnings related to extension libraries
86     var                warnings related to variable- and syntax-definitions and use
87     const              warnings related to constant-definitions
88     syntax             syntax-related warnings
89     redef              warnings about redefinitions of standard- or extended-bindings
90     call               warnings related to known procedure calls
91     ffi                warnings related to the foreign function interface
92
93; -dynamic : This option should be used when compiling files intended to be loaded dynamically into a running Scheme program.
94
95; -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.
96
97; -emit-all-import-libraries : emit import libraries for all modules defined in the current compulation unit (see also: {{-emit-import-library}}).
98
99; -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.
100
101; -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).
102
103; -emit-inline-file FILENAME : Write procedures that can be globally inlined in internal form to {{FILENAME}}, if global inlining is enabled. Implies {{-inline -local}}.
104
105; -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.
106
107; -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.
108
109; -feature SYMBOL : Registers {{SYMBOL}} to be a valid feature identifier for {{cond-expand}}. Multiple symbols may be given, if comma-separated.
110
111; -fixnum-arithmetic : Equivalent to {{(fixnum-arithmetic)}} declaration. Assume all mathematical operations use small integer arguments.
112
113; -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.
114
115; -heap-initial-size NUMBER : Sets the size that the heap of the compiled application should have at startup time.
116
117; -heap-growth PERCENTAGE : Sets the heap-growth rate for the compiled program at compile time (see: {{-:hg}}).
118
119; -heap-shrinkage PERCENTAGE : Sets the heap-shrinkage rate for the compiled program at compile time (see: {{-:hs}}).
120
121; -help : Print a summary of available options and the format of the command line parameters and exit the compiler.
122
123; -ignore-repository : Do not load any extensions from the repository (treat repository as empty). Also do not consult compiled (only interpreted) import libraries in {{import}} forms.
124
125; -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 {{;}}.
126
127; -inline : Enable procedure inlining for known procedures of a size below the threshold (which can be set through the {{-inline-limit}} option).
128
129; -inline-global : Enable cross-module inlining (in addition to local inlining). Implies {{-inline}}. For more information, see also [[Declarations]].
130
131; -inline-limit THRESHOLD : Sets the maximum size of a potentially inlinable procedure. The default threshold is {{20}}.
132
133; -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}}.
134
135; -keep-shadowed-macros : Do not remove macro definitions with the same name as assigned toplevel variables (the default is to remove the macro definition).
136
137; -lambda-lift : Enable the optimization known as lambda-lifting.
138
139; -local : Assume toplevel variables defined in the current compilation unit are not externally modified.
140
141; -no-argc-checks : disable argument count checks
142
143; -no-bound-checks : disable bound variable checks
144
145; -no-lambda-info : Don't emit additional information for each {{lambda}} expression (currently the argument-list, after alpha-conversion/renaming).
146
147; -no-parentheses-synonyms STYLE : Disables list delimiter synonyms, [..] and {...} for (...).
148
149; -no-procedure-checks : disable procedure call checks
150
151; -no-procedure-checks-for-usual-bindings :  disable procedure call checks only for usual bindings
152
153; -no-symbol-escape : Disables support for escaped symbols, the |...| form.
154
155; -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.
156
157; -no-warnings : Disable generation of compiler warnings.
158
159; -nursery NUMBER :
160; -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.
161
162; -optimize-leaf-routines : Enable leaf routine optimization.
163
164; -optimize-level LEVEL : Enables certain sets of optimization options. {{LEVEL}} should be an integer.
165
166     -optimize-level 0          does nothing.
167     -optimize-level 1          is equivalent to -optimize-leaf-routines
168     -optimize-level 2          is currently the same as -optimize-level 1 -inline
169     -optimize-level 3          is equivalent to -optimize-leaf-routines -local -inline
170     -optimize-level 4          is equivalent to -optimize-leaf-routines -local -inline -unsafe
171
172; -output-file FILENAME : Specifies the pathname of the generated C file. Default is {{FILENAME.c}}.
173
174; -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}}.
175
176; -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}}.
177
178; -profile :
179; -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.
180
181; -profile-name FILENAME : Specifies name of the generated profile information (which defaults to {{PROFILE}}. Implies {{-profile}}.
182
183; -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.
184
185; -r5rs-syntax : Disables the Chicken extensions to R5RS syntax. Does not disable [[Non-standard read syntax|non-standard read syntax]].
186
187; -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}}).
188
189; -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 {{,}}.
190
191; -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.
192
193; -scrutinize : Enable simple flow-analysis to catch common type errors and argument/result mismatches. You can also use the {{scrutinize}} declaration to enable scrutiny.
194
195; -static-extension NAME : similar to {{-require-extension NAME}}, but links extension statically (also applies for an explicit {{(require-extension NAME)}}).
196
197; -types FILENAME : load additional type database from {{FILENAME}}. Type-definitions in {{FILENAME}} will override previous type-definitions.
198
199; -compile-syntax : Makes macros also available at run-time. By default macros are not available at run-time.
200
201; -to-stdout : Write compiled code to standard output instead of creating a {{.c}} file.
202
203; -unit NAME : Compile this file as a library unit. Equivalent to {{-prelude "(declare (unit NAME))"}}
204
205; -unsafe : Disable runtime safety checks.
206
207; -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.
208
209; -uses NAME : Use definitions from the library unit {{NAME}}. This is equivalent to {{-prelude "(declare (uses NAME))"}}. Multiple arguments may be given, separated by {{,}}.
210
211; -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)}}.
212
213; -version : Prints the version and some copyright information and exit the compiler.
214
215; -verbose : Prints progress information to standard output during compilation.
216
217The environment variable {{CHICKEN_OPTIONS}} can be set to a string
218with default command-line options for the compiler.
219
220=== Runtime options
221
222After successful compilation a C source file is generated and can be
223compiled with a C compiler. Executables generated with CHICKEN (and the
224compiler itself) accept a small set of runtime options:
225
226; {{-:?}} : Shows a list of the available runtime options and exits the program.
227
228; {{-:aNUMBER}} : Specifies the length of the buffer for recording a trace of the last invoked procedures. Defaults to 16.
229
230; {{-:b}} : Enter a read-eval-print-loop when an error is encountered.
231
232; {{-:B}} : Sounds a bell (ASCII 7) on every major garbage collection.
233
234; {{-: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).
235
236; {{-:d}} : Prints some debug-information at runtime.
237
238; {{-:D}} : Prints some more debug-information at runtime.
239
240; {{-:fNUMBER}} : Specifies the maximal number of currently pending finalizers before finalization is forced.
241
242; {{-:hNUMBER}} : Specifies fixed heap size
243
244; {{-: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.
245
246; {{-:hiNUMBER}} : Specifies the initial heap size
247
248; {{-:hmNUMBER}} : Specifies a maximal heap size. The default is (2GB - 15).
249
250; {{-: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).
251
252; {{-:o}} : Disables detection of stack overflows at run-time.
253
254; {{-:r}} : Writes trace output to stderr. This option has no effect with in files compiled with the {{-no-trace}} options.
255
256; {{-:sNUMBER}} : Specifies stack size.
257
258; {{-:tNUMBER}} : Specifies symbol table size.
259
260; {{-:w}} : Enables garbage collection of unused symbols. By default unused and unbound symbols are not garbage collected.
261
262; {{-: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.
263
264The argument values may be given in bytes, in kilobytes (suffixed with
265{{K}} or {{k}}), in megabytes (suffixed with {{M}}
266or {{m}}), or in gigabytes (suffixed with {{G}}
267or {{g}}). Runtime options may be combined, like {{-:dc}},
268but everything following a {{NUMBER}} argument is ignored. So
269{{-:wh64m}} is OK, but {{-:h64mw}} will not enable GC of
270unused symbols.
271=== Examples
272
273==== A simple example (with one source file)
274
275To compile a Scheme program (assuming a UNIX-like environment) consisting of a single source file, perform the following steps.
276
277===== Writing your source file
278
279In this example we will assume your source file is called {{foo.scm}}:
280
281<enscript highlight=scheme>
282;;; foo.scm
283
284(define (fac n)
285  (if (zero? n)
286      1
287      (* n (fac (- n 1))) ) )
288
289(write (fac 10))
290(newline)
291</enscript>
292
293===== Compiling your program
294
295Compile the file {{foo.scm}}:
296
297 % csc foo.scm
298
299This will produce the {{foo}} executable:
300
301 % ls
302 foo  foo.scm
303
304===== Running your program
305
306To run your newly compiled executable use:
307
308 % foo
309 3628800
310
311If you get a {{foo: command not found}} error, you might want to try with {{./foo}} instead
312(or, in Unix machines, modify your {{PATH}} environment variable to include your current directory).
313==== An example with multiple files
314
315If multiple bodies of Scheme code are to be combined into a single
316executable, then we have to compile each file and link the resulting
317object files together with the runtime system.
318
319Let's consider an example where your program consists of multiple source files.
320
321===== Writing your source files
322
323The declarations in these files specify which of the compiled files is the main
324module, and which is the library module. An executable can only have
325one main module, since a program has only a single entry-point. In this
326case {{foo.scm}} is the main module, because it doesn't have a
327{{unit}} declaration:
328
329<enscript highlight=scheme>
330;;; foo.scm
331
332; The declaration marks this source file as dependant on the symbols provided
333; by the bar unit:
334(declare (uses bar))
335
336(write (fac 10)) (newline)
337</enscript>
338
339{{bar.scm}} will be our library:
340
341<enscript highlight=scheme>
342;;; bar.scm
343
344; The declaration marks this source file as the bar unit.  The names of the
345; units and your files don't need to match.
346(declare (unit bar))
347
348(define (fac n)
349  (if (zero? n)
350      1
351      (* n (fac (- n 1))) ) )
352</enscript>
353
354===== Compiling and running your program
355
356You should compile your two files with the following commands:
357
358 % csc -c bar.scm
359 % csc -c foo.scm
360
361That should produce two files, {{bar.o}} and {{foo.o}}.
362They contain the code from your source files in compiled form.
363
364To link your compiled files use the following command:
365
366 % csc foo.o bar.o -o foo
367
368This should produce the {{foo}} executable, which you can run just as in the previous example.
369At this point you can also erase the {{*.o}} files.
370
371You could avoid one step and link the two files just as {{foo.scm}} is compiled:
372
373 % csc -c bar.scm
374 % csc foo.scm bar.o -o foo
375
376Note that if you want to distribute your program, you might want it to
377follow the GNU Coding Standards.  One relatively easy way to achieve
378this is to use Autoconf and Automake, two tools made for this specific
379purpose.
380
381=== Extending the compiler
382
383The compiler supplies a couple of hooks to add user-level passes to the
384compilation process. Before compilation commences any Scheme source files
385or compiled code specified using the {{-extend}} option are loaded
386and evaluated.  The parameters {{user-options-pass, user-read-pass,
387user-preprocessor-pass, user-pass}} and {{user-post-analysis-pass}} can be set
388to procedures that are called to perform certain compilation passes
389instead of the usual processing (for more information about parameters
390see: [[Supported language]].
391
392; [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.
393
394; [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.
395
396; [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.
397
398; [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.
399
400; [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 {{#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.
401
402Loaded code (via the {{-extend}} option) has access to the library
403units {{extras, srfi-1, srfi-4, utils, regex}} and the pattern matching macros.
404Multithreading is not available.
405
406Note that the macroexpansion/canonicalization phase of the compiler adds
407certain forms to the source program.  These extra expressions are not
408seen by {{user-preprocessor-pass}} but by {{user-pass}}.
409
410=== Distributing compiled C files
411
412It is relatively easy to create distributions of Scheme projects that
413have been compiled to C.  The runtime system of CHICKEN consists of only
414two handcoded C files ({{runtime.c}} and {{chicken.h}}), plus
415the file {{chicken-config.h}}, which is generated by the build process. All
416other modules of the runtime system and the extension libraries are just
417compiled Scheme code. The following example shows a minimal application, which
418should run without changes on the most frequent operating systems, like Windows,
419Linux or FreeBSD:
420
421Let's take a simple example.
422
423<enscript highlight=scheme>
424; hello.scm
425
426(print "Hello, world!")
427</enscript>
428
429  % chicken hello.scm -optimize-level 3 -output-file hello.c
430
431Compiled to C, we get {{hello.c}}. We need the files {{chicken.h}} and
432{{runtime.c}}, which contain the basic runtime system, plus the three
433basic library files {{library.c}}, {{eval.c}} and {{extras.c}} which
434contain the same functionality as the library linked into a plain
435CHICKEN-compiled application, or which is available by default in the
436interpreter, {{csi}}:
437
438  % cd /tmp
439  %echo '(print "Hello World.")' > hello.scm
440  % cp $CHICKEN_BUILD/runtime.c .
441  % cp $CHICKEN_BUILD/library.c .
442  % cp $CHICKEN_BUILD/eval.c    .
443  % cp $CHICKEN_BUILD/extras.c  .
444  % gcc -static -Os -fomit-frame-pointer runtime.c library.c eval.c \
445    extras.c hello.c -o hello -lm
446
447Now we have all files together, and can create an tarball containing all the files:
448
449 % tar cf hello.tar Makefile hello.c runtime.c library.c eval.c extras.c chicken.h
450 % gzip hello.tar
451
452This is naturally rather simplistic. Things like enabling dynamic loading, estimating
453the optimal stack-size and selecting supported features of the host system would need
454more configuration- and build-time support. All this can be addressed using more
455elaborate build-scripts, makefiles or by using autoconf/automake.
456
457Note also that the size of the application can still be reduced by removing {{extras}} and
458{{eval}} and compiling {{hello.scm}} with the {{-explicit-use}} option.
459
460For more information, study the CHICKEN source code and/or get in
461contact with the author.
462
463---
464Previous: [[Basic mode of operation]]
465
466Next: [[Using the interpreter]]
Note: See TracBrowser for help on using the repository browser.