~ chicken-core (master) /chicken.mdoc

  1.\"  Copyright (c) 2007-2022, The CHICKEN Team
  2.\"  All rights reserved.
  3.\"
  4.\"  Redistribution and use in source and binary forms, with or without
  5.\"  modification, are permitted provided that the following conditions
  6.\"  are met:
  7.\"  1. Redistributions of source code must retain the above copyright
  8.\"     notice, this list of conditions and the following disclaimer.
  9.\"  2. Redistributions in binary form must reproduce the above copyright
 10.\"     notice, this list of conditions and the following disclaimer in the
 11.\"     documentation and/or other materials provided with the distribution.
 12.\"  3. The name of the authors may not be used to endorse or promote products
 13.\"     derived from this software without specific prior written permission.
 14.\"
 15.\"  THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
 16.\"  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 17.\"  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 18.\"  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 19.\"  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 20.\"  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 21.\"  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 22.\"  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 23.\"  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 24.\"  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 25.\"
 26.\"
 27.Dd Apr 26, 2017
 28.Dt CHICKEN 1
 29.Os
 30.Sh NAME
 31.Nm chicken
 32.Nd A Scheme-to-C translator
 33.Sh SYNOPSIS
 34.Nm
 35.Op Ar OPTION ...
 36.Op Ar FILENAME ...
 37.Sh DESCRIPTION
 38.Nm
 39is a compiler and interpreter for the programming language Scheme
 40supporting most of the features as described in the
 41Revised^5 Report on the Algorithmic Language Scheme.
 42The
 43.Nm
 44program is the basic Scheme-to-C translator used in this system.
 45For a more convenient interface, see
 46.Xr csc 1 .
 47.Pp
 48.Ar FILENAME
 49should be a complete source file name with extension, or
 50.Dq -
 51for standard input.
 52.Ar OPTION
 53may be one of the following:
 54.Pp
 55General options:
 56.Bl -tag -width Ds
 57.It Fl help
 58Display usage and exit.
 59.It Fl version
 60Display compiler version and exit.
 61.It Fl release
 62Print release number and exit.
 63.It Fl verbose
 64Display information on compilation progress.
 65.El
 66.Pp
 67File and pathname options:
 68.Bl -tag -width Ds
 69.It Fl output-file Ar FILENAME
 70Specifies output-filename, default is
 71.Dq out.c .
 72.It Fl include-path Ar PATHNAME
 73Specifies alternative path for included files.
 74.It Fl to-stdout
 75Write compiled file to stdout instead of file.
 76.El
 77.Pp
 78Language options:
 79.Bl -tag -width Ds
 80.It Fl feature Ar SYMBOL
 81Register feature identifier.
 82.It Fl no-feature Ar SYMBOL
 83Disable built-in feature identifier.
 84.El
 85.Pp
 86Syntax related options:
 87.Bl -tag -width Ds
 88.It Fl case-insensitive
 89Don't preserve case of read symbols.
 90.It Fl keyword-style Ar STYLE
 91Allow alternative keyword syntax
 92.Po prefix, suffix or none Pc .
 93.It Fl no-parentheses-synonyms
 94Disables list delimiter synonyms.
 95.It Fl r7rs-syntax
 96Disables the CHICKEN extensions to R7RS syntax.
 97.It Fl compile-syntax
 98Macros are made available at run-time.
 99.It Fl emit-import-library Ar MODULE
100Write compile-time module information into separate file.
101.It Fl emit-all-import-libraries
102Emit import-libraries for all defined modules.
103.It Fl no-compiler-syntax
104Disable expansion of compiler-macros.
105.It Fl module Ar NAME
106Wrap compiled code in module of the given name.
107.It Fl module-registration
108Always generate module registration code, even when import libraries are emitted.
109.It Fl no-module-registration
110Do not generate module registration code. Overrides
111.Fl module-registration .
112.El
113.Pp
114Translation options:
115.Bl -tag -width Ds
116.It Fl explicit-use
117Do not use units
118.Sq library
119and
120.Sq eval
121by default.
122.It Fl static
123Link extensions statically.
124.It Fl check-syntax
125Stop compilation after macro-expansion.
126.It Fl analyze-only
127Stop compilation after first analysis pass.
128.El
129.Pp
130Debugging options:
131.Bl -tag -width Ds
132.It Fl no-warnings
133Disable warnings.
134.It Fl debug-level Ar NUMBER
135Set level of available debugging information.
136.It Fl no-trace
137Disable tracing information.
138.It Fl profile
139Executable emits profiling information.
140.It Fl profile-name Ar FILENAME
141Name of the generated profile information file.
142.It Fl accumulate-profile
143Executable emits profiling information in append mode.
144.It Fl no-lambda-info
145Omit additional procedure-information.
146.It Fl types Ar FILENAME
147Load additional type database.
148.It Fl emit-types-file Ar FILENAME
149Write type-declaration information into file.
150.El
151.Pp
152Optimization options:
153.Bl -tag -width Ds
154.It Fl optimize-level Ar NUMBER
155Enable certain sets of optimization options.
156.It Fl optimize-leaf-routines
157Enable leaf routine optimization.
158.It Fl no-usual-integrations
159Standard procedures may be redefined.
160.It Fl unsafe
161Disable all safety checks.
162.It Fl local
163Assume globals are only modified in current file.
164.It Fl block
165Enable block-compilation.
166.It Fl disable-interrupts
167Disable interrupts in compiled code.
168.It Fl fixnum-arithmetic
169Assume all numbers are fixnums.
170.It Fl disable-stack-overflow-checks
171Disables detection of stack-overflows.
172.It Fl inline
173Enable inlining.
174.It Fl inline-limit Ar LIMIT
175Set inlining threshold.
176.It Fl inline-global
177Enable cross-module inlining.
178.It Fl specialize
179Perform type-based specialization of primitive calls.
180.It Fl emit-inline-file Ar FILENAME
181Generate file with globally inlinable procedures
182.Po implies Fl inline Fl local Pc .
183.It Fl consult-inline-file Ar FILENAME
184Explicitly load inline file.
185.It Fl no-argc-checks
186Disable argument count checks.
187.It Fl no-bound-checks
188Disable bound variable checks.
189.It Fl no-procedure-checks
190Disable procedure call checks.
191.It Fl no-procedure-checks-for-usual-bindings
192Disable procedure call checks only for usual bindings.
193.It Fl no-procedure-checks-for-toplevel-bindings
194Disable procedure call checks for toplevel bindings.
195.It Fl strict-types
196Assume variable do not change their type.
197.It Fl lfa2
198Perform additional lightweight flow-analysis pass.
199.It Fl unroll-limit Ar LIMIT
200Specifies inlining limit for self-recursive calls.
201.El
202.Pp
203Configuration options:
204.Bl -tag -width Ds
205.It Fl unit Ar NAME
206Compile file as a library unit.
207.It Fl uses Ar NAME
208Declare library unit as used.
209.It Fl heap-size Ar NUMBER
210Specifies heap-size of compiled executable.
211.It Fl nursery Ar NUMBER Fl stack-size Ar NUMBER
212Specifies nursery size of compiled executable.
213.It Fl extend Ar FILENAME
214Load file before compilation commences.
215.It Fl prelude Ar EXPRESSION
216Add expression to front of source file.
217.It Fl postlude Ar EXPRESSION
218Add expression to end of source file.
219.It Fl prologue Ar FILENAME
220Include file before main source file.
221.It Fl epilogue Ar FILENAME
222Include file after main source file.
223.It Fl dynamic
224Compile as dynamically loadable code.
225.It Fl require-extension Ar NAME
226Require and import extension
227.Ar NAME .
228.It Fl emit-link-file Ar FILENAME
229Write a list of statically linked extensions to
230.Ar FILENAME ,
231used for identifying the static objects that need to be linked to an
232executable.
233.El
234.Pp
235Obscure options:
236.Bl -tag -width Ds
237.It Fl debug Ar MODES
238Display debugging output for the given modes.
239.It Fl raw
240Do not generate implicit init- and exit code.
241.It Fl emit-external-prototypes-first
242Emit prototypes for callbacks before foreign declarations.
243.It Fl regenerate-import-libraries
244Always emit import libraries, even when their contents haven't changed.
245The default behaviour is to preserve existing import libraries.
246.It Fl ignore-repository
247Do not refer to repository for extensions.
248.It Fl setup-mode
249Prefer the current directory when locating extensions.
250.El
251.Sh ENVIRONMENT
252The following environment variables change the behaviour of
253.Nm Ns :
254.Bl -tag -width CHICKEN_INCLUDE_PATH
255.It Ev CHICKEN_INCLUDE_PATH
256Contains one or more pathnames where the compiler should additionally look for
257include-files, separated by
258.Sq \&;
259characters.
260.It Ev CHICKEN_OPTIONS
261Holds a string of default compiler options that should apply to every invocation of
262.Nm .
263.El
264.Sh EXIT STATUS
265.Ex -std
266.Sh SEE ALSO
267.Xr chicken 1 ,
268.Xr chicken-install 1 ,
269.Xr chicken-uninstall 1
270.Pp
271More information can be found in the
272.Lk http://wiki.call-cc.org/manual/index "CHICKEN User's Manual".
273.Sh AUTHORS
274.An The CHICKEN Team
275.Sh BUGS
276Submit bug reports by e-mail to
277.Mt chicken-janitors@nongnu.org