source: project/chicken/trunk/chicken.1 @ 6423

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

info installation fix by Eugene Ossintsev; PROFILE file has PID as extension (suggested by Robin Lee Powell)

File size: 10.7 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 that global variables are not modified outside this compilation-unit.
40
41.TP
42.B \-case\-insensitive
43Enables the reader to read symbols case-insensitive. The default is to read case-sensitive (in violation of R5RS).
44This option registers the
45.B case\-insensitive
46feature identifier.
47
48.TP
49.B \-check\-imports
50Search for references to undefined global variables.
51
52.TP
53.B \-check\-syntax
54Aborts compilation process after macro-expansion and syntax checks.
55
56.TP
57.B \-compress\-literals\ threshold
58Compiles quoted literals that exceed the size
59.BI threshold
60as strings
61and parse the strings at run-time. This reduces the size of the code and
62speeds up compile-times of the host C compiler, but has a small run-time
63performance penalty. The size of a literal is computed by counting recursively the objects
64in the literal, so a vector counts as 1 plus the count of the elements,
65a pair counts as the counts of the car and the cdr, respectively.
66All other objects count 1.
67
68.TP
69.BI \-database\-size \ number
70Specifies the initial size of the analysis-database. Should only be used if extremely large files are to be compiled.
71
72.TP
73.BI \-debug \ modes
74Enables one or more debugging modes. See the User's Manual for more information.
75
76.TP
77.BI \-debug\-level \ level
78Selects amount of debug-information.
79.I level
80should be an integer.
81.P
82.br
83.B \ \ \ \ 0
84-no-trace -no-lambda-info
85.br
86.B \ \ \ \ 1
87-no-trace
88.br
89.B \ \ \ \ 2
90nothing.
91
92.TP
93.B \-disable\-c\-syntax\-checks
94Disable basic syntax checking of embedded C code fragments.
95
96.TP
97.B \-disable\-compiler\-macros
98Disable expansion of compiler macros.
99
100.TP
101.B \-disable\-interrupts
102Equivalent to
103.B \-prelude\ "(declare\ (interrupts-disabled))"
104
105.TP
106.B \-disable\-stack\-overflow\-checks
107Disables detection of stack-overflows.
108
109.TP
110.B \-disable\-warning\ class
111Disables specific class of warnings, may be given multiple times.
112
113.TP
114.B \-dynamic
115This option should be used when compiling files intended to be loaded dynamically into
116a running Scheme program.
117
118.TP
119.BI \-epilogue \ filename
120Includes the file named
121.I filename
122at the end of the compiled source file.
123The include-path is not searched. This option may be given multiple times.
124
125.TP
126.I \-emit\-debug\-info
127Emit additional information for each
128.B lambda
129expression (currently the argument-list,
130after alpha-conversion/renaming).
131
132.TP
133.BI \-emit\-exports\ filename
134Write exported toplevel variables to file
135.B filename
136
137.TP
138.I \-emit\-external\-prototypes\-first
139Emit prototypes for callbacks defined with
140.B define\-external
141before any
142other foreign declarations. This is sometimes useful, when C/C++ code embedded into
143the a Scheme program has to access the callbacks. By default the prototypes are emitted
144after foreign declarations.
145
146.TP
147.B \-explicit\-use
148Disables automatic use of the units
149.I library
150and
151.I eval
152\. Use this option if compiling a library unit
153instead of an application unit.
154
155.TP
156.BI \-extend \ filename
157Loads a Scheme file before compilation commences. This feature can be used to extend the compiler.
158
159.TP
160.B \-extension
161Mostly equivalent to
162.B \-prelude\ \'\(define-extension\ NAME\)\'
163where
164.B NAME
165is the basename of the currently compiled file. Note that if you want to compile a file
166as a normal (dynamically loadable) extension library, you should also pass the
167.I \-shared
168option.
169
170.TP
171.BI \-feature \ symbol
172Registers
173.I symbol
174to be a valid feature identifier for
175.B cond\-expand
176
177.TP
178.B \-fixnum\-arithmetic
179Equivalent to
180.B \-prelude\ "(declare\ (fixnum))"
181
182.TP
183.BI \-heap\-size \ number
184Sets the static heap-size of the generated executable to
185.I number
186bytes. The parameter may be
187followed by a
188.B M
189or
190.B K
191suffix which stand for mega- and kilobytes, respectively. The default heap-size is 16 megabytes.
192
193.TP
194.BI \-heap\-initial\-size \ number
195Sets the size that the heap of the compiled application should have at startup time.
196
197.TP
198.BI \-heap\-growth \ percentage
199Sets the heap-growth rate for the compiled program at compile time.
200
201.TP
202.BI \-heap\-shrinkage \ percentage
203Sets the heap-shrinkage rate for the compiled program at compile time.
204
205.TP
206.B \-help
207Print a summary of available options and the format of the command-line parameters and exit the compiler.
208
209.TP
210.BI \-import\ pathname
211Read exports from linked or loaded libraries from given file. Implies
212.B \-check\-imports
213
214.TP
215.BI \-include\-path \ pathname
216Specifies an additional search path for files included via the
217.I include
218special form. This option may be given multiple times. If the environment variable
219.B CHICKEN_INCLUDE_PATH
220is set, it should contain a list of alternative include
221pathnames separated by
222.I \;
223\.
224The environment variable
225.B CHICKEN_HOME
226is also considered as a search path.
227
228.TP
229.B \-inline
230Enables procedure inlining.
231
232.TP
233.BI \-inline\-limit threshold
234Sets the maximum size of potentially inlinable procedures.
235
236.TP
237.BI \-keep\-shadowed\-macros
238Do not remove macro definitions with the same name as assigned toplevel variables (the default is to remove the macro definition).
239
240.TP
241.BI \-keyword\-style style
242Enables alternative keyword syntax, where style may be either
243.B prefix
244(as in Common Lisp),
245.B suffix
246(as in DSSSL) or
247.B none
248Any other value is ignored. The default is \texttt{suffix}.
249
250.TP
251.B \-lambda\-lift
252Enable the optimization known as lambda-lifting.
253
254.TP
255.B \-no\-trace
256Disable generation of tracing information. If a compiled executable should halt due to a runtime error,
257then a file containing a stack-trace will be written to the current directory under the name
258.I STACKTRACE
259\. Each line in the created file gives the name and the line-number (if available) of a procedure call.
260With this option given, the generated code is slightly faster.
261
262.TP
263.B \-no\-warnings
264Disable generation of compiler warnings.
265
266.TP
267.BI \-nursery \ number
268.TP
269.BI \-stack\-size \ number
270Sets the size of the first heap-generation of the generated executable to
271.I number
272bytes. The parameter may
273be followed by a
274.B M
275or
276.B K
277suffix. The default stack-size depends on the target platform.
278
279.TP
280.BI \-optimize\-leaf\-routines
281Enable leaf routine optimization.
282
283.TP
284.BI \-optimize\-level \ level
285Enables certain sets of optimization options.
286.I level
287should be an integer. Each optimization level corresponds to a certain set of optimization option
288as shown in the following list:
289.P
290.br
291.B \ \ \ \ 0
292nothing
293.br
294.B \ \ \ \ 1
295-optimize-leaf-routines
296.br
297.B \ \ \ \ 2
298-optimize-leaf-routines -usual-integrations
299.br
300.B \ \ \ \ 3
301-optimize-leaf-routines -usual-integrations -unsafe
302
303.TP
304.BI \-output\-file \ filename
305Specifies the pathname of the generated C file. Default is
306.I FILENAME.c
307\.
308
309.TP
310.BI \-postlude \ expressions
311Add
312.I expressions
313after all other toplevel expressions in the compiled file.
314This option may be given multiple times. Processing of this option takes place after processing of
315.BI \-epilogue
316\.
317
318.TP
319.BI \-prelude \ expressions
320Add
321.I expressions
322before all other toplevel expressions in the compiled file.
323This option may be given multiple times. Processing of this option takes place before processing of
324.B \-prologue
325\.
326
327.TP
328.B \-profile
329.B \-accumulate\-profile
330Instruments the source code to count procedure calls and execution times. After the program terminates
331(either via an explicit
332.B exit
333or implicitly), profiling statistics are written to a file named
334.B PROFILE.<PID>
335where <PID> is the process ID of the program being profiled.
336Each line of the generated file contains a list with the procedure name,
337the number of calls and the time spent executing it. Use the
338.B chicken\-profile
339program to display the profiling information in a more user-friendly form.
340
341.TP
342.B \-profile\-name\ filename
343Specifies the name of the generated profile information file. Only useful
344in combination with the
345.B \-profile
346or
347.B \-accumulate-profile
348options.
349
350.TP
351.BI \-prologue \ filename
352Includes the file named
353.I filename
354at the start of the compiled source file.
355The include-path is not searched. This option may be given multiple times.
356
357.TP
358.B \-quiet
359Disables output of compile information.
360
361.TP
362.B \-release
363Print release number and exit.
364
365.TP
366.BI \-require\-extension \ name
367Loads the syntax-extension
368.I name
369before the source program is processed. This is identical to adding
370.B require\-extension\ NAME
371at the start of
372the compiled program.
373
374.TP
375.B \-run\-time\-macros
376Makes low-level macros (defined with
377.B define\-macro
378also available at run-time. By default
379low-level macros are not available at run-time. Note that highlevel-macros ("syntax-case")
380 defined in compiled code are never available at run-time.
381
382.TP
383.B \-to\-stdout
384Write compiled code to standard output instead of creating a
385.I .c
386file.
387
388.TP
389.BI \-unit \ name
390Compile this file as a library unit.
391
392.TP
393.B \-unsafe
394Disable runtime safety checks.
395
396.TP
397.B \-unsafe\-libraries
398Marks the generated file for being linked with the unsafe runtime system. This
399should be used when generating shared object files that are to be loaded
400dynamically. If the marker is present, any attempt to load code compiled with
401this option will signal an error.
402
403.TP
404.BI \-uses \ name
405Use definitions in the given library unit.
406
407.TP
408.B \-usual\-integrations
409Specifies that standard procedures and certain internal procedures are never redefined, and can
410be inlined. This is equivalent to declaring
411.I (usual\-integrations)
412\.
413
414.TP
415.B \-verbose
416Prints progress information to standard output during compilation.
417
418.TP
419.B \-version
420Prints the version and some copyright information and exit the compiler.
421
422.SH ENVIRONMENT\ VARIABLES
423
424.TP
425.B CHICKEN_HOME
426Should contain the pathname where support- and include-files can be found.
427
428.TP
429.B CHICKEN_INCLUDE_PATH
430Contains one or more pathnames where the compiler should additionally look for include-files, separated by
431.B \;
432characters.
433
434.TP
435.B CHICKEN_OPTIONS
436Holds a string of default compiler options that should apply to every invocation of
437.B chicken
438\.
439
440.SH DOCUMENTATION
441
442More information can be found in the
443.I Chicken\ User's\ Manual
444
445.SH BUGS
446
447Submit bug reports by e-mail to
448.I felix@call-with-current-continuation.org
449, preferrably using the
450.B chicken\-bug
451tool.
452
453.SH AUTHOR
454
455.I Chicken
456was implemented by Felix L. Winkelmann (felix@call-with-current-continuation.org).
457
458.SH SEE ALSO
459
460.BR csc(1)
461.BR chicken-bug(1)
Note: See TracBrowser for help on using the repository browser.