Chapter 17

Running MzScheme

The stand-alone version of MzScheme accepts a number of command-line options.

MzScheme accepts the following options:

• Startup file and expression options:

  •    -e expr or --eval expr : Evaluates expr after MzScheme starts.

  •    -f file or --load file : Loads file after MzScheme starts.

  •    -d file or --load-cd file : Uses load/cd to load file after MzScheme starts.

  •    -t file or --require file : Requires file after MzScheme starts.

  •    -F or --Load : Loads each remaining argument as a file after MzScheme starts.

  •    -D or --Load-cd : Loads each remaining argument as a file using load/cd after MzScheme starts.

  •    -T or --Require : Requires each remaining argument as a file after MzScheme starts.

  •    -l file or --mzlib file: Requires the MzLib library file after MzScheme starts.

  •    -L file collect : Requires the library file in the collection collect after MzScheme starts.

  •    -M collect : Requires the library collect.ss in the collection collect after MzScheme starts.

  •    -p file user package : Requires a PLaneT library whose module path is (planet file (user package)).

  •    -P name user : Requires a PLaneT library, a shorthand for -p name.ss user name.plt.

  •    -r file or --script file : Use this option for MzScheme-based scripts. It mutes the startup banner printout, suppresses the read-eval-print loop, and loads file after MzScheme starts. No argument after file is treated as a switch. The -r or --script switch is a shorthand for -fmv-.

  •    -i file or --script-cd file : Same as -r file or --script file, except that the current directory is changed to file's directory before it is loaded. The -i or --script-cd switch is a shorthand for -dmv-.

  •    -u file or --require-script file : Same as -r file or --script file, except that file is required instead of loaded. The -u or --require-script switch is a shorthand for -tmv-.

  •    -w or --awk : Loads the awk.ss library after MzScheme starts.

  •    -k n m : Loads code embedded in the executable from file position n to m after MzScheme starts. This option is useful for creating a stand-alone binary by appending code to the normal MzScheme executable. See PLT mzc: MzScheme Compiler Manual for more details.

  •    -C or --main : Like -r, then calls the function bound to main in the top-level environment. The argument to main is a list of immutable strings; the first string is the path of the file that was loaded, and the rest of the list contains leftover command-line arguments (the ones installed in current-command-line-arguments). The main function is called only if no previous evaluations or loads resulted in an uncaught exception.

• Initialization options:

  •    -X dir or --collects dir : Sets dir as the path to the main collection of libraries (and makes (find-system-path 'collects-dir) produce dir).

  •    -S dir or --search dir : Adds dir to the library collection search path (after a user-specific directory, if any, and before the main collection directory).

  •    -U or --no-user-path : Omits paths in the search for collections, C libraries, etc. More specifically, this option initializes the use-user-specific-search-paths parameter to #f.

  •    -x or --no-lib-path : Suppresses the initialization of current-library-collection-paths (as described in Chapter 16).

  •    -N file or --name file : sets the name of the executable as reported by (find-system-path 'run-file) to file. Also, program is initially defined as file.

  •    -q or --no-init-file : Suppresses loading the user's initialization file, as described below.

  •    -A or --no-argv : Suppresses the definition of argv and program, as described below.

  •    -j or --no-jit : Disables the native-code just-in-time compiler, setting the eval-jit-enabled parameter to #f.

• Language setting options:

  •    -Q or --prim : Initializes the top-level environment with (require mzscheme), which improves performance of non-module programs by allowing top-level bindings to be recognized. In this mode, primitive names can be re-defined in the top-level environment, but re-definition affects only expressions compiled after the re-definition.

  •    -g or --case-sens : Makes the reader initially case-sensitive (the default).

  •    -G or --case-insens : Makes the reader initially case-insensitive.

  •    -s or --set-undef : Creates an initial namespace where set! will successfully mutate an undefined global variable (implicitly defining it).

• Miscellaneous options:

  •    -- : No argument following this switch is used as a switch.

  •    -m or --mute-banner : Suppresses the startup banner text produced by -v.

  •    -v or --version : Suppresses the read-eval-print loop.

  •    -h or --help : Shows information about MzScheme's command-line options and then exits, ignoring other options.

  •    --persistent : Catches the SIGDANGER (low page space) signal and ignores it (AIX only).

17.1  Command-Line Conventions

Extra arguments following the last option are available from the current-command-line-arguments parameter (see section 7.9.1.6) as an immutable vector of immutable strings. The name used to start MzScheme is available from the find-system-path procedure (see section 11.3.2) using 'exec-file. In addition, unless -A is specified, the argument vector is put into the global variable argv, and the name used to start MzScheme is put into the global variable program as a path.

Multiple single-letter switches (the ones preceded by a single dash) can be collapsed into a single switch by concatenating the letters, as long as the first switch is not --. The arguments for each switch are placed after the collapsed switches (in the order of the switches). For example,

   -vfme file expr

and

   -v -f file -m -e expr

are equivalent. If a collapsed -- appears before other collapsed switches in the same collapsed set, it is implicitly moved to the end of the collapsed set.

17.2  Executable Name

If the MzScheme executable is given a name of the form scheme-dialect, then the command line is effectively prefixed with

   -qAeC '(require (lib "init.ss" "script-lang" "dialect"))'

The first actual command-line argument thus serves as a file to load. The file is loaded into a namespace that is initialized by the dialect-specific init.ss library. The loaded file should define main, which is called with command-line arguments -- starting with the loaded file name -- as a list of immutable strings.

17.3  Initialization

The current-library-collection-paths parameter is initialized (as described in Chapter 16) before any expression or file is evaluated or loaded, unless the -x or --no-lib-path option is specified.

Unless the -q or --no-init-file option is specified, a user initialization file is loaded after current-library-collection-paths parameter is initialized and before any other expression or file is evaluated or loaded. The path to the user initialization file is obtained from MzScheme's find-system-path procedure using 'init-file.

Expressions and files are evaluated and loaded in order that they are provided on the command line, including calls to main implied by --main, embeddings loaded by -k, and so on. If an uncaught exception occurs, the remaining expressions and files are skipped. The thread that loads the files and evaluates the expressions is the main thread. When the main thread terminates (or is killed), the MzScheme process exits.

After the command-line files and expressions are loaded and evaluated, the main thread calls read-eval-print-loop, unless the -v, --version, -r, --script, -i, or --script-cd option is specified.

The exit status for the MzScheme process indicates an error if an error occurs evaluating or loading a command-line expression or file and read-eval-print-loop is not called afterwards, or if the default exit handler is called with an exact integer between 1 and 255.