~ chicken-core (master) /csc.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 CSC 1
 29.Os
 30.Sh NAME
 31.Nm csc
 32.Nd driver program for the CHICKEN Scheme compiler
 33.Sh SYNOPSIS
 34.Nm
 35.Op Ar OPTION ...
 36.Op Ar FILENAME ...
 37.Sh DESCRIPTION
 38.Nm
 39is a program that invokes the CHICKEN compiler and the host systems C compiler to generate
 40an executable from a Scheme source file or C files generated by CHICKEN.
 41.Pp
 42.Ar FILENAME
 43is a Scheme source file name with optional extension or a C/C++/Objective-C source,
 44object or library file name with extension.
 45.Ar OPTION
 46may be one of the following:
 47.Pp
 48General options:
 49.Bl -tag -width Ds
 50.It Fl h , Fl help
 51Display usage text and exit.
 52.It Fl v , Fl verbose
 53Show compiler notes and tool-invocations.
 54.It Fl vv
 55Display information about translation progress.
 56.It Fl vvv
 57Display information about all compilation stages.
 58.It Fl version
 59Display Scheme compiler version and exit.
 60.It Fl release
 61Display release number and exit.
 62.El
 63.Pp
 64File and pathname options:
 65.Bl -tag -width Ds
 66.It Fl o Ar FILENAME , Fl output-file Ar FILENAME
 67Specifies target executable name.
 68.It Fl I Ar PATHNAME , Fl include-path Ar PATHNAME
 69Specifies alternative path for included files.
 70.It Fl to-stdout
 71Write compiler to stdout
 72.Po implies -t Pc .
 73.It Fl s , Fl shared , Fl dynamic
 74Generate dynamically loadable shared object file.
 75.El
 76.Pp
 77Language options:
 78.Bl -tag -width Ds
 79.It Fl D Ar SYMBOL , Fl feature Ar SYMBOL
 80Register feature identifier.
 81.It Fl no-feature Ar SYMBOL
 82Disable builtin feature identifier.
 83.It Fl c++
 84Compile via a C++ source file
 85.Pq .cpp .
 86.It Fl objc
 87Compile via Objective-C source file
 88.Pq \&.m .
 89.El
 90.Pp
 91Syntax related options:
 92.Bl -tag -width Ds
 93.It Fl i , Fl case-insensitive
 94Don't preserve case of read symbols.
 95.It Fl K , Fl keyword-style Ar STYLE
 96Enable alternative keyword-syntax
 97.Po prefix, suffix or none Pc .
 98.It Fl no-parentheses-synonyms
 99Disables list delimiter synonyms.
100.It Fl no-symbol-escape
101Disables support for escaped symbols.
102.It Fl r7rs-syntax
103Disables the CHICKEN extensions to R7RS syntax.
104.It Fl compile-syntax
105Macros are made available at run-time.
106.It Fl j Ar MODULE , Fl emit-import-library Ar MODULE
107Write compile-time module information into separate file.
108.It Fl J , Fl emit-all-import-libraries
109Emit import-libraries for all defined modules.
110.It Fl no-compiler-syntax
111Disable expansion of compiler-macros.
112.It Fl m Ar NAME , Fl module Ar NAME
113Wrap compiled code in module of the given name.
114.It Fl M , Fl module-registration
115Always generate module registration code, even when import libraries are emitted.
116.It Fl N , Fl no-module-registration
117Do not generate module registration code. Overrides
118.Fl module-registration .
119.El
120.Pp
121Translation options:
122.Bl -tag -width Ds
123.It Fl x , Fl explicit-use
124Do not use units
125.Sq library
126and
127.Sq eval
128by default.
129.It Fl P , Fl check-syntax
130Stop compilation after macro-expansion.
131.It Fl A , Fl analyze-only
132Stop compilation after first analysis pass.
133.El
134.Pp
135Debugging options:
136.Bl -tag -width Ds
137.It Fl w , Fl no-warnings
138Disable warnings.
139.It Fl d0 , Fl d1 , Fl d2 , Fl d3 , Fl debug-level Ar NUMBER
140Set level of available debugging information.
141.It Fl no-trace
142Disable rudimentary debugging information.
143.It Fl profile
144Executable emits profiling information.
145.It Fl accumulate-profile
146Executable emits profiling information in append mode.
147.It Fl profile-name Ar FILENAME
148Name of the generated profile information file.
149.It Fl types Ar FILENAME
150Load additional type database.
151.El
152.Pp
153Optimization options:
154.Bl -tag -width Ds
155.It Fl O , Fl optimize-level Ar NUMBER
156Enable certain sets of optimization options.
157.Bd -filled -offset indent
158.It Fl O0
159No optimization
160.Po equivalent to Fl no-usual-integrations Fl no-compiler-syntax Pc .
161.It Fl O1
162Minimal optimization
163.Po equivalent to Fl optimize-leaf-routines Fl merge-reusable-closures Pc .
164.It Fl O2 No (Default)
165Enable optimizations that do not break standard compliance
166.Po equivalent to Fl optimize-leaf-routines Fl inline Fl lfa2 Fl merge-reusable-closures Fl merge-shareable-closures Pc .
167.It Fl O3
168Maximal optimization, while still "safe"
169.Po equivalent to Fl optimize-leaf-routines Fl local Fl inline Fl lfa2 Fl inline-global Fl specialize Fl merge-reusable-closures Fl merge-shareable-closures Pc .
170.It Fl O4
171Maximal optimization, "unsafe"
172.Po equivalent to Fl optimize-leaf-routines Fl local Fl inline Fl lfa2 Fl inline-global Fl specialize Fl unsafe Fl merge-reusable-closures Fl merge-shareable-closures Pc .
173.It Fl O5
174All possible optimizations, "unsafe"
175.Po equivalent to Fl optimize-leaf-routines Fl block Fl inline Fl lfa2 Fl inline-global Fl specialize Fl unsafe Fl disable-interrupts Fl no-trace Fl no-lambda-info Fl merge-reusable-closures Fl merge-shareable-closures Pc .
176.Ed
177.It Fl optimize-leaf-routines
178Enable leaf routine optimization.
179.It Fl no-usual-integrations
180Standard procedures may be redefined.
181.It Fl u , Fl unsafe
182Disable safety checks.
183.It Fl local
184Assume globals are only modified in current file.
185.It Fl b , Fl block
186Enable block-compilation.
187.It Fl disable-interrupts
188Disable interrupts in compiled code.
189.It Fl f , Fl fixnum-arithmetic
190Assume all numbers are fixnums.
191.It Fl disable-stack-overflow-checks
192Disables detection of stack-overflows.
193.It Fl inline
194Enable inlining.
195.It Fl inline-limit Ar LIMIT
196Set inlining threshold.
197.It Fl inline-global
198Enable cross-module inlining.
199.It Fl specialize
200Perform type-based specialization of primitive calls.
201.It Fl oi Ar FILENAME , Fl emit-inline-file Ar FILENAME
202Generate file with globally inlinable procedures
203.Po implies Fl inline Fl local Pc .
204.It Fl consult-inline-file Ar FILENAME
205Explicitly load inline file.
206.It Fl ot Ar FILENAME , Fl emit-types-file Ar FILENAME
207Write type-declaration information into file.
208.It Fl no-argc-checks
209Disable argument count checks.
210.It Fl no-bound-checks
211Disable bound variable checks.
212.It Fl no-procedure-checks
213Disable procedure call checks.
214.It Fl no-procedure-checks-for-usual-bindings
215Disable procedure call checks only for usual bindings.
216.It Fl no-procedure-checks-for-toplevel-bindings
217Disable procedure call checks for toplevel bindings.
218.It Fl strict-types
219Assume variable do not change their type.
220.It Fl lfa2
221Perform additional lightweight flow-analysis pass.
222.It Fl unroll-limit Ar LIMIT
223Specifies inlining limit for self-recursive calls.
224.It Fl merge-reusable-closures
225Enables closure reuse.
226.It Fl merge-shareable-closures
227Enables closure sharing.
228.El
229.Pp
230Configuration options:
231.Bl -tag -width Ds
232.It Fl unit Ar NAME
233Compile file as a library unit.
234.It Fl uses Ar NAME
235Declare library unit as used.
236.It Fl heap-size Ar NUMBER
237Specifies heap-size of compiled executable.
238.It Fl nursery Ar NUMBER Fl stack-size Ar NUMBER
239Specifies nursery size of compiled executable.
240.It Fl X Ar FILENAME , Fl extend Ar FILENAME
241Load file before compilation commences.
242.It Fl prelude Ar EXPRESSION
243Add expression to beginning of source file.
244.It Fl postlude Ar EXPRESSION
245Add expression to end of source file.
246.It Fl prologue Ar FILENAME
247Include file before main source file.
248.It Fl epilogue Ar FILENAME
249Include file after main source file.
250.It Fl e , Fl embedded
251Compile as embedded
252.Po don't generate
253.Sq Fn main
254.Pc .
255.It Fl gui
256Compile as GUI application.
257.It Fl link Ar NAME
258Link extension with compiled executable
259.Po implies Sq Fl uses
260.Pc .
261.It Fl R Ar NAME , Fl require-extension Ar NAME
262Require extension and import in compiled code.
263.It Fl dll , Fl library
264Compile multiple units into a dynamic library.
265.It Fl libdir Ar DIRECTORY
266Override location of runtime library directory.
267.El
268.Pp
269Options to other passes:
270.Bl -tag -width Ds
271.It Fl C Ar OPTION
272Pass option to C compiler.
273.It Fl L Ar OPTION
274Pass option to linker.
275.It Fl I Ns Ar <DIR>
276Pass
277.Dq -I Ns Ar <DIR>
278to C compiler
279.Po add include path Pc .
280.It Fl L Ns Ar <DIR>
281Pass
282.Dq -L Ns Ar <DIR>
283to linker
284.Po add library path Pc .
285.It Fl k
286Keep intermediate files.
287.It Fl c
288Stop after compilation to object files.
289.It Fl t
290Stop after translation to C.
291.It Fl cc Ar COMPILER
292Select a C compiler other than the default.
293.It Fl cxx Ar COMPILER
294Select a C++ compiler other than the default.
295.It Fl ld Ar COMPILER
296Select a linker other than the default.
297.It Fl static
298Link with static CHICKEN libraries and extensions.
299.It Fl F Ns Ar <DIR>
300Pass
301.Dq -F Ns Ar <DIR>
302to C compiler
303.Po add framework header path on Mac OS X Pc .
304.It Fl framework Ar NAME
305Passed to linker on Mac OS X.
306.It Fl rpath Ar PATHNAME
307Add directory to runtime library search path.
308.It Fl Wl,...
309Pass linker options.
310.It Fl strip
311Strip resulting binary.
312.El
313.Pp
314Inquiry options:
315.Bl -tag -width Ds
316.It Fl home
317Show home-directory
318.Po where support files go Pc .
319.It Fl cflags
320Show required C-compiler flags and exit.
321.It Fl ldflags
322Show required linker flags and exit.
323.It Fl libs
324Show required libraries and exit.
325.It Fl cc-name
326Show name of default C compiler used.
327.It Fl cxx-name
328Show name of default C++ compiler used.
329.It Fl ld-name
330Show name of default linker used.
331.It Fl dry-run
332Just show commands executed, don't run them
333.Po implies Sq Fl v
334.Pc .
335.El
336.Pp
337Obscure options:
338.Bl -tag -width Ds
339.It Fl debug Ar MODES
340Display debugging output for the given modes.
341.It Fl compiler Ar PATHNAME
342Use a compiler other than the default
343.Sq chicken .
344.It Fl raw
345Do not generate implicit init- and exit code.
346.It Fl emit-external-prototypes-first
347Emit prototypes for callbacks before foreign declarations.
348.It Fl regenerate-import-libraries
349Always emit import libraries, even when their contents haven't changed.
350The default behaviour is to preserve existing import libraries.
351.It Fl ignore-repository
352Do not refer to repository for extensions.
353.It Fl keep-shadowed-macros
354Do not remove shadowed macros.
355.It Fl host
356Compile for host when configured for cross-compiling.
357.It Fl private-repository
358Load extensions from executable path.
359.It Fl deployed
360Link support file to be used from a deployed executable
361.Po sets
362.Sq rpath
363accordingly, if supported on this platform.
364.Pc
365.It Fl no-elevation
366Embed manifest on Windows to supress elevation warnings for programs named
367.Sq install
368or
369.Sq setup .
370.El
371.Pp
372Options can be collapsed if unambiguous, so
373.Dq -vkfO
374is the same as
375.Dq -v -k -fixnum-arithmetic -optimize .
376.Sh ENVIRONMENT
377The following environment variables change the behaviour of
378.Nm Ns :
379.Bl -tag -width CSC_OPTIONS
380.It Ev CSC_OPTIONS
381Can hold default options that should be passed to every invocation of
382.Nm .
383.El
384.Sh EXIT STATUS
385.Ex -std
386.Sh SEE ALSO
387.Xr chicken 1
388.Pp
389More information can be found in the
390.Lk http://wiki.call-cc.org/manual/index "CHICKEN User's Manual".
391.Sh AUTHORS
392.An The CHICKEN Team
393.Sh BUGS
394Submit bug reports by e-mail to
395.Mt chicken-janitors@nongnu.org