2.2 Command line arguments

The synopsis of the executable program vicare is as follows:

vicare [OPTIONS] [PROGRAM]              [-- [PROGOPTS]]
vicare [OPTIONS] --r6rs-script     FILE [-- [PROGOPTS]]
vicare [OPTIONS] --binary-program  FILE [-- [PROGOPTS]]
vicare [OPTIONS] --compile-program PROGFILE
vicare [OPTIONS] --compile-library LIBFILE
vicare [OPTIONS] --compile FILE
vicare [OPTIONS] --compile-dependencies PROGRAM

the OPTIONS are interpreted by vicare, PROGOPTS can be obtained using the command-line procedure in the (rnrs programs) library; when running the REPL: the first element of the returned list will be the string ‘*interactive*’, corresponding to the script name in R6RS–script mode.

The vicare executable recognises a few command line switches that influence how Vicare Scheme starts; the following are the main options, driving the execution mode. It is an error to put on the command line two or more of these options.

--r6rs-script PROGRAM

Start Vicare in R6RS–script mode. The PROGRAM file is handled as an R6RS program. Example:

$ cat test.sps
(import (rnrs))
(write (command-line))
(newline)
(flush-output-port (current-output-port))

$ vicare --r6rs-script test.sps -- hi there
("test.sps" "hi" "there")

--binary-program PROGRAM

Start Vicare in compiled–program mode. The PROGRAM file is handled as a serialised R6RS binary program: it is loaded and executed.

--compile-program PROGRAM

Load the source R6RS program PROGRAM, compile it and store a serialised version of it into an output file. PROGRAM itself is not evaluated.

If the option --output is used: its value is the pathname of the output file; otherwise the output file pathname is built from PROGRAM and the binary file is placed in the same directory of the source.

If the option --library-locator is not used: using --compile-program will automatically select the compile–time library locator.

--compile-dependencies IMPORTS-FILE

Load the R6RS program IMPORTS-FILE, compile all the libraries upon which it depends and store them in the build directory selected by --build-directory. IMPORTS-FILE itself is not evaluated.

If the option --library-locator is not used: using --compile-dependencies will automatically select the compile–time library locator.

--compile-library LIBFILE

Load the R6RS library source LIBFILE, compile it and serialise it in an output file.

If the option --output is used: its value is the pathname of the output file; otherwise the output pathname is automatically generated under the build directory selected by --build-directory.

If the option --library-locator is not used: using --compile-library will automatically select the compile–time library locator.

-c FILE

--compile FILE

Load the selected FILE and recognise it as program or library by the file extension (.sps or .sls); the behave as if the option --compile-program or --compile-library had been given.

When none of these options is given, but a standalone PROGRAM argument is present on the command line: act as if the option --r6rs-script is present with the given file name.

If no standalone PROGRAM argument is present: enter the REPL. When neither the option --rcfile nor the option --no-rcfile is used: before entering the REPL, the default run–command file ~/.vicarerc is loaded.

The rest of the command line arguments are recognised by the standard Scheme run time system.

-b path/to/boot/file.boot

--boot path/to/boot/file.boot

Use the specified boot file as the initial system boot file. The boot file is a binary file that contains all the code and data of the Scheme system. In the absence of the -b flag, the executable will use the default boot file. Running vicare with the -h option shows the location where the default boot file was installed.

--no-rcfile

Disable loading of run–command files.

--rcfile FILE

Load and evaluate FILE as an R6RS program at start up, before loading libraries and running the main program. This option can be used multiple times.

When the execution mode is to enter the REPL: using this option disables loading the default file ~/.vicarerc; only the selected FILE scripts are loaded.

-o OFILE

--output OFILE

Select the pathname of an output file. This selection has multiple purposes and it is ignored when irrelevant. OFILE is used as: output FASL file name when compiling individual library files; output FASL file name when compiling program files.

-l LIBFILE

--load-library LIBFILE

Load the source file libfile expecting it to contain one or more R6RS libraries; after executing the RC files, load the libraries in the internal collection, but do not add them to any environment. This option can be used multiple times.

--A DIRECTORY

--source-path DIRECTORY

Append DIRECTORY to the source libraries search path. This option can be used multiple times.

-I DIRECTORY

Prepend DIRECTORY to the source libraries search path. This option can be used multiple times.

-L DIRECTORY

--library-path DIRECTORY

Add DIRECTORY to the binary libraries search path. This option can be used multiple times.

--library-locator NAME

Select a Scheme library locator. NAME can be one among: ‘run-time’, ‘compile-time’, ‘source’. For details on searching libraries Library search algorithms. For details on the built–in library locators API Locating libraries.

--build-directory DIRECTORY

Select DIRECTORY as pathname under which compiled library files are temporarily stored before being installed. When used multiple times: the last one wins.

--more-file-extensions

Rather than searching only libraries with extension ‘.vicare.sls’ and ‘.sls’, search also for ‘.vicare.ss’, ‘.ss’, ‘.vicare.scm’, ‘.scm’ and the ‘main’ file. using libraries searching for more details.

--prompt STRING

Use STRING as prompt for the REPL. Defaults to ‘vicare’, to which the character ‘>’ is appended for each nested REPL level. iklib cafe for more details.

--repl-on-sigint

When this option is used an interprocess signal handler is registered at program start up to enter a debugging REPL whenever a SIGINT signal is received.

--raw-repl

Do not create a readline console input port even if the readline interface is available.

-d

-g

Turn on debugging mode. With this option: unhandled exceptions in the program will result in starting the debugger, which allows stack trace inspection.

--option option-name

Turn on or off compiler and expander options; option-name must be a string among:

strict-r6rs

no-strict-r6rs

The first option causes Vicare to strictly follow R6RS specifications, disabling extensions. The default is to enable extensions.

debug

no-debug

Turn on or off debugging mode. With this option: unhandled exceptions in the program will result in starting the debugger, which allows stack trace inspection. Using --option debug is equivalent to using the options -d and -g.

drop-assertions

no-drop-assertions

The first option causes every assert macro to be expanded into its expression, dropping the assertions. The second option expands uses of the assert syntax as full assertions; this is the default.

Specifically, when drop-assertions is used:

(assert ?expr)

is expanded into:

?expr

so that side effects in ?expr are performed and the resulting value is returned. The default is to include the full assertion.

check-compiler-pass-preconditions

no-check-compiler-pass-preconditions

The first option enables performing additional compiler passes to validate generated code. To be used when debugging Vicare’s compiler. The default is not to perform such compiler passes.

gc-integrity-checks

no-gc-integrity-checks

The first option enables garbage collection integrity checks. This slows down the garbage collection. The default is to disable garbage collection integrity checks.

print-assembly

Print to the current error port the assembly instructions generated when compiling code.

print-optimizer

print-optimiser

Print to the current error port a symbolic expression which results from running the optimiser.

print-loaded-libraries

no-print-loaded-libraries

Whenever a library file is loaded: the first option causes a message to be printed on the console error port. This is for debugging purposes. When used together with library-debug-messages: even more detailed messages are generated for library related actions.

debug-messages

no-debug-messages

Be more verbose about undertaken actions. This is for debugging purposes.

library-debug-messages

no-library-debug-messages

Be more verbose about undertaken library–related actions. This is for debugging purposes.

expander-descriptive-gensyms

Instruct the expander to generate descriptive lexical and storage location gensyms.

expander-descriptive-marks

Instruct the expander to generate descriptive mark objects.

compiler-descriptive-labels

Instruct the compiler to generate descriptive labels.

compiler-core-type-inference

no-compiler-core-type-inference

Instruct the compiler to perform core type inference or not; the default is to perform it. Disabling core type inference automatically disables substitution of core primitive calls with unsafe core primitive calls.

compiler-introduce-primrefs

no-compiler-introduce-primrefs

Instruct the compiler to perform substitution between core primitive calls and unsafe core primitive calls, when the correctness of the operand is determined at compile–time; the default is to perform it.

enable-automatic-gc

disable-automatic-gc

Enable or disable automatic garbage collection. When automatic garbage collection is disabled:

• Memory allocation for Scheme objects is performed by enlarging, when needed, the Scheme heap’s nursery.
• We can still run garbage collection by explicitly invoking collect (see collect).

We can programmatically change this setting with automatic-garbage-collection (see automatic-garbage-collection).

enable-runtime-messages

disable-runtime-messages

Enable or disable printing to the standard error file descriptor some debugging messages from the C language run–time program.

basic-letrec-pass

waddell-letrec-pass

scc-letrec-pass

Select which algorithm to use when optimising letrec and letrec* syntaxes. Accepted values: ‘scc’, ‘waddell’, ‘basic’. Defaults to ‘scc’.

-Wall

Enable all the expander and compiler common warnings. It is equivalent to using the following options:

-Wlogic-constants -Wnot-returning -Wunused-variables

-Wextra

Enable all the expander and compiler extra warnings. It is equivalent to using the following options:

-Woverloaded-function-late-binding

-Wlogic-constants

-Wno-logic-constants

Enable or disable raising a &warning exception when an operand in a logic expression (if test, and, or, …) always returns false or non–false. By default this warning is disabled.

-Wnot-returning

-Wno-not-returning

Enable or disable raising a &warning exception when an operand evaluated for its return values is typed as not returning. By default this warning is disabled.

-Wunused-variables

-Wno-unused-variables

Enable or disable raising a &warning exception when a local lexical variable is defined but never used. By default this warning is disabled.

-Woverloaded-function-late-binding

-Wno-overloaded-function-late-binding

Enable or disable raising a &warning exception when an overloaded function has to default to late binding because the early binding code was unable to find a matching specialised function. By default this warning is disabled.

--scheme-heap-nursery-size num-of-bytes

Configure the Scheme heap’s nursery hot memory block size. The value num-of-bytes must be a positive exact integer fitting a signed long data type, greater than 3 Vicare’s page sizes, 4096 * 3 = 12288. The given num-of-bytes value is normalised by rounding it to the least exact multiple of 4096 greater than num-of-bytes.

--scheme-stack-size num-of-bytes

Configure the Scheme stack size. The value num-of-bytes must be a positive exact integer fitting a signed long data type, greater than 3 Vicare’s page sizes, 4096 * 3 = 12288. The given num-of-bytes value is normalised by rounding it to the least exact multiple of 4096 greater than num-of-bytes.

-O0

Disable the use of the compiler’s source optimiser.

-O1

-O2

-O3

Enable the use of the compiler’s source optimiser at various levels. The default optimisation level is equivalent to -O2.

--optimizer-passes-count COUNT

Specify how many passes to perform with the source optimizer. Must be a positive fixnum. Defaults to 1.

-V

--version

Display the version message then exit.

--version-only

Display only the version number on the standard error port, followed by a newline, then exit.

--license

Display the license message then exit.

-h

--help

Display the help message then exit.

--

Mark the end of vicare options; all the arguments after this marker can be obtained by calling the command-line procedure.

-v

--verbose

Turn on verbose messages describing expander and compiler operations.

--silent

Turn off verbose messages describing compiler operations.