On this page:
18.1.1 Initialization
18.1.2 Exit Status
18.1.3 Init Libraries
18.1.4 Command Line
18.1.5 Language Run-Time Configuration
18.1.6 Language Expand Configuration

18.1 Running Racket or GRacket

The core Racket run-time system is available in two main variants:

18.1.1 Initialization

On start-up, the top-level environment contains no bindings—not even #%app for function application. Primitive modules with names that start with #% are defined, but they are not meant for direct use, and the set of such modules can change. For example, the '#%kernel module is eventually used to bootstrap the implementation of racket/base.

The first action of Racket or GRacket is to initialize current-library-collection-paths to the result of (find-library-collection-paths pre-extras extras), where pre-extras is normally null and extras are extra directory paths provided in order in the command line with -S/--search. An executable created from the Racket or GRacket executable can embed paths used as pre-extras.

Racket and GRacket next require racket/init and racket/gui/init, respectively, but only if the command line does not specify a require flag (-t/--require, -l/--lib, or -u/--require-script) before any eval, load, or read-eval-print-loop flag (-e/--eval, -f/--load, -r/--script, -m/--main, or -i/--repl). The initialization library can be changed with the -I configuration option. The configure-runtime submodule of the initialization library or the 'configure-runtime property of the initialization library’s language is used before the library is instantiated; see Language Run-Time Configuration.

After potentially loading the initialization module, expression evals, files loads, and module requires are executed in the order that they are provided on the command line. If any raises an uncaught exception, then the remaining evals, loads, and requires are skipped. If the first require precedes any eval or load so that the initialization library is skipped, then the configure-runtime submodule of the required module or the 'configure-runtime property of the required module’s library language is used before the module is instantiated; see Language Run-Time Configuration.

After running all command-line expressions, files, and modules, Racket or GRacket then starts a read-eval-print loop for interactive evaluation if no command line flags are provided other than configuration options. For Racket, the read-eval-print loop is run by calling read-eval-print-loop from racket/repl. For GRacket, the read-eval-print loop is run by calling graphical-read-eval-print-loop from racket/gui/base. If any command-line argument is provided that is not a configuration option, then the read-eval-print-loop is not started, unless the -i/--repl flag is provided on the command line to specifically re-enable it.

In addition, just before the read-eval-print loop is started, Racket runs racket/interactive and GRacket runs racket/gui/interactive, unless a different interactive file is specified in the the installation’s "config.rktd" file found in (find-config-dir), or the file "interactive.rkt" is found in (find-system-path 'addon-dir). If the -q/--no-init-file flag is specified on the command line, then no interactive file is run.

Finally, before Racket or GRacket exits, it calls the procedure that is the current value of executable-yield-handler in the main thread, unless the -V/--no-yield command-line flag is specified. Requiring racket/gui/base sets this parameter call (racket 'yield).

Changed in version 6.7 of package base: Run racket/interactive file rather than directly running (find-system-path 'init-file).
Changed in version 6.90.0.30: Run a read-eval-print loop by using racket/repl or racket/gui/base instead of racket/base or racket/gui/init.

18.1.2 Exit Status

The default exit status for a Racket or GRacket process is non-zero if an error occurs during a command-line eval (via -e, etc.), load (via -f, -r, etc.), or require (via -l, -t, etc.)—or, more generally, if the abort handler of the prompt surrounding those evalutions is called—but only when no read-eval-print loop is started. Otherwise, the default exit status is 0.

In all cases, a call to exit (when the default exit handler is in place) can end the process with a specific status value.

18.1.3 Init Libraries

 (require racket/init) package: base
The racket/init library is the default start-up library for Racket. It re-exports the racket, racket/enter and racket/help libraries, and it sets current-print to use pretty-print.

The racket/interactive is the default start up library when the REPL begins. It is not run if the -q/--no-init-file is specified. The interactive file can be changed by modifying 'interactive-file in the "config.rktd" file found in (find-config-dir). Alternative, if the file "interactive.rkt" exists in (find-system-path 'addon-dir) it is run rather than the installation wide interactive module.
The default interactive module starts xrepl and runs the (find-system-path 'init-file) file in the users home directory. A different interactive file can keep this behavior by requiring racket/interactive.

Added in version 6.7 of package base.

The racket/language-info library provides a get-info function that takes any value and returns another function; the returned function takes a key value and a default value, and it returns '(#(racket/runtime-config configure #f)) if the key is 'configure-runtime or the default value otherwise.

+See also Module-Handling Configuration in The Racket Guide.

The vector '#(racket/language-info get-info #f) is suitable for attaching to a module as its language info to get the same language information as the racket/base language.

The racket/runtime-config library provides a configure function that takes any value and sets print-as-expression to #t.

The vector #(racket/runtime-config configure #f) is suitable as a member of a list of runtime-configuration specification (as returned by a module’s language-information function for the key 'configure-runtime) to obtain the same runtime configuration as for the racket/base language.

18.1.4 Command Line

The Racket and GRacket executables recognize the following command-line flags:

If at least one command-line argument is provided, and if the first one after any configuration option is not a flag, then a -u/--require-script flag is implicitly added before the first non-flag argument.

If no command-line arguments are supplied other than configuration options, then the -i/--repl flag is effectively added.

For GRacket on Unix, the follow flags are recognized when they appear at the beginning of the command line, and they count as configuration options (i.e., they do not disable the read-eval-print loop or prevent the insertion of -u/--require-script):

Similarly, on Mac OS, a leading switch starting with -psn_ is treated as a special configuration option. It indicates that Finder started the application, so the current input, output, and error output are redirected to a GUI window.

Multiple single-letter switches (the ones preceded by a single -) 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,

  -ifve file expr

and

  -i -f file -v -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.

Extra arguments following the last option are available from the current-command-line-arguments parameter.

Changed in version 6.90.0.17 of package base: Added -O/--stdout.
Changed in version 7.1.0.5: Added -M/--compile-any.
Changed in version 7.8.0.6: Added -Z.
Changed in version 8.0.0.10: Added -E.
Changed in version 8.0.0.11: Added -Y.
Changed in version 8.4.0.1: Added -y/--make.

18.1.5 Language Run-Time Configuration

+See also Module-Handling Configuration in The Racket Guide.

A module can have a configure-runtime submodule that is dynamic-required before the module itself when a module is the main module of a program. Normally, a configure-runtime submodule is added to a module by the module’s language (i.e., by the #%module-begin form among a module’s initial bindings). The body of a configure-runtime submodule typically sets parameters, possibly including current-interaction-info.

Alternatively or in addition, an older protocol is in place. When a module is implemented using #lang, the language after #lang can specify configuration actions to perform when a module using the language is the main module of a program. The language specifies run-time configuration by

A 'configure-runtime query returns a list of vectors, instead of directly configuring the environment, so that the indicated modules to be bundled with a program when creating a stand-alone executable; see raco exe: Creating Stand-Alone Executables in raco: Racket Command-Line Tools.

For information on defining a new #lang language, see syntax/module-reader.

18.1.6 Language Expand Configuration

A module lang can have a configure-expand submodule that is dynamic-required before the expansion of another module that is implemented as (module name lang ....). The submodule is loaded in a root namespace, the same as a reader module. The submodule should provide enter-parameterization and exit-parameterization as procedures that each take no arguments and return a parameterization:

The current-parameterization procedure works as a default for both enter-parameterization and exit-parameterization.

The parameterization produced by a enter-parameterization typically sets parameters that affect error reporting during expansion, such as error-syntax->string-handler. The parameterization produced by exit-parameterization should generally revert any changes made by enter-parameterization while keeping other parameter values intact (such as current-load-relative-directory). To communicate from a use of enter-parameterization to a nested use of exit-parameterization, use a private parameter.

The enter-parameterization and exit-parameterization procedures are expected to build on the current parameterization, but they should generally not mutate current parameters, since that mutation would extend beyond the use of the returned parameterization. Instead, use parameterize to create a new parameterization with updated parameter values. The enter-parameterization and exit-parameterization should also not operate on the current namespace, since that can interfere with module expansion.

Added in version 8.8.0.6 of package base.