~ chicken-core (chicken-5) /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 r5rs-syntax
103Disables the CHICKEN extensions to R5RS 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 O0 , Fl O1 , Fl O2 , Fl O3 , Fl O4 , Fl O5 , Fl optimize-level Ar NUMBER
156Enable certain sets of optimization options.
157.It Fl optimize-leaf-routines
158Enable leaf routine optimization.
159.It Fl no-usual-integrations
160Standard procedures may be redefined.
161.It Fl u , Fl unsafe
162Disable safety checks.
163.It Fl local
164Assume globals are only modified in current file.
165.It Fl b , Fl block
166Enable block-compilation.
167.It Fl disable-interrupts
168Disable interrupts in compiled code.
169.It Fl f , Fl fixnum-arithmetic
170Assume all numbers are fixnums.
171.It Fl disable-stack-overflow-checks
172Disables detection of stack-overflows.
173.It Fl inline
174Enable inlining.
175.It Fl inline-limit Ar LIMIT
176Set inlining threshold.
177.It Fl inline-global
178Enable cross-module inlining.
179.It Fl specialize
180Perform type-based specialization of primitive calls.
181.It Fl oi Ar FILENAME , Fl emit-inline-file Ar FILENAME
182Generate file with globally inlinable procedures
183.Po implies Fl inline Fl local Pc .
184.It Fl consult-inline-file Ar FILENAME
185Explicitly load inline file.
186.It Fl ot Ar FILENAME , Fl emit-types-file Ar FILENAME
187Write type-declaration information into file.
188.It Fl no-argc-checks
189Disable argument count checks.
190.It Fl no-bound-checks
191Disable bound variable checks.
192.It Fl no-procedure-checks
193Disable procedure call checks.
194.It Fl no-procedure-checks-for-usual-bindings
195Disable procedure call checks only for usual bindings.
196.It Fl no-procedure-checks-for-toplevel-bindings
197Disable procedure call checks for toplevel bindings.
198.It Fl strict-types
199Assume variable do not change their type.
200.It Fl clustering
201Combine groups of local procedures into dispatch loop.
202.It Fl lfa2
203Perform additional lightweight flow-analysis pass.
204.It Fl unroll-limit Ar LIMIT
205Specifies inlining limit for self-recursive calls.
206.El
207.Pp
208Configuration options:
209.Bl -tag -width Ds
210.It Fl unit Ar NAME
211Compile file as a library unit.
212.It Fl uses Ar NAME
213Declare library unit as used.
214.It Fl heap-size Ar NUMBER
215Specifies heap-size of compiled executable.
216.It Fl nursery Ar NUMBER Fl stack-size Ar NUMBER
217Specifies nursery size of compiled executable.
218.It Fl X Ar FILENAME , Fl extend Ar FILENAME
219Load file before compilation commences.
220.It Fl prelude Ar EXPRESSION
221Add expression to beginning of source file.
222.It Fl postlude Ar EXPRESSION
223Add expression to end of source file.
224.It Fl prologue Ar FILENAME
225Include file before main source file.
226.It Fl epilogue Ar FILENAME
227Include file after main source file.
228.It Fl e , Fl embedded
229Compile as embedded
230.Po don't generate
231.Sq Fn main
232.Pc .
233.It Fl gui
234Compile as GUI application.
235.It Fl link Ar NAME
236Link extension with compiled executable
237.Po implies Sq Fl uses
238.Pc .
239.It Fl R Ar NAME , Fl require-extension Ar NAME
240Require extension and import in compiled code.
241.It Fl dll , Fl library
242Compile multiple units into a dynamic library.
243.It Fl libdir Ar DIRECTORY
244Override location of runtime library directory.
245.El
246.Pp
247Options to other passes:
248.Bl -tag -width Ds
249.It Fl C Ar OPTION
250Pass option to C compiler.
251.It Fl L Ar OPTION
252Pass option to linker.
253.It Fl I Ns Ar <DIR>
254Pass
255.Dq -I Ns Ar <DIR>
256to C compiler
257.Po add include path Pc .
258.It Fl L Ns Ar <DIR>
259Pass
260.Dq -L Ns Ar <DIR>
261to linker
262.Po add library path Pc .
263.It Fl k
264Keep intermediate files.
265.It Fl c
266Stop after compilation to object files.
267.It Fl t
268Stop after translation to C.
269.It Fl cc Ar COMPILER
270Select a C compiler other than the default.
271.It Fl cxx Ar COMPILER
272Select a C++ compiler other than the default.
273.It Fl ld Ar COMPILER
274Select a linker other than the default.
275.It Fl static
276Link with static CHICKEN libraries and extensions.
277.It Fl F Ns Ar <DIR>
278Pass
279.Dq -F Ns Ar <DIR>
280to C compiler
281.Po add framework header path on Mac OS X Pc .
282.It Fl framework Ar NAME
283Passed to linker on Mac OS X.
284.It Fl rpath Ar PATHNAME
285Add directory to runtime library search path.
286.It Fl Wl,...
287Pass linker options.
288.It Fl strip
289Strip resulting binary.
290.El
291.Pp
292Inquiry options:
293.Bl -tag -width Ds
294.It Fl home
295Show home-directory
296.Po where support files go Pc .
297.It Fl cflags
298Show required C-compiler flags and exit.
299.It Fl ldflags
300Show required linker flags and exit.
301.It Fl libs
302Show required libraries and exit.
303.It Fl cc-name
304Show name of default C compiler used.
305.It Fl cxx-name
306Show name of default C++ compiler used.
307.It Fl ld-name
308Show name of default linker used.
309.It Fl dry-run
310Just show commands executed, don't run them
311.Po implies Sq Fl v
312.Pc .
313.El
314.Pp
315Obscure options:
316.Bl -tag -width Ds
317.It Fl debug Ar MODES
318Display debugging output for the given modes.
319.It Fl compiler Ar PATHNAME
320Use a compiler other than the default
321.Sq chicken .
322.It Fl raw
323Do not generate implicit init- and exit code.
324.It Fl emit-external-prototypes-first
325Emit prototypes for callbacks before foreign declarations.
326.It Fl regenerate-import-libraries
327Always emit import libraries, even when their contents haven't changed.
328The default behaviour is to preserve existing import libraries.
329.It Fl ignore-repository
330Do not refer to repository for extensions.
331.It Fl keep-shadowed-macros
332Do not remove shadowed macros.
333.It Fl host
334Compile for host when configured for cross-compiling.
335.It Fl private-repository
336Load extensions from executable path.
337.It Fl deployed
338Link support file to be used from a deployed executable
339.Po sets
340.Sq rpath
341accordingly, if supported on this platform.
342.Pc
343.It Fl no-elevation
344Embed manifest on Windows to supress elevation warnings for programs named
345.Sq install
346or
347.Sq setup .
348.El
349.Pp
350Options can be collapsed if unambiguous, so
351.Dq -vkfO
352is the same as
353.Dq -v -k -fixnum-arithmetic -optimize .
354.Sh ENVIRONMENT
355The following environment variables change the behaviour of
356.Nm Ns :
357.Bl -tag -width CSC_OPTIONS
358.It Ev CSC_OPTIONS
359Can hold default options that should be passed to every invocation of
360.Nm .
361.El
362.Sh EXIT STATUS
363.Ex -std
364.Sh SEE ALSO
365.Xr chicken 1
366.Pp
367More information can be found in the
368.Lk http://wiki.call-cc.org/manual/index "CHICKEN User's Manual".
369.Sh AUTHORS
370.An The CHICKEN Team
371.Sh BUGS
372Submit bug reports by e-mail to
373.Mt chicken-janitors@nongnu.org