180 lines
6.8 KiB
Racket
180 lines
6.8 KiB
Racket
#lang scribble/doc
|
|
@(require scribble/manual "guide-utils.rkt" (for-syntax racket/pretty))
|
|
|
|
@title[#:tag "running" #:style 'toc]{Running and Creating Executables}
|
|
|
|
While developing programs, many Racket programmers use the
|
|
@seclink[#:doc '(lib "scribblings/drracket/drracket.scrbl")
|
|
"top"]{DrRacket} programming environment. To run a program without the
|
|
development environment, use @exec{racket} (for console-based
|
|
programs) or @exec{gracket} (for GUI programs). This chapter mainly
|
|
explains how to run @exec{racket} and @exec{gracket}.
|
|
|
|
@local-table-of-contents[]
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@section[#:tag "racket"]{Running @exec{racket} and @exec{gracket}}
|
|
|
|
The @exec{gracket} executable is the same as @exec{racket}, but with
|
|
small adjustments to behave as a GUI application rather than a console
|
|
application. For example, @exec{gracket} by default runs in
|
|
interactive mode with a GUI window instead of a console prompt. GUI
|
|
applications can be run with plain @exec{racket}, however.
|
|
|
|
Depending on command-line arguments, @exec{racket} or @exec{gracket}
|
|
runs in @seclink["start-interactive-mode"]{interactive mode},
|
|
@seclink["start-module-mode"]{module mode}, or
|
|
@seclink["start-load-mode"]{load mode}.
|
|
|
|
@subsection[#:tag "start-interactive-mode"]{Interactive Mode}
|
|
|
|
When @exec{racket} is run with no command-line arguments (other than
|
|
confguration options, like @Flag{j}), then it starts a @tech{REPL}
|
|
with a @litchar{> } prompt:
|
|
|
|
@verbatim[#:indent 2]{
|
|
@(regexp-replace #rx"\n+$" (banner) "")
|
|
>
|
|
}
|
|
|
|
@margin-note{For enhancing your @tech{REPL} experience, see
|
|
@racketmodname[xrepl]; for information on GNU Readline support, see
|
|
@racketmodname[readline].}
|
|
|
|
To initialize the @tech{REPL}'s environment, @exec{racket} first
|
|
requires the @racketmodname[racket/init] module, which provides all of
|
|
@racket[racket], and also installs @racket[pretty-print] for display
|
|
results. Finally, @exec{racket} loads the file reported by
|
|
@racket[(find-system-path 'init-file)], if it exists, before starting
|
|
the @tech{REPL}.
|
|
|
|
If any command-line arguments are provided (other than configuration
|
|
options), add @Flag{i} or @DFlag{repl} to re-enable the
|
|
@tech{REPL}. For example,
|
|
|
|
@commandline{racket -e '(display "hi\n")' -i}
|
|
|
|
displays ``hi'' on start-up, but still presents a @tech{REPL}.
|
|
|
|
If module-requiring flags appear before @Flag{i}/@DFlag{repl}, they
|
|
cancel the automatic requiring of @racketmodname[racket/init]. This
|
|
behavior can be used to initialize the @tech{REPL}'s environment with
|
|
a different language. For example,
|
|
|
|
@commandline{racket -l racket/base -i}
|
|
|
|
starts a @tech{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 @racket[require]. For
|
|
example,
|
|
|
|
@commandline{racket -l racket/date -i}
|
|
|
|
produces a @tech{REPL} that fails for every expression, because
|
|
@racketmodname[racket/date] provides only a few functions, and not the
|
|
@racket[#%top-interaction] and @racket[#%app] bindings that are needed
|
|
to evaluate top-level function calls in the @tech{REPL}.
|
|
|
|
If a module-requiring flag appears after @Flag{i}/@DFlag{repl} instead
|
|
of before it, then the module is required after
|
|
@racketmodname[racket/init] to augment the initial environment. For
|
|
example,
|
|
|
|
@commandline{racket -i -l racket/date}
|
|
|
|
starts a useful @tech{REPL} with @racketmodname[racket/date] available
|
|
in addition to the exports of @racketmodname[racket].
|
|
|
|
@; ----------------------------------------
|
|
|
|
@subsection[#:tag "start-module-mode"]{Module Mode}
|
|
|
|
If a file argument is supplied to @exec{racket} before any
|
|
command-line switch (other than configuration options), then the file
|
|
is required as a module, and (unless @Flag{i}/@DFlag{repl} is
|
|
specified), no @tech{REPL} is started. For example,
|
|
|
|
@commandline{racket hello.rkt}
|
|
|
|
requires the @filepath{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
|
|
@racket[current-command-line-arguments].
|
|
|
|
If command-line flags are used, then the @Flag{u} or
|
|
@DFlag{require-script} flag can be used to explicitly require a file
|
|
as a module. The @Flag{t} or @DFlag{require} flag is similar, except
|
|
that additional command-line flags are processed by @exec{racket},
|
|
instead of preserved for the required module. For example,
|
|
|
|
@commandline{racket -t hello.rkt -t goodbye.rkt}
|
|
|
|
requires the @filepath{hello.rkt} module, then requires the
|
|
@filepath{goodbye.rkt} module, and then exits.
|
|
|
|
The @Flag{l} or @DFlag{lib} flag is similar to
|
|
@Flag{t}/@DFlag{require}, but it requires a module using a
|
|
@racket[lib] module path instead of a file path. For example,
|
|
|
|
@commandline{racket -l raco}
|
|
|
|
is the same as running the @exec{raco} executable with no arguments,
|
|
since the @racket[raco] module is the executable's main module.
|
|
|
|
Note that if you wanted to pass command-line flags to
|
|
@racket[raco] above, you would need to protect the flags with a
|
|
@Flag{-}, so that @exec{racket} doesn't try to parse them itself:
|
|
|
|
@commandline{racket -l raco -- --help}
|
|
|
|
@; ----------------------------------------
|
|
|
|
@subsection[#:tag "start-load-mode"]{Load Mode}
|
|
|
|
The @Flag{f} or @DFlag{load} flag supports @racket[load]ing top-level
|
|
expressions in a file directly, as opposed to expressions within a
|
|
module file. This evaluation is like starting a @tech{REPL} and typing
|
|
the expressions directly, except that the results are not printed.
|
|
For example,
|
|
|
|
@commandline{racket -f hi.rkts}
|
|
|
|
@racket[load]s @filepath{hi.rkts} and exits. Note that load mode is
|
|
generally a bad idea, for the reasons explained in
|
|
@secref["use-module"]; using module mode is typically better.
|
|
|
|
The @Flag{e} or @DFlag{eval} flag accepts an expression to evaluate
|
|
directly. Unlike file loading, the result of the expression is
|
|
printed, as in a @tech{REPL}. For example,
|
|
|
|
@commandline{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
|
|
@seclink["start-interactive-mode"]{interactive mode}:
|
|
@racketmodname[racket/init] is required unless another module is
|
|
specified first. For example,
|
|
|
|
@commandline{racket -l racket/base -e '(current-seconds)'}
|
|
|
|
likely runs faster, because it initializes the environment for
|
|
evaluation using the smaller @racketmodname[racket/base] language,
|
|
instead of @racketmodname[racket/init].
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@include-section["scripts.scrbl"]
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@section[#:tag "exe"]{Creating Stand-Alone Executables}
|
|
|
|
@(define raco-doc '(lib "scribblings/raco/raco.scrbl"))
|
|
|
|
For information on creating and distributing executables, see
|
|
@secref[#:doc raco-doc "exe"] and @secref[#:doc raco-doc "exe-dist"] in
|
|
@other-manual[raco-doc].
|