21.1 Running racket and gracket

► |  | The Racket Guide

1 | Welcome to Racket
2 | Racket Essentials
3 | Built-In Datatypes
4 | Expressions and Definitions
5 | Programmer-Defined Datatypes
6 | Modules
7 | Contracts
8 | Input and Output
9 | Regular Expressions
10 | Exceptions and Control
11 | Iterations and Comprehensions
12 | Pattern Matching
13 | Classes and Objects
14 | Units
15 | Reflection and Dynamic Evaluation
16 | Macros
17 | Creating Languages
18 | Concurrency and Synchronization
19 | Performance
20 | Parallelism
21 | Running and Creating Executables
22 | More Libraries
23 | Dialects of Racket and Scheme
24 | Command-Line Tools and Your Editor of Choice
| Bibliography
| Index

▼ | 21 | Running and Creating Executables

21.1 | Running racket and gracket
21.2 | Scripts
21.3 | Creating Stand-Alone Executables

► | 21.1 | Running racket and gracket

21.1.1 | Interactive Mode
21.1.2 | Module Mode
21.1.3 | Load Mode

On this page:

21.1.1 Interactive Mode
21.1.2 Module Mode
21.1.3 Load Mode

Racket
top contents ← prev up next →

### 21.1 Running racket and gracket🔗ℹ

The gracket executable is the same as racket, but with small adjustments to behave as a GUI application rather than a console application. For example, gracket by default runs in interactive mode with a GUI window instead of a console prompt. GUI applications can be run with plain racket, however.

Depending on command-line arguments, racket or gracket runs in interactive mode, module mode, or load mode.

#### 21.1.1 Interactive Mode🔗ℹ

When racket is run with no command-line arguments (other than configuration options, like -j), then it starts a REPL with a > prompt:

Welcome to Racket v9.3 [cs].
>

> > > For enhancing your REPL experience, see xrepl; for information on GNU Readline support, see readline.

To initialize the REPL’s environment, racket first requires the racket/init module, which provides all of racket, and also installs pretty-print for display results. Finally, racket loads the file reported by (find-system-path 'init-file), if it exists, before starting the REPL.

If any command-line arguments are provided (other than configuration options), add -i or --repl to re-enable the REPL. For example,

racket -e '(display "hi\n")' -i

displays “hi” on start-up, but still presents a REPL.

If module-requiring flags appear before -i/--repl, they cancel the automatic requiring of racket/init. This behavior can be used to initialize the REPL’s environment with a different language. For example,

racket -l racket/base -i

starts a REPL using a much smaller initial language (that loads much faster). Beware that most modules do not provide the basic syntax of Racket, including function-call syntax and require. For example,

racket -l racket/date -i

produces a REPL that fails for every expression, because racket/date provides only a few functions, and not the #%top-interaction and #%app bindings that are needed to evaluate top-level function calls in the REPL.

If a module-requiring flag appears after -i/--repl instead of before it, then the module is required after racket/init to augment the initial environment. For example,

racket -i -l racket/date

starts a useful REPL with racket/date available in addition to the exports of racket.

#### 21.1.2 Module Mode🔗ℹ

If a file argument is supplied to racket before any command-line switch (other than configuration options), then the file is required as a module, and (unless -i/--repl is specified), no REPL is started. For example,

racket hello.rkt

requires the "hello.rkt" module and then exits. Any argument after the file name, flag or otherwise, is preserved as a command-line argument for use by the required module via current-command-line-arguments.

If command-line flags are used, then the -u or --require-script flag can be used to explicitly require a file as a module. The -t or --require flag is similar, except that additional command-line flags are processed by racket, instead of preserved for the required module. For example,

racket -t hello.rkt -t goodbye.rkt

requires the "hello.rkt" module, then requires the "goodbye.rkt" module, and then exits.

The -l or --lib flag is similar to -t/--require, but it requires a module using a lib module path instead of a file path. For example,

racket -l raco

is the same as running the raco executable with no arguments, since the raco module is the executable’s main module.

Note that if you wanted to pass command-line flags to raco above, you would need to protect the flags with a --, so that racket doesn’t try to parse them itself:

racket -l raco -- --help

#### 21.1.3 Load Mode🔗ℹ

The -f or --load flag supports loading top-level expressions in a file directly, as opposed to expressions within a module file. This evaluation is like starting a REPL and typing the expressions directly, except that the results are not printed. For example,

racket -f hi.rkts

loads "hi.rkts" and exits. Note that load mode is generally a bad idea, for the reasons explained in A Note to Readers with Lisp/Scheme Experience; using module mode is typically better.

The -e or --eval flag accepts an expression to evaluate directly. Unlike file loading, the result of the expression is printed, as in a REPL. For example,

racket -e '(current-seconds)'

prints the number of seconds since January 1, 1970.

For file loading and expression evaluation, the top-level environment is created in the same way for interactive mode: racket/init is required unless another module is specified first. For example,

racket -l racket/base -e '(current-seconds)'

likely runs faster, because it initializes the environment for evaluation using the smaller racket/base language, instead of racket/init.

top contents ← prev up next →