csc.mdoc

.\"  Copyright (c) 2007-2021, The CHICKEN Team
.\"  All rights reserved.
.\"
.\"  Redistribution and use in source and binary forms, with or without
.\"  modification, are permitted provided that the following conditions
.\"  are met:
.\"  1. Redistributions of source code must retain the above copyright
.\"     notice, this list of conditions and the following disclaimer.
.\"  2. Redistributions in binary form must reproduce the above copyright
.\"     notice, this list of conditions and the following disclaimer in the
.\"     documentation and/or other materials provided with the distribution.
.\"  3. The name of the authors may not be used to endorse or promote products
.\"     derived from this software without specific prior written permission.
.\"
.\"  THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
.\"  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\"  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\"  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\"  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\"  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\"  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\"  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\"  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\"  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\"
.Dd Apr 26, 2017
.Dt CSC 1
.Os
.Sh NAME
.Nm csc
.Nd driver program for the CHICKEN Scheme compiler
.Sh SYNOPSIS
.Nm
.Op Ar OPTION ...
.Op Ar FILENAME ...
.Sh DESCRIPTION
.Nm
is a program that invokes the CHICKEN compiler and the host systems C compiler to generate
an executable from a Scheme source file or C files generated by CHICKEN.
.Pp
.Ar FILENAME
is a Scheme source file name with optional extension or a C/C++/Objective-C source,
object or library file name with extension.
.Ar OPTION
may be one of the following:
.Pp
General options:
.Bl -tag -width Ds
.It Fl h , Fl help
Display usage text and exit.
.It Fl v , Fl verbose
Show compiler notes and tool-invocations.
.It Fl vv
Display information about translation progress.
.It Fl vvv
Display information about all compilation stages.
.It Fl version
Display Scheme compiler version and exit.
.It Fl release
Display release number and exit.
.El
.Pp
File and pathname options:
.Bl -tag -width Ds
.It Fl o Ar FILENAME , Fl output-file Ar FILENAME
Specifies target executable name.
.It Fl I Ar PATHNAME , Fl include-path Ar PATHNAME
Specifies alternative path for included files.
.It Fl to-stdout
Write compiler to stdout
.Po implies -t Pc .
.It Fl s , Fl shared , Fl dynamic
Generate dynamically loadable shared object file.
.El
.Pp
Language options:
.Bl -tag -width Ds
.It Fl D Ar SYMBOL , Fl feature Ar SYMBOL
Register feature identifier.
.It Fl no-feature Ar SYMBOL
Disable builtin feature identifier.
.It Fl c++
Compile via a C++ source file
.Pq .cpp .
.It Fl objc
Compile via Objective-C source file
.Pq \&.m .
.El
.Pp
Syntax related options:
.Bl -tag -width Ds
.It Fl i , Fl case-insensitive
Don't preserve case of read symbols.
.It Fl K , Fl keyword-style Ar STYLE
Enable alternative keyword-syntax
.Po prefix, suffix or none Pc .
.It Fl no-parentheses-synonyms
Disables list delimiter synonyms.
.It Fl no-symbol-escape
Disables support for escaped symbols.
.It Fl r5rs-syntax
Disables the CHICKEN extensions to R5RS syntax.
.It Fl compile-syntax
Macros are made available at run-time.
.It Fl j Ar MODULE , Fl emit-import-library Ar MODULE
Write compile-time module information into separate file.
.It Fl J , Fl emit-all-import-libraries
Emit import-libraries for all defined modules.
.It Fl no-compiler-syntax
Disable expansion of compiler-macros.
.It Fl m Ar NAME , Fl module Ar NAME
Wrap compiled code in module of the given name.
.It Fl M , Fl module-registration
Always generate module registration code, even when import libraries are emitted.
.It Fl N , Fl no-module-registration
Do not generate module registration code. Overrides
.Fl module-registration .
.El
.Pp
Translation options:
.Bl -tag -width Ds
.It Fl x , Fl explicit-use
Do not use units
.Sq library
and
.Sq eval
by default.
.It Fl P , Fl check-syntax
Stop compilation after macro-expansion.
.It Fl A , Fl analyze-only
Stop compilation after first analysis pass.
.El
.Pp
Debugging options:
.Bl -tag -width Ds
.It Fl w , Fl no-warnings
Disable warnings.
.It Fl d0 , Fl d1 , Fl d2 , Fl d3 , Fl debug-level Ar NUMBER
Set level of available debugging information.
.It Fl no-trace
Disable rudimentary debugging information.
.It Fl profile
Executable emits profiling information.
.It Fl accumulate-profile
Executable emits profiling information in append mode.
.It Fl profile-name Ar FILENAME
Name of the generated profile information file.
.It Fl types Ar FILENAME
Load additional type database.
.El
.Pp
Optimization options:
.Bl -tag -width Ds
.It Fl O , Fl O0 , Fl O1 , Fl O2 , Fl O3 , Fl O4 , Fl O5 , Fl optimize-level Ar NUMBER
Enable certain sets of optimization options.
.It Fl optimize-leaf-routines
Enable leaf routine optimization.
.It Fl no-usual-integrations
Standard procedures may be redefined.
.It Fl u , Fl unsafe
Disable safety checks.
.It Fl local
Assume globals are only modified in current file.
.It Fl b , Fl block
Enable block-compilation.
.It Fl disable-interrupts
Disable interrupts in compiled code.
.It Fl f , Fl fixnum-arithmetic
Assume all numbers are fixnums.
.It Fl disable-stack-overflow-checks
Disables detection of stack-overflows.
.It Fl inline
Enable inlining.
.It Fl inline-limit Ar LIMIT
Set inlining threshold.
.It Fl inline-global
Enable cross-module inlining.
.It Fl specialize
Perform type-based specialization of primitive calls.
.It Fl oi Ar FILENAME , Fl emit-inline-file Ar FILENAME
Generate file with globally inlinable procedures
.Po implies Fl inline Fl local Pc .
.It Fl consult-inline-file Ar FILENAME
Explicitly load inline file.
.It Fl ot Ar FILENAME , Fl emit-types-file Ar FILENAME
Write type-declaration information into file.
.It Fl no-argc-checks
Disable argument count checks.
.It Fl no-bound-checks
Disable bound variable checks.
.It Fl no-procedure-checks
Disable procedure call checks.
.It Fl no-procedure-checks-for-usual-bindings
Disable procedure call checks only for usual bindings.
.It Fl no-procedure-checks-for-toplevel-bindings
Disable procedure call checks for toplevel bindings.
.It Fl strict-types
Assume variable do not change their type.
.It Fl clustering
Combine groups of local procedures into dispatch loop.
.It Fl lfa2
Perform additional lightweight flow-analysis pass.
.It Fl unroll-limit Ar LIMIT
Specifies inlining limit for self-recursive calls.
.El
.Pp
Configuration options:
.Bl -tag -width Ds
.It Fl unit Ar NAME
Compile file as a library unit.
.It Fl uses Ar NAME
Declare library unit as used.
.It Fl heap-size Ar NUMBER
Specifies heap-size of compiled executable.
.It Fl nursery Ar NUMBER Fl stack-size Ar NUMBER
Specifies nursery size of compiled executable.
.It Fl X Ar FILENAME , Fl extend Ar FILENAME
Load file before compilation commences.
.It Fl prelude Ar EXPRESSION
Add expression to beginning of source file.
.It Fl postlude Ar EXPRESSION
Add expression to end of source file.
.It Fl prologue Ar FILENAME
Include file before main source file.
.It Fl epilogue Ar FILENAME
Include file after main source file.
.It Fl e , Fl embedded
Compile as embedded
.Po don't generate
.Sq Fn main
.Pc .
.It Fl gui
Compile as GUI application.
.It Fl link Ar NAME
Link extension with compiled executable
.Po implies Sq Fl uses
.Pc .
.It Fl R Ar NAME , Fl require-extension Ar NAME
Require extension and import in compiled code.
.It Fl dll , Fl library
Compile multiple units into a dynamic library.
.It Fl libdir Ar DIRECTORY
Override location of runtime library directory.
.El
.Pp
Options to other passes:
.Bl -tag -width Ds
.It Fl C Ar OPTION
Pass option to C compiler.
.It Fl L Ar OPTION
Pass option to linker.
.It Fl I Ns Ar <DIR>
Pass
.Dq -I Ns Ar <DIR>
to C compiler
.Po add include path Pc .
.It Fl L Ns Ar <DIR>
Pass
.Dq -L Ns Ar <DIR>
to linker
.Po add library path Pc .
.It Fl k
Keep intermediate files.
.It Fl c
Stop after compilation to object files.
.It Fl t
Stop after translation to C.
.It Fl cc Ar COMPILER
Select a C compiler other than the default.
.It Fl cxx Ar COMPILER
Select a C++ compiler other than the default.
.It Fl ld Ar COMPILER
Select a linker other than the default.
.It Fl static-libs
Link with static CHICKEN libraries and extensions.
.It Fl F Ns Ar <DIR>
Pass
.Dq -F Ns Ar <DIR>
to C compiler
.Po add framework header path on Mac OS X Pc .
.It Fl framework Ar NAME
Passed to linker on Mac OS X.
.It Fl rpath Ar PATHNAME
Add directory to runtime library search path.
.It Fl Wl,...
Pass linker options.
.It Fl strip
Strip resulting binary.
.El
.Pp
Inquiry options:
.Bl -tag -width Ds
.It Fl home
Show home-directory
.Po where support files go Pc .
.It Fl cflags
Show required C-compiler flags and exit.
.It Fl ldflags
Show required linker flags and exit.
.It Fl libs
Show required libraries and exit.
.It Fl cc-name
Show name of default C compiler used.
.It Fl cxx-name
Show name of default C++ compiler used.
.It Fl ld-name
Show name of default linker used.
.It Fl dry-run
Just show commands executed, don't run them
.Po implies Sq Fl v
.Pc .
.El
.Pp
Obscure options:
.Bl -tag -width Ds
.It Fl debug Ar MODES
Display debugging output for the given modes.
.It Fl compiler Ar PATHNAME
Use a compiler other than the default
.Sq chicken .
.It Fl raw
Do not generate implicit init- and exit code.
.It Fl emit-external-prototypes-first
Emit prototypes for callbacks before foreign declarations.
.It Fl regenerate-import-libraries
Always emit import libraries, even when their contents haven't changed.
The default behaviour is to preserve existing import libraries.
.It Fl ignore-repository
Do not refer to repository for extensions.
.It Fl keep-shadowed-macros
Do not remove shadowed macros.
.It Fl host
Compile for host when configured for cross-compiling.
.It Fl private-repository
Load extensions from executable path.
.It Fl deployed
Link support file to be used from a deployed executable
.Po sets
.Sq rpath
accordingly, if supported on this platform.
.Pc
.It Fl no-elevation
Embed manifest on Windows to supress elevation warnings for programs named
.Sq install
or
.Sq setup .
.El
.Pp
Options can be collapsed if unambiguous, so
.Dq -vkfO
is the same as
.Dq -v -k -fixnum-arithmetic -optimize .
.Sh ENVIRONMENT
The following environment variables change the behaviour of
.Nm Ns :
.Bl -tag -width CSC_OPTIONS
.It Ev CSC_OPTIONS
Can hold default options that should be passed to every invocation of
.Nm .
.El
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr chicken 1
.Pp
More information can be found in the
.Lk http://wiki.call-cc.org/manual/index "CHICKEN User's Manual".
.Sh AUTHORS
.An The CHICKEN Team
.Sh BUGS
Submit bug reports by e-mail to
.Mt chicken-janitors@nongnu.org