source: project/chicken/branches/cmi/chicken.1 @ 12248

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

updated chicken manpage

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