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

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

setup-utils removal was quite incomplete; added -ignore-repository; msvc Makefile fix (thanks to Ivan Shcheklein); lots of mindless hacking

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.B \-ignore\-repository
204Do not load any extensions from the repository (treat repository as empty).
205
206.TP
207.BI \-import\ pathname
208Read exports from linked or loaded libraries from given file. Implies
209.B \-check\-imports
210
211.TP
212.BI \-include\-path \ pathname
213Specifies an additional search path for files included via the
214.I include
215special form. This option may be given multiple times. If the environment variable
216.B CHICKEN_INCLUDE_PATH
217is set, it should contain a list of alternative include
218pathnames separated by
219.I \;
220\.
221
222.TP
223.B \-inline
224Enables procedure inlining.
225
226.TP
227.B \-inline\-global
228Enable cross-module inlining.
229
230.TP
231.BI \-inline\-limit threshold
232Sets the maximum size of potentially inlinable procedures.
233
234.TP
235.BI \-keep\-shadowed\-macros
236Do not remove macro definitions with the same name as assigned toplevel variables (the default is to remove the macro definition).
237
238.TP
239.BI \-keyword\-style style
240Enables alternative keyword syntax, where style may be either
241.B prefix
242(as in Common Lisp),
243.B suffix
244(as in DSSSL) or
245.B none
246Any other value is ignored. The default is \texttt{suffix}.
247
248.TP
249.B \-lambda\-lift
250Enable the optimization known as lambda-lifting.
251
252.TP
253.B \-local
254Assume toplevel variables defined in the current compilation unit are
255not externally modified.
256
257.TP
258.B \-no\-trace
259Disable generation of tracing information. If a compiled executable should halt due to a runtime error,
260then a file containing a stack-trace will be written to the current directory under the name
261.I STACKTRACE
262\. Each line in the created file gives the name and the line-number (if available) of a procedure call.
263With this option given, the generated code is slightly faster.
264
265.TP
266.B \-no\-warnings
267Disable generation of compiler warnings.
268
269.TP
270.BI \-nursery \ number
271.TP
272.BI \-stack\-size \ number
273Sets the size of the first heap-generation of the generated executable to
274.I number
275bytes. The parameter may
276be followed by a
277.B M
278or
279.B K
280suffix. The default stack-size depends on the target platform.
281
282.TP
283.BI \-optimize\-leaf\-routines
284Enable leaf routine optimization.
285
286.TP
287.BI \-optimize\-level \ level
288Enables certain sets of optimization options.
289.I level
290should be an integer. Each optimization level corresponds to a certain set of optimization option
291as shown in the following list:
292.P
293.br
294.B \ \ \ \ 0
295nothing
296.br
297.B \ \ \ \ 1
298-optimize-leaf-routines
299.br
300.B \ \ \ \ 2
301-optimize-leaf-routines -usual-integrations
302.br
303.B \ \ \ \ 3
304-optimize-leaf-routines -usual-integrations -unsafe
305
306.TP
307.BI \-output\-file \ filename
308Specifies the pathname of the generated C file. Default is
309.I FILENAME.c
310\.
311
312.TP
313.BI \-postlude \ expressions
314Add
315.I expressions
316after all other toplevel expressions in the compiled file.
317This option may be given multiple times. Processing of this option takes place after processing of
318.BI \-epilogue
319\.
320
321.TP
322.BI \-prelude \ expressions
323Add
324.I expressions
325before all other toplevel expressions in the compiled file.
326This option may be given multiple times. Processing of this option takes place before processing of
327.B \-prologue
328\.
329
330.TP
331.B \-profile
332.B \-accumulate\-profile
333Instruments the source code to count procedure calls and execution times. After the program terminates
334(either via an explicit
335.B exit
336or implicitly), profiling statistics are written to a file named
337.B PROFILE.<PID>
338where <PID> is the process ID of the program being profiled.
339Each line of the generated file contains a list with the procedure name,
340the number of calls and the time spent executing it. Use the
341.B chicken\-profile
342program to display the profiling information in a more user-friendly form.
343
344.TP
345.B \-profile\-name\ filename
346Specifies the name of the generated profile information file. Only useful
347in combination with the
348.B \-profile
349or
350.B \-accumulate-profile
351options.
352
353.TP
354.BI \-prologue \ filename
355Includes the file named
356.I filename
357at the start of the compiled source file.
358The include-path is not searched. This option may be given multiple times.
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.