source: project/wiki/man/4/Using the compiler @ 27885

Last change on this file since 27885 was 27885, checked in by svnwiki, 7 years ago

Anonymous wiki edit for IP [199.84.164.114]: Distributing compiled C files updates with warning for Mac OS X user and buildtag.h that was also required.

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