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 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. 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 command line is started, Racket loads the file (find-system-path 'init-file) and GRacket loads the file (find-graphical-system-path 'init-file) is loaded, unless the -q/--no-init-file flag is specified on the command line.

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

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.), 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.

 (require racket/gui/init) package: gui-lib
The racket/gui/init library is the default start-up library for GRacket. It re-exports the racket/init and racket/gui/base libraries, and it sets current-load to use text-editor-load-handler.

 (require racket/language-info) 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.

 (require racket/runtime-config) package: base
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 X, 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.

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

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.