~ 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 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 lfa2
201Perform additional lightweight flow-analysis pass.
202.It Fl unroll-limit Ar LIMIT
203Specifies inlining limit for self-recursive calls.
204.El
205.Pp
206Configuration options:
207.Bl -tag -width Ds
208.It Fl unit Ar NAME
209Compile file as a library unit.
210.It Fl uses Ar NAME
211Declare library unit as used.
212.It Fl heap-size Ar NUMBER
213Specifies heap-size of compiled executable.
214.It Fl nursery Ar NUMBER Fl stack-size Ar NUMBER
215Specifies nursery size of compiled executable.
216.It Fl X Ar FILENAME , Fl extend Ar FILENAME
217Load file before compilation commences.
218.It Fl prelude Ar EXPRESSION
219Add expression to beginning of source file.
220.It Fl postlude Ar EXPRESSION
221Add expression to end of source file.
222.It Fl prologue Ar FILENAME
223Include file before main source file.
224.It Fl epilogue Ar FILENAME
225Include file after main source file.
226.It Fl e , Fl embedded
227Compile as embedded
228.Po don't generate
229.Sq Fn main
230.Pc .
231.It Fl gui
232Compile as GUI application.
233.It Fl link Ar NAME
234Link extension with compiled executable
235.Po implies Sq Fl uses
236.Pc .
237.It Fl R Ar NAME , Fl require-extension Ar NAME
238Require extension and import in compiled code.
239.It Fl dll , Fl library
240Compile multiple units into a dynamic library.
241.It Fl libdir Ar DIRECTORY
242Override location of runtime library directory.
243.El
244.Pp
245Options to other passes:
246.Bl -tag -width Ds
247.It Fl C Ar OPTION
248Pass option to C compiler.
249.It Fl L Ar OPTION
250Pass option to linker.
251.It Fl I Ns Ar <DIR>
252Pass
253.Dq -I Ns Ar <DIR>
254to C compiler
255.Po add include path Pc .
256.It Fl L Ns Ar <DIR>
257Pass
258.Dq -L Ns Ar <DIR>
259to linker
260.Po add library path Pc .
261.It Fl k
262Keep intermediate files.
263.It Fl c
264Stop after compilation to object files.
265.It Fl t
266Stop after translation to C.
267.It Fl cc Ar COMPILER
268Select a C compiler other than the default.
269.It Fl cxx Ar COMPILER
270Select a C++ compiler other than the default.
271.It Fl ld Ar COMPILER
272Select a linker other than the default.
273.It Fl static
274Link with static CHICKEN libraries and extensions.
275.It Fl F Ns Ar <DIR>
276Pass
277.Dq -F Ns Ar <DIR>
278to C compiler
279.Po add framework header path on Mac OS X Pc .
280.It Fl framework Ar NAME
281Passed to linker on Mac OS X.
282.It Fl rpath Ar PATHNAME
283Add directory to runtime library search path.
284.It Fl Wl,...
285Pass linker options.
286.It Fl strip
287Strip resulting binary.
288.El
289.Pp
290Inquiry options:
291.Bl -tag -width Ds
292.It Fl home
293Show home-directory
294.Po where support files go Pc .
295.It Fl cflags
296Show required C-compiler flags and exit.
297.It Fl ldflags
298Show required linker flags and exit.
299.It Fl libs
300Show required libraries and exit.
301.It Fl cc-name
302Show name of default C compiler used.
303.It Fl cxx-name
304Show name of default C++ compiler used.
305.It Fl ld-name
306Show name of default linker used.
307.It Fl dry-run
308Just show commands executed, don't run them
309.Po implies Sq Fl v
310.Pc .
311.El
312.Pp
313Obscure options:
314.Bl -tag -width Ds
315.It Fl debug Ar MODES
316Display debugging output for the given modes.
317.It Fl compiler Ar PATHNAME
318Use a compiler other than the default
319.Sq chicken .
320.It Fl raw
321Do not generate implicit init- and exit code.
322.It Fl emit-external-prototypes-first
323Emit prototypes for callbacks before foreign declarations.
324.It Fl regenerate-import-libraries
325Always emit import libraries, even when their contents haven't changed.
326The default behaviour is to preserve existing import libraries.
327.It Fl ignore-repository
328Do not refer to repository for extensions.
329.It Fl keep-shadowed-macros
330Do not remove shadowed macros.
331.It Fl host
332Compile for host when configured for cross-compiling.
333.It Fl private-repository
334Load extensions from executable path.
335.It Fl deployed
336Link support file to be used from a deployed executable
337.Po sets
338.Sq rpath
339accordingly, if supported on this platform.
340.Pc
341.It Fl no-elevation
342Embed manifest on Windows to supress elevation warnings for programs named
343.Sq install
344or
345.Sq setup .
346.El
347.Pp
348Options can be collapsed if unambiguous, so
349.Dq -vkfO
350is the same as
351.Dq -v -k -fixnum-arithmetic -optimize .
352.Sh ENVIRONMENT
353The following environment variables change the behaviour of
354.Nm Ns :
355.Bl -tag -width CSC_OPTIONS
356.It Ev CSC_OPTIONS
357Can hold default options that should be passed to every invocation of
358.Nm .
359.El
360.Sh EXIT STATUS
361.Ex -std
362.Sh SEE ALSO
363.Xr chicken 1
364.Pp
365More information can be found in the
366.Lk http://wiki.call-cc.org/manual/index "CHICKEN User's Manual".
367.Sh AUTHORS
368.An The CHICKEN Team
369.Sh BUGS
370Submit bug reports by e-mail to
371.Mt chicken-janitors@nongnu.org