source: project/chicken/branches/prerelease/chicken.1 @ 13240

Last change on this file since 13240 was 13240, checked in by felix winkelmann, 11 years ago

merged trunk svn rev. 13239 into prerelease

File size: 13.4 KB
Line 
1.\" dummy line
2.TH CHICKEN 1 "10 Sep 2002"
3
4.SH NAME
5
6chicken \- A Scheme\-to\-C compiler
7
8.SH SYNOPSIS
9
10.B chicken
11.I pathname
12[
13.I option ...
14]
15
16.SH DESCRIPTION
17
18.I Chicken
19is a compiler for the programming language
20.I Scheme
21supporting most of the features as described in the
22.I Revised^5 Report on
23.I the Algorithmic Language Scheme
24\.
25
26.SH OPTIONS
27
28.TP
29.B \-analyze\-only
30Stop compilation after first analysis pass.
31
32.B \-benchmark\-mode
33Equivalent to
34.B \-optimize\-level\ 3\ \-fixnum\-arithmetic\ \-disable\-interrupts\ \-lambda\-lift
35.B \-block\ \-no\-lambda\-info
36
37.TP
38.B \-block
39Enable block-compilation. When this option is specified, the compiler assumes
40that global variables are not modified outside this compilation-unit.
41
42.TP
43.B \-case\-insensitive
44Enables the reader to read symbols case-insensitive. The default is to read
45case-sensitive (in violation of R5RS).
46This option registers the
47.B case\-insensitive
48feature identifier.
49
50.TP
51.B \-check\-imports
52Search for references to undefined global variables.
53
54.TP
55.B \-check\-syntax
56Aborts compilation process after macro-expansion and syntax checks.
57
58.TP
59.BI \-database\-size \ number
60Specifies the initial size of the analysis-database. Should only be used if
61extremely large files are to be compiled.
62
63.TP
64.BI \-debug \ modes
65Enables one or more debugging modes. See the User's Manual for more information.
66
67.TP
68.BI \-debug\-level \ level
69Selects amount of debug-information.
70.I level
71should be an integer.
72.P
73.br
74.B \ \ \ \ 0
75-no-trace -no-lambda-info
76.br
77.B \ \ \ \ 1
78-no-trace
79.br
80.B \ \ \ \ 2
81nothing.
82
83.TP
84.B \-disable\-c\-syntax\-checks
85Disable basic syntax checking of embedded C code fragments.
86
87.TP
88.B \-disable\-compiler\-macros
89Disable expansion of compiler macros.
90
91.TP
92.B \-disable\-interrupts
93Equivalent to
94.B \-prelude\ \'(declare\ (interrupts-disabled))\'
95\.
96
97.TP
98.B \-disable\-stack\-overflow\-checks
99Disables detection of stack-overflows.
100
101.TP
102.BI \-disable\-warning \ class
103Disables specific
104.I class
105of warnings, may be given multiple times.
106.P
107.br
108.B \ \ \ \ ext\ \ \
109Suspect extension use.
110.br
111.B \ \ \ \ type\ \
112Suspect type/literal use.
113.br
114.B \ \ \ \ usage\
115Suspect feature use.
116.br
117.B \ \ \ \ style\
118Suspect feature use.
119.br
120.B \ \ \ \ syntax
121Suspect sytax form.
122.br
123.B \ \ \ \ redef\
124Redefinition of builtin binding.
125.br
126.B \ \ \ \ var\ \ \
127Suspect variable use.
128
129.TP
130.B \-dynamic
131This option should be used when compiling files intended to be loaded dynamically into
132a running Scheme program.
133
134.TP
135.BI \-epilogue \ filename
136Includes the file named
137.I filename
138at the end of the compiled source file.
139The include-path is not searched. This option may be given multiple times.
140
141.TP
142.B \-emit\-debug\-info
143Emit additional information for each
144.B lambda
145expression (currently the argument-list,
146after alpha-conversion/renaming).
147
148.TP
149.BI \-emit\-exports \ filename
150Write exported toplevel variables to file
151.I filename
152\.
153
154.TP
155.B \-emit\-external\-prototypes\-first
156Emit prototypes for callbacks defined with
157.B define\-external
158before any
159other foreign declarations. This is sometimes useful, when C/C++ code embedded into
160the a Scheme program has to access the callbacks. By default the prototypes are emitted
161after foreign declarations.
162
163.TP
164.BI \-emit\-inline\-file \ filename
165Write procedures that can be globally inlined in internal form to
166.I filename
167, if global inlining is enabled. Implies "-inline -local".
168
169.TP
170.B \-explicit\-use
171Disables automatic use of the units
172.I library
173and
174.I eval
175\. Use this option if compiling a library unit
176instead of an application unit.
177
178.TP
179.BI \-extend \ filename
180Loads a Scheme file,
181.I filename
182, before compilation commences. This feature can be used to extend the compiler.
183
184.TP
185.B \-extension
186Mostly equivalent to
187.B \-prelude\ \'(define-extension\ NAME)\'
188where
189.B NAME
190is the basename of the currently compiled file. Note that if you want to compile a file
191as a normal (dynamically loadable) extension library, you should also pass the
192.B \-shared
193option.
194
195.TP
196.BI \-feature \ symbol
197Registers
198.I symbol
199to be a valid feature identifier for
200.B cond\-expand
201
202.TP
203.B \-fixnum\-arithmetic
204Equivalent to
205.B \-prelude\ \'(declare\ (fixnum))\'
206\.
207
208.TP
209.BI \-heap\-size \ number
210Sets the static heap-size of the generated executable to
211.I number
212bytes. The parameter may be
213followed by a
214.B M
215or
216.B K
217suffix which stand for mega- and kilo-bytes, respectively. The default heap-size is 16 megabytes.
218
219.TP
220.BI \-heap\-initial\-size \ number
221Sets the size that the heap of the compiled application should have at startup time.
222
223.TP
224.BI \-heap\-growth \ percentage
225Sets the heap-growth rate for the compiled program at compile time.
226
227.TP
228.BI \-heap\-shrinkage \ percentage
229Sets the heap-shrinkage rate for the compiled program at compile time.
230
231.TP
232.B \-help
233Print a summary of available options and the format of the command-line
234parameters and exit the compiler.
235
236.TP
237.B \-ignore\-repository
238Do not load any extensions from the repository (treat repository as empty). Also
239do not consult compiled (only interpreted) import libraries in
240.I import
241forms.
242
243.TP
244.BI \-import\ pathname
245Read exports from linked or loaded libraries from given file. Implies
246.B \-check\-imports
247
248.TP
249.BI \-include\-path \ pathname
250Specifies an additional search path for files included via the
251.I include
252special form. This option may be given multiple times.
253
254.TP
255.B \-inline
256Enables procedure inlining.
257
258.TP
259.B \-inline\-global
260Enable cross-module inlining.
261
262.TP
263.BI \-inline\-limit \ threshold
264Sets the maximum size of potentially inlinable procedures.
265
266.TP
267.BI \-keep\-shadowed\-macros
268Do not remove macro definitions with the same name as assigned toplevel
269variables (the default is to remove the macro definition).
270
271.TP
272.BI \-keyword\-style \ style
273Enables alternative keyword syntax, where style may be either
274.B prefix
275(as in Common Lisp),
276.B suffix
277(as in DSSSL) or
278.B none
279Any other value is ignored. The default is
280.B suffix
281\.
282
283.TP
284.B \-lambda\-lift
285Enable the optimization known as lambda-lifting.
286
287.TP
288.B \-local
289Assume toplevel variables defined in the current compilation unit are
290not externally modified.
291
292.TP
293.B \-no\-trace
294Disable generation of tracing information. If a compiled executable should halt
295due to a runtime error, then a file containing a stack-trace will be written to
296the current directory under the name
297.I STACKTRACE
298\. Each line in the created file gives the name and the line-number (if
299available) of a procedure call. With this option given, the generated code is
300slightly faster.
301
302.TP
303.B \-no\-warnings
304Disable generation of compiler warnings.
305
306.TP
307.BI \-nursery \ number
308
309.TP
310.BI \-stack\-size \ number
311Sets the size of the first heap-generation of the generated executable to
312.I number
313bytes. The parameter may
314be followed by a
315.B M
316or
317.B K
318suffix. The default stack-size depends on the target platform.
319
320.TP
321.BI \-optimize\-leaf\-routines
322Enable leaf routine optimization.
323
324.TP
325.BI \-optimize\-level \ level
326Enables certain sets of optimization options.
327.I level
328should be an integer. Each optimization level corresponds to a certain set of optimization option
329as shown in the following list:
330.P
331.br
332.B \ \ \ \ 0
333nothing
334.br
335.B \ \ \ \ 1
336-optimize-leaf-routines
337.br
338.B \ \ \ \ 2
339-optimize-leaf-routines -usual-integrations
340.br
341.B \ \ \ \ 3
342-optimize-leaf-routines -usual-integrations -unsafe
343
344.TP
345.BI \-output\-file \ filename
346Specifies the pathname of the generated C file. Default is
347.I FILENAME.c
348\.
349
350.TP
351.BI \-postlude \ expressions
352Add
353.I expressions
354after all other toplevel expressions in the compiled file.
355This option may be given multiple times. Processing of this option takes place
356after processing of
357.BI \-epilogue
358\.
359
360.TP
361.BI \-prelude \ expressions
362Add
363.I expressions
364before all other toplevel expressions in the compiled file.
365This option may be given multiple times. Processing of this option takes place
366before processing of
367.B \-prologue
368\.
369
370.TP
371.B \-profile
372.B \-accumulate\-profile
373Instruments the source code to count procedure calls and execution times. After
374the program terminates (either via an explicit
375.B exit
376or implicitly), profiling statistics are written to a file named
377.B PROFILE.<PID>
378where <PID> is the process ID of the program being profiled.
379Each line of the generated file contains a list with the procedure name,
380the number of calls and the time spent executing it. Use the
381.B chicken\-profile
382program to display the profiling information in a more user-friendly form.
383
384.TP
385.BI \-profile\-name \ filename
386Specifies the name of the generated profile information file. Only useful
387in combination with the
388.B \-profile
389or
390.B \-accumulate-profile
391options.
392
393.TP
394.BI \-prologue \ filename
395Includes the file named
396.I filename
397at the start of the compiled source file.
398The include-path is not searched. This option may be given multiple times.
399
400.TP
401.B \-release
402Print release number and exit.
403
404.TP
405.BI \-require\-extension \ name
406Loads the syntax-extension
407.I name
408before the source program is processed. This is identical to adding
409.B require\-extension\ NAME
410at the start of
411the compiled program.
412
413.TP
414.B \-run\-time\-macros
415Makes low-level macros (defined with
416.B define\-macro
417also available at run-time. By default
418low-level macros are not available at run-time. Note that highlevel-macros ("syntax-case")
419defined in compiled code are never available at run-time.
420
421.TP
422.B \-to\-stdout
423Write compiled code to standard output instead of creating a
424.I .c
425file.
426
427.TP
428.BI \-unit \ name
429Compile this file as a library unit.
430
431.TP
432.B \-unsafe
433Disable runtime safety checks.
434
435.TP
436.B \-unsafe\-libraries
437Marks the generated file for being linked with the unsafe runtime system. This
438should be used when generating shared object files that are to be loaded
439dynamically. If the marker is present, any attempt to load code compiled with
440this option will signal an error.
441
442.TP
443.BI \-uses \ name
444Use definitions in the given library unit.
445
446.TP
447.B \-usual\-integrations
448Specifies that standard procedures and certain internal procedures are never redefined, and can
449be inlined. This is equivalent to declaring
450.I (usual\-integrations)
451\.
452
453.TP
454.B \-verbose
455Prints progress information to standard output during compilation.
456
457.TP
458.B \-version
459Prints the version and some copyright information and exit the compiler.
460
461.SH ENVIRONMENT\ VARIABLES
462
463.TP
464.B CHICKEN_PREFIX
465Is used as a prefix directory for support files, include-files and libraries.
466
467.TP
468.B CHICKEN_INCLUDE_PATH
469Contains one or more pathnames where the compiler should additionally look for
470include-files, separated by
471.B \;
472characters.
473
474.TP
475.B CHICKEN_OPTIONS
476Holds a string of default compiler options that should apply to every invocation of
477.B chicken
478\.
479
480.SH RUNTIME\ OPTIONS
481After successful compilation a C source file is generated and can be compiled
482with a C compiler. Executables generated with
483.B chicken
484(and the
485.B chicken
486program itself) accept a small set of runtime options.
487
488.TP
489.B \-:?
490Shows a list of the available runtime options and exits the program.
491
492.TP
493.B \-:aNUMBER
494Specifies the length of the buffer for recording a trace of the last invoked
495procedures. Defaults to 8.
496
497.TP
498.B \-:b
499Enter a read-eval-print-loop when an error is encountered.
500
501.TP
502.B \-:B
503Sounds a bell (ASCII 7) on every major garbage collection.
504
505.TP
506.B \-:c
507Forces console mode. Currently this is only used in the interpreter (csi) to
508force output of the
509.I #;N>
510prompt even if stdin is not a terminal (for example if running in an emacs buffer under Windows).
511
512.TP
513.B \-:d
514Prints some debug-information at runtime.
515
516.TP
517.B \-:D
518Prints some more debug-information at runtime.
519
520.TP
521.B \-:fNUMBER
522Specifies the maximal number of currently pending finalizers before finalization is forced.
523
524.TP
525.B \-:hNUMBER
526Specifies fixed heap size
527
528.TP
529.B \-:hgPERCENTAGE
530Sets the growth rate of the heap in percent. If the heap is exhausted, then it
531will grow by
532.B PERCENTAGE
533\. The default is 200.
534
535.TP
536.B \-:hiNUMBER
537Specifies the initial heap size
538
539.TP
540.B \-:hmNUMBER
541Specifies a maximal heap size. The default is (2GB - 15).
542
543.TP
544.B \-:hsPERCENTAGE
545Sets the shrink rate of the heap in percent. If no more than a quarter of
546.B PERCENTAGE
547of the heap is used, then it will shrink to
548.B PERCENTAGE
549\. The default
550is 50. Note: If you want to make sure that the heap never shrinks, specify a
551value of 0. (this can be useful in situations where an optimal heap-size is
552known in advance).
553
554.TP
555.B \-:o
556Disables detection of stack overflows at run-time.
557
558.TP
559.B \-:r
560Writes trace output to stderr. This option has no effect with in files compiled with the
561.B -no-trace
562options.
563
564.TP
565.B \-:sNUMBER
566Specifies stack size.
567
568.TP
569.B \-:tNUMBER
570Specifies symbol table size.
571
572.TP
573.B \-:w
574Enables garbage collection of unused symbols. By default unused and unbound
575symbols are not garbage collected.
576
577.TP
578.B \-:x
579Raises uncaught exceptions of separately spawned threads in primordial thread.
580By default uncaught exceptions in separate threads are not handled, unless the
581primordial one explicitly joins them. When warnings are enabled (the default)
582and
583.B \-:x
584is not given, a warning will be shown, though.
585
586.P
587The
588.B NUMBER
589argument values may be given in bytes, in kilobytes (suffixed with K or k),
590in megabytes (suffixed with M or m), or in gigabytes (suffixed with G or g).
591Runtime options may be combined, like
592.B \-:dc
593, but everything following a
594.B NUMBER
595argument is ignored. So
596.B \-:wh64m
597is OK, but
598.B \-:h64mw
599will not enable GC of unused symbols.
600
601.SH DOCUMENTATION
602
603More information can be found in the
604.I Chicken\ User's\ Manual
605
606.SH AUTHORS
607
608Felix L. Winkelmann and The Chicken Team.
609
610.SH SEE ALSO
611
612.BR csc(1)
613.BR chicken-bug(1)
Note: See TracBrowser for help on using the repository browser.