source: project/chicken/branches/release/chicken.1 @ 7276

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

merged trunk

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