|
|
# Running and Creating Executables
|
|
|
|
|
|
While developing programs, many Racket programmers use the DrRacket
|
|
|
programming environment. To run a program without the development
|
|
|
environment, use `racket` \(for console-based programs\) or `gracket`
|
|
|
\(for GUI programs\). This chapter mainly explains how to run `racket`
|
|
|
and `gracket`.
|
|
|
|
|
|
1 Running `racket` and `gracket`
|
|
|
1.1 Interactive Mode
|
|
|
1.2 Module Mode
|
|
|
1.3 Load Mode
|
|
|
|
|
|
2 Scripts
|
|
|
2.1 Unix Scripts
|
|
|
2.2 Windows Batch Files
|
|
|
|
|
|
3 Creating Stand-Alone Executables
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
### 1.1. Interactive Mode
|
|
|
|
|
|
When `racket` is run with no command-line arguments \(other than
|
|
|
confguration options, like `-j`\), then it starts a REPL with a `> `
|
|
|
prompt:
|
|
|
|
|
|
`Welcome to Racket v7.1.0.6.`
|
|
|
`>`
|
|
|
|
|
|
> 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`.
|
|
|
|
|
|
### 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`
|
|
|
|
|
|
### 1.3. Load Mode
|
|
|
|
|
|
The `-f` or `--load` flag supports `load`ing 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`
|
|
|
|
|
|
`load`s `"hi.rkts"` and exits. Note that load mode is generally a bad
|
|
|
idea, for the reasons explained in \[missing\]; 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`.
|
|
|
|
|
|
## 2. Scripts
|
|
|
|
|
|
Racket files can be turned into executable scripts on Unix and Mac OS.
|
|
|
On Windows, a compatibility layer like Cygwin support the same kind of
|
|
|
scripts, or scripts can be implemented as batch files.
|
|
|
|
|
|
### 2.1. Unix Scripts
|
|
|
|
|
|
In a Unix environment \(including Linux and Mac OS\), a Racket file can
|
|
|
be turned into an executable script using the shell’s `#!` convention.
|
|
|
The first two characters of the file must be `#!`; the next character
|
|
|
must be either a space or `/`, and the remainder of the first line must
|
|
|
be a command to execute the script. For some platforms, the total length
|
|
|
of the first line is restricted to 32 characters, and sometimes the
|
|
|
space is required.
|
|
|
|
|
|
> Use `#lang` `racket/base` instead of `#lang` `racket` to produce scripts
|
|
|
> with a faster startup time.
|
|
|
|
|
|
The simplest script format uses an absolute path to a `racket`
|
|
|
executable followed by a module declaration. For example, if `racket` is
|
|
|
installed in `"/usr/local/bin"`, then a file containing the following
|
|
|
text acts as a “hello world” script:
|
|
|
|
|
|
`#! /usr/local/bin/racket`
|
|
|
`#lang racket/base`
|
|
|
`"Hello, world!"`
|
|
|
|
|
|
In particular, if the above is put into a file `"hello"` and the file is
|
|
|
made executable \(e.g., with `chmod a+x hello`\), then typing `./hello`
|
|
|
at the shell prompt produces the output `"Hello, world!"`.
|
|
|
|
|
|
The above script works because the operating system automatically puts
|
|
|
the path to the script as the argument to the program started by the
|
|
|
`#!` line, and because `racket` treats a single non-flag argument as a
|
|
|
file containing a module to run.
|
|
|
|
|
|
Instead of specifying a complete path to the `racket` executable, a
|
|
|
popular alternative is to require that `racket` is in the user’s command
|
|
|
path, and then “trampoline” using `/usr/bin/env`:
|
|
|
|
|
|
`#! /usr/bin/env racket`
|
|
|
`#lang racket/base`
|
|
|
`"Hello, world!"`
|
|
|
|
|
|
In either case, command-line arguments to a script are available via
|
|
|
`current-command-line-arguments`:
|
|
|
|
|
|
`#! /usr/bin/env racket`
|
|
|
`#lang racket/base`
|
|
|
`(printf "Given arguments: ~s\n"`
|
|
|
`(current-command-line-arguments))`
|
|
|
|
|
|
If the name of the script is needed, it is available via
|
|
|
`(find-system-path 'run-file)`, instead of via
|
|
|
`(current-command-line-arguments)`.
|
|
|
|
|
|
Usually, the best way to handle command-line arguments is to parse them
|
|
|
using the `command-line` form provided by `racket`. The `command-line`
|
|
|
form extracts command-line arguments from
|
|
|
`(current-command-line-arguments)` by default:
|
|
|
|
|
|
`#! /usr/bin/env racket`
|
|
|
`#lang racket`
|
|
|
|
|
|
`(define verbose? (make-parameter #f))`
|
|
|
|
|
|
`(define greeting`
|
|
|
`(command-line`
|
|
|
`#:once-each`
|
|
|
`[("-v") "Verbose mode" (verbose? #t)]`
|
|
|
`#:args`
|
|
|
`(str) str))`
|
|
|
|
|
|
`(printf "~a~a\n"`
|
|
|
`greeting`
|
|
|
`(if (verbose?) " to you, too!" ""))`
|
|
|
|
|
|
Try running the above script with the `--help` flag to see what
|
|
|
command-line arguments are allowed by the script.
|
|
|
|
|
|
An even more general trampoline uses `/bin/sh` plus some lines that are
|
|
|
comments in one language and expressions in the other. This trampoline
|
|
|
is more complicated, but it provides more control over command-line
|
|
|
arguments to `racket`:
|
|
|
|
|
|
`#! /bin/sh`
|
|
|
`#|`
|
|
|
`exec racket -e '(printf "Running...\n")' -u "$0" ${1+"$@"}`
|
|
|
`|#`
|
|
|
`#lang racket/base`
|
|
|
`(printf "The above line of output had been produced via\n")`
|
|
|
`(printf "a use of the `-e' flag.\n")`
|
|
|
`(printf "Given arguments: ~s\n"`
|
|
|
`(current-command-line-arguments))`
|
|
|
|
|
|
Note that `#!` starts a line comment in Racket, and `#|`...`|#` forms a
|
|
|
block comment. Meanwhile, `#` also starts a shell-script comment, while
|
|
|
`exec racket` aborts the shell script to start `racket`. That way, the
|
|
|
script file turns out to be valid input to both `/bin/sh` and `racket`.
|
|
|
|
|
|
### 2.2. Windows Batch Files
|
|
|
|
|
|
A similar trick can be used to write Racket code in Windows `.bat` batch
|
|
|
files:
|
|
|
|
|
|
`; @echo off`
|
|
|
`; Racket.exe "%~f0" %*`
|
|
|
`; exit /b`
|
|
|
`#lang racket/base`
|
|
|
`"Hello, world!"`
|
|
|
|
|
|
## 3. Creating Stand-Alone Executables
|
|
|
|
|
|
For information on creating and distributing executables, see
|
|
|
\[missing\] and \[missing\] in \[missing\].
|