#
Chapter 17
Running MzScheme

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

MzScheme accepts the following flags:

- Startup file and expression flags:

  - `-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.

  - `-r` `file` or `--script` `file` : Use this flag 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 flag. The `-r` or `--script` flag 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` flag is a shorthand for `-dmv-`.

  - `-u` `file` or `--require-script` `file` : Same as `-r` `file` or `--script` `file`, except that `file` is `require`d instead of `load`ed. The `-u` or `--require-script` flag 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 flag 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 flags:

  - `-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 flag 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 flags:

  - `-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 flags:

  - `--` : No argument following this flag is used as a flag.

  - `-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 flags and then exits, ignoring other flags.

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

  - `-R` `file` or `--restore` `file` : Restores a saved image (see section 14.5). Extra arguments after `file` are returned as a vector of strings to the continuation of the `write-image-to-file` call that created the image.

## 17.1 Flag Conventions

Extra arguments following the last flag 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 flags (the ones preceded by a single dash) can be collapsed into a single flag by concatenating the letters, as long as the first flag is not `--`. The arguments for each flag are placed after the collapsed flags (in the order of the flags). For example, ``

-vfme `file` `expr`

and ``

-v -f `file` -m -e `expr`

are equivalent. If a collapsed `--` appears before other collapsed flags, 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` flag is specified.

Unless the `-q` or `--no-init-file` flag 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` flag 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.