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

Last change on this file since 5945 was 5945, checked in by felix winkelmann, 12 years ago

renamed some tools in misc/; apply hack fix on x86-64 (again); re-added manual

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