18.1 Running Racket or GRacket (original) (raw)
18.1 Running Racket or GRacket🔗ℹ
The core Racket run-time system is available in two main variants:
- Racket, which provides the primitives libraries on whichracket/base is implemented. On Unix and Mac OS, the executable is calledracket. On Windows, the executable is called Racket.exe.
- GRacket, which is a GUI variant of racket to the degree that the system distinguishes them. On Unix, the executable is called gracket, and single-instance flags and X11-related flags are handled and communicated specially to the racket/gui/base library. On Windows, the executable is called GRacket.exe, and it is a GUI application (as opposed to a console application) that implements single-instance support. On Mac OS, thegracket script launches GRacket.app.
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 initializecurrent-library-collection-paths to the result of(find-library-collection-paths pre-extras extras), wherepre-extras is normally null and extrasare 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/initand 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. Theconfigure-runtime submodule of the initialization library or the'configure-runtime property of the initialization library’s language is used before the library is instantiated; seeLanguage Run-Time Configuration.
After potentially loading the initialization module, expressionevals, 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 firstrequire precedes any eval or load so that the initialization library is skipped, then the configure-runtimesubmodule of the required module or the'configure-runtime property of the required module’s library language is used before the module is instantiated; seeLanguage 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 thanconfiguration options. For Racket, the read-eval-print loop is run by calling read-eval-print-loop fromracket/repl. For GRacket, the read-eval-print loop is run by calling graphical-read-eval-print-loop fromracket/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/--replflag 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/interactiveand 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/baseinstead 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.), orrequire (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 is0.
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🔗ℹ
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.
Theracket/language-info library provides aget-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.
Theracket/runtime-config library provides aconfigure function that takes any value and sets print-as-expressionto #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:
- File and expression options:
- -e ‹expr› or --eval ‹expr› : evals ‹expr›. The results of the evaluation are printed via current-print.
- -f ‹file› or --load ‹file› : loads ‹file›; if‹file› is "-", then expressions are read and evaluated from standard input.
- -t ‹file› or --require ‹file› : requires ‹file›, and thenrequires (submod (file "‹file›") main) if available.
- -l ‹path› or --lib ‹path› : requires (lib "‹path›"), and then requires(submod (lib "‹path›") main) if available.
- -p ‹package› :requires (planet "‹package›"), and thenrequires (submod (planet "‹package›") main) if available.
- -r ‹file› or --script ‹file› : loads ‹file› Despite its name, --script is not usually used for Unix scripts. See Scripts for more information on scripts. as a script. This flag is like -f ‹file› plus-N ‹file› to set the program name and -- to cause all further command-line elements to be treated as non-flag arguments.
- -u ‹file› or --require-script ‹file› : requires ‹file› as a script; This flag is like -t ‹file› plus -N ‹file› to set the program name and -- to cause all further command-line elements to be treated as non-flag arguments.
- -k ‹n› ‹m› ‹p› : Loads code embedded in the executable from file position ‹n› to‹m› and from ‹m› to ‹p›. (On Mac OS,‹n›, ‹m›, and ‹p› are relative to a__PLTSCHEME segment in the executable. On Windows, they are relative to a resource of type 257 and ID 1. On Unix using ELF, they are relative to the .rackprog segment in the executable.) The first range is loaded in every new place, and any modules declared in that range are considered predefined in the sense ofmodule-predefined?. This option is normally embedded in a stand-alone binary that also embeds Racket code.
- -Y ‹file› ‹n› ‹m› ‹p› : Like -k ‹n› ‹m› ‹p›, but reading from ‹file› (without any adjustment for a segment or resource offset).
- -m or --main : Evaluates a call tomain as bound in the top-level environment. All of the command-line arguments that are not processed as options (i.e., the arguments put intocurrent-command-line-arguments) are passed as arguments to main. The results of the call are printed via current-print.
The call to main is constructed as an expression (main arg-str ...) where the lexical context of the expression gives#%app and #%datum bindings as#%plain-app and #%datum, but the lexical context of main is the top-level environment.
- Interaction options:
- -i or --repl : Runs an interactive read-eval-print loop, using either read-eval-print-loop (Racket) orgraphical-read-eval-print-loop (GRacket) after showing(banner) and loading (find-system-path 'init-file). In the case of Racket, (read-eval-print-loop)is followed by (newline). For GRacket, supply the -z/--text-replconfiguration option to use read-eval-print-loop (and newline) instead of graphical-read-eval-print-loop.
- -n or --no-lib : Skips requiring the initialization library (i.e., racket/init orracket/gui/init, unless it is changed with the-I flag) when not otherwise disabled.
- -v or --version : Shows(banner).
- -K or --back : GRacket, Mac OS only; leave application in the background.
- -V --no-yield : Skips finalexecutable-yield-handler action, which normally waits until all frames are closed, etc. in the main eventspace before exiting for programs that use racket/gui/base.
- Configuration options:
- -y or --make : Enables automatic generation and update of compiled ".zo" files for modules loaded in the initial namespace. Specifically, the result of(make-compilation-manager-load/use-compiled-handler)is installed as the compiled-load handler before other module-loading actions. Caution: This flag is intended for use in interactive settings; using it in a script is probably a bad idea, because concurrent invocations of the script may collide attempting to update compiled files, or there may be filesystem-permission issues. Using-c/--no-compiled cancels the effect of-y/--make.
- -c or --no-compiled : Disables loading of compiled ".zo" files, by initializinguse-compiled-file-paths to null. Use judiciously: this effectively ignores the content of all"compiled" subdirectories, so that any used modules are compiled on the fly—even racket/base and its dependencies—which leads to prohibitively expensive run times.
- -q or --no-init-file : Skips loading(find-system-path 'init-file) for-i/--repl.
- -z or --text-repl : GRacket only; changes-i/--repl to usetextual-read-eval-print-loop instead ofgraphical-read-eval-print-loop.
- -I ‹path› : Sets (lib "‹path›") as the path to require to initialize the namespace, unless namespace initialization is disabled. Using this flag can effectively set the language for the read-eval-print loop and other top-level evaluation.
- -X ‹dir› or --collects ‹dir› : Sets ‹dir› as the path to the main collection of libraries by making (find-system-path 'collects-dir) produce ‹dir›. If ‹dir› is an empty string, then (find-system-path 'collects-dir)returns ".", butcurrent-library-collection-paths is initialized to the empty list, and use-collection-link-paths is initialized to #f.
- -S ‹dir› or --search ‹dir› : Adds ‹dir› to the default library collection search path after the main collection directory. If the -S/--dir flag is supplied multiple times, the search order is as supplied.
- -G ‹dir› or --config ‹dir› : Sets the directory that is returned by(find-system-path 'config-dir).
- -A ‹dir› or --addon ‹dir› : Sets the directory that is returned by(find-system-path 'addon-dir).
- -U or --no-user-path : Omits user-specific paths in the search for collections, C libraries, etc. by initializing theuse-user-specific-search-paths parameter to#f.
- -A ‹dir› or --addon ‹dir› : Sets the directory that is returned by(find-system-path 'addon-dir).
- -R ‹paths› or --compiled ‹paths› : Sets the initial value of thecurrent-compiled-file-roots parameter, overriding any PLTCOMPILEDROOTS setting. The ‹paths›argument is parsed in the same way as PLTCOMPILEDROOTS(see current-compiled-file-roots).
- -C or --cross : Select cross-platform build mode, causing (system-type 'cross) to report'force, and sets the current configuration of(find-system-path 'config-dir) and(find-system-path 'collects-dir) to be the results of(find-system-path 'host-config-dir) and(find-system-path 'host-collects-dir), respectively. If -C or --cross is provided multiple times, only the first instance has an effect.
- -N ‹file› or --name ‹file› : sets the name of the executable as reported by (find-system-path 'run-file) to‹file›.
- -E ‹file› or --exe ‹file› : sets the name of the executable as reported by (find-system-path 'exec-file) to‹file›.
- -J ‹name› or --wm-class ‹name› : GRacket, Unix only; sets the WM_CLASSprogram class to ‹name› (while the WM_CLASSprogram name is derived from the executable name or a-N/--name argument).
- -j or --no-jit : Disables the native-code just-in-time compiler by setting theeval-jit-enabled parameter to #f.
- -M or --compile-any : Enables machine-independent bytecode by setting thecurrent-compile-target-machine parameter to#f.
- -d or --no-delay : Disables on-demand parsing of compiled code and syntax objects by setting theread-on-demand-source parameter to #f.
- -b or --binary : Requests binary mode, instead of text mode, for the process’s input, out, and error ports. This flag currently has no effect, because binary mode is always used.
- -W ‹levels› or --warn ‹levels› : Sets the logging level for writing events to the original error port. The possible ‹level› values are the same as for the PLTSTDERR environment variable. See Logging for more information.
- -O ‹levels› or --stdout ‹levels› : Sets the logging level for writing events to the original output port. The possible ‹level› values are the same as for the PLTSTDOUT environment variable. See Logging for more information.
- -L ‹levels› or --syslog ‹levels› : Sets the logging level for writing events to the system log. The possible ‹level› values are the same as for the PLTSYSLOG environment variable. See Logging for more information.
- Meta options:
- -Z : The argument following this flag is ignored. This flag can be handy in some impoverished scripting environments to replace or cancel another command-line argument.
- -- : No argument following this flag is itself used as a flag.
- -h or --help : Shows information about the command-line flags and start-up process and exits, ignoring all other 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 thanconfiguration 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):
- -display ‹display› : Sets the X11 display to use.
- -geometry ‹arg›, -bg ‹arg›, -background ‹arg›,-fg ‹arg›, -foreground ‹arg›, -fn ‹arg›, -font ‹arg›, -iconic, -name ‹arg›, -rv, -reverse,+rv, -selectionTimeout ‹arg›,-synchronous, -title ‹arg›,-xnllanguage ‹arg›, or -xrm ‹arg› : Standard X11 arguments that are mostly ignored but accepted for compatibility with other X11 programs. The-synchronous flag behaves in the usual way.
- -singleInstance : If an existing GRacket is already running on the same X11 display, if it was started on a machine with the same hostname, and if it was started with the same name as reported by (find-system-path 'run-file)—possibly set with the -N/--namecommand-line argument—then all non-option command-line arguments are treated as filenames and sent to the existing GRacket instance via the application file handler (seeapplication-file-handler).
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 thecurrent-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 isdynamic-required before the module itself when a module is the main module of a program. Normally, a configure-runtimesubmodule 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 includingcurrent-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
- attaching a 'module-language syntax property to the module as read from its source (see module andmodule-compiled-language-info);
- having the function indicated by the 'module-language syntax property recognize the'configure-runtime key, for which it returns a list of vectors; each vector must have the form (vector mp name val) where mp is a module path,name is a symbol, and val is an arbitrary value; and
- having each function called as ((dynamic-require mp name) val) configure the run-time environment, typically by setting parameters such as current-print.
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 inraco: Racket Command-Line Tools.
For information on defining a new #lang language, seesyntax/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 provideenter-parameterization andexit-parameterization as procedures that each take no arguments and return a parameterization:
- enter-parameterization for lang is called at the start of an expansion of a module (module name lang ....), and the parameterization wraps the module expansion via call-with-parameterization.
- exit-parameterization is called forlang if the expansion of (module name lang ....) triggers expansion of other modules, typically because they are required by the module being expanded. In that case,exit-parameterization is called to obtain a parameterization that is put in place around a call toenter-parameterization for the language of the module newly being expanded.
The current-parameterization procedure works as a default for both enter-parameterization andexit-parameterization.
The parameterization produced by aenter-parameterization typically sets parameters that affect error reporting during expansion, such aserror-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 ascurrent-load-relative-directory). To communicate from a use of enter-parameterization to a nested use ofexit-parameterization, use a private parameter.
The enter-parameterization andexit-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. Theenter-parameterization andexit-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.