diff --git a/collects/scribblings/guide/chars.scrbl b/collects/scribblings/guide/chars.scrbl index 5ae61dbc14..e2106e0f5d 100644 --- a/collects/scribblings/guide/chars.scrbl +++ b/collects/scribblings/guide/chars.scrbl @@ -5,7 +5,7 @@ @title[#:tag "characters"]{Characters} -A Scheme @defterm{character} corresponds to a Unicode @defterm{scalar +A Scheme @deftech{character} corresponds to a Unicode @defterm{scalar value}. Roughly, a scalar value is an unsigned integer whose representation fits into 21 bits, and that maps to some notion of a natural-language character or piece of a character. Technically, a diff --git a/collects/scribblings/guide/compile.scrbl b/collects/scribblings/guide/compile.scrbl new file mode 100644 index 0000000000..c5a2b037da --- /dev/null +++ b/collects/scribblings/guide/compile.scrbl @@ -0,0 +1,60 @@ +#lang scribble/doc +@(require scribble/manual + "guide-utils.ss") + +@title[#:tag "compile"]{Compilation and Configuration} + +So far, we have talked about three main PLT Scheme executables: + +@itemize[ + + @item{DrScheme, which is the development environment.} + + @item{@exec{mzscheme}, which is the console-based virtual machine for + running PLT Scheme programs (and that can be used as a + development environment in interactive mode);} + + @item{@exec{mred}, which is like @scheme{mzscheme}, but for GUI + applications.} + +] + +Three more executables help in compiling PLT Scheme programs and in +maintaining a PLT Scheme installation: + +@itemize[ + + @item{@exec{mzc} is a command-line tool for miscellaneous tasks, such + as compiling Scheme source to bytecode, generating executables, and + building distribution packages, and compiling C-implemented + extensions to work with the run-time system. The @exec{mzc} is + described in @other-manual['(lib + "scribblings/mzc/mzc.scrbl")]. + + For example, if you have a program @filepath{take-over-world.ss} and + you'd like to compile it to bytecode, along with all of its + dependencies, so that it loads more quickly, then run + + @commandline{mzc take-over-the-world.ss}} + + @item{@exec{setup-plt} is a command-line tool for managing a PLT + Scheme installation, including manually installed packages. The + @exec{setup-plt} tool is described in @other-manual['(lib + "scribblings/setup-plt/setup-plt.scrbl")]. + + For example, if you create your own library @techlink{collection} + called @filepath{take-over}, and you'd like to build all bytecode and + documentation for the collection, then run + + @commandline{setup-plt -l take-over}} + + @item{@exec{planet} is a command-line tool for managing packages that + are normally downloaded automatically, on demand. The @exec{planet} + tool is described in @other-manual['(lib "planet/planet.scrbl")]. + + For example, if you'd like to see a list of @|PLaneT| packages that + are currently installed, then run + + @commandline{planet show}} + +] diff --git a/collects/scribblings/guide/guide.scrbl b/collects/scribblings/guide/guide.scrbl index bebb3f6b43..f2f858ba63 100644 --- a/collects/scribblings/guide/guide.scrbl +++ b/collects/scribblings/guide/guide.scrbl @@ -46,64 +46,21 @@ precise details to @|MzScheme| and other reference manuals. @include-section["unit.scrbl"] -@; ---------------------------------------------------------------------- -@section[#:tag "threads"]{Threads} - -@subsection[#:tag "parameters"]{Parameters} - -A @deftech{parameter} holds a kind of global option. For example, -there is a parameter that determines the default destination for -printed output. - -@; ---------------------------------------------------------------------- @include-section["namespaces.scrbl"] - -@; ---------------------------------------------------------------------- @include-section["macros.scrbl"] -@; ---------------------------------------------------------------------- -@section[#:tag "reader"]{Reader Extension} - -@; ---------------------------------------------------------------------- -@section[#:tag "security"]{Security} - - -@; ---------------------------------------------------------------------- -@section[#:tag "memory-management"]{Memory Management} - -@subsection[#:tag "weakboxes"]{Weak Boxes} - -@subsection[#:tag "ephemerons"]{Ephemerons} - -@; ---------------------------------------------------------------------- @include-section["performance.scrbl"] -@; ---------------------------------------------------------------------- @include-section["running.scrbl"] -@; ---------------------------------------------------------------------- -@section{Configuration and Compilation} - -@itemize{ - - @tool["setup-plt"]{a command-line tool for installation tasks} - - @tool["planet"]{a command-line tool for managing packages that are - normally downloaded automatically, on demand} - - @tool["mzc"]{a command-line tool for miscellaneous tasks, such as - compiling Scheme source, compiling C-implemented extensions to the - run-time system, generating executables, and building distribution - packages} - -} +@include-section["compile.scrbl"] @; ---------------------------------------------------------------------- @section{More Libraries} @other-manual['(lib "scribblings/gui/gui.scrbl")] describes the PLT -Scheme graphics toolbox, whose core is implemented by the MrEd +Scheme graphics toolbox, whose core is implemented by the @exec{mred} executable. @other-manual['(lib "scribblings/foreign/foreign.scrbl")] describes diff --git a/collects/scribblings/guide/hash-tables.scrbl b/collects/scribblings/guide/hash-tables.scrbl index 955f6184e9..99d44d37f0 100644 --- a/collects/scribblings/guide/hash-tables.scrbl +++ b/collects/scribblings/guide/hash-tables.scrbl @@ -55,9 +55,9 @@ mapping is retained only so long as the key is retained elsewhere. Beware that even a weak hash table retains its values strongly, as long as the corresponding key is accessible. This creates a catch-22 dependency when a value refers back to its key, so that the mapping is -retained permanently. To break the cycle, map the key to an -@seclink["ephemerons"]{ephemeron} that pairs the value with its key (in -addition to the implicit pairing of the hash table). +retained permanently. To break the cycle, map the key to an ephemeron +that pairs the value with its key (in addition to the implicit pairing +of the hash table). @examples[ (define ht (make-weak-hasheq)) diff --git a/collects/scribblings/guide/io.scrbl b/collects/scribblings/guide/io.scrbl index c5905e3f52..62b3e13692 100644 --- a/collects/scribblings/guide/io.scrbl +++ b/collects/scribblings/guide/io.scrbl @@ -188,10 +188,8 @@ stdout in purple, and output written to stderr in red italics. (swing-hammer) ] -The current-port functions are actually @tech{parameters}, which means -that their values can be set with @scheme[parameterize]. - -@moreguide["parameters"]{parameters} +The current-port functions are actually parameters, which means that +their values can be set with @scheme[parameterize]. @examples[ #:eval io-eval diff --git a/collects/scribblings/guide/module-set.scrbl b/collects/scribblings/guide/module-set.scrbl index dd318a0a6c..c81b0139a2 100644 --- a/collects/scribblings/guide/module-set.scrbl +++ b/collects/scribblings/guide/module-set.scrbl @@ -63,7 +63,7 @@ involves the re-definition of a previously immutable binding. ] For exploration and debugging purposes, the Scheme reflective layer -provides a @scheme[compile-enforce-module-constants] @tech{parameter} +provides a @scheme[compile-enforce-module-constants] parameter to disable the enforcement of constants. @interaction[ diff --git a/collects/scribblings/guide/performance.scrbl b/collects/scribblings/guide/performance.scrbl index c62094ee70..54543fc9f2 100644 --- a/collects/scribblings/guide/performance.scrbl +++ b/collects/scribblings/guide/performance.scrbl @@ -23,10 +23,13 @@ and memory performance of Scheme code. Every definition or expression to be evaluated by Scheme is compiled to an internal bytecode format. In interactive mode, this compilation -occurs automatically and on-the-fly. Tools like @exec{setup-plt} and -@scheme[compile-file] marshal compiled bytecode to a file. Most of the -time required to compile a file is actually in macro expansion; -generating bytecode from fully expanded code is relatively fast. +occurs automatically and on-the-fly. Tools like @exec{mzc} and +@exec{setup-plt} marshal compiled bytecode to a file, so that you do +not have to compile from source every time that you run a +program. (Most of the time required to compile a file is actually in +macro expansion; generating bytecode from fully expanded code is +relatively fast.) See @secref["compile"] for more information on +generating bytecode files. The bytecode compiler applies all standard optimizations, such as constant propagation, constant folding, inlining, and dead-code @@ -41,7 +44,7 @@ arithmetic on small integers, and arithmetic on inexact real numbers. Currently, @tech{JIT} compilation is supported for x86, x86_64 (a.k.a. AMD64), and 32-bit PowerPC processors. The @tech{JIT} compiler can be disabled via the @scheme[eval-jit-enabled] parameter -or the @DFlag{no-jit}/@Flag{j} command-line flag. +or the @DFlag{no-jit}/@Flag{j} command-line flag for @exec{mzscheme}. The @tech{JIT} compiler works incrementally as functions are applied, but the @tech{JIT} compiler makes only limited use of run-time diff --git a/collects/scribblings/guide/running.scrbl b/collects/scribblings/guide/running.scrbl index be521ab655..7fa46d5a3f 100644 --- a/collects/scribblings/guide/running.scrbl +++ b/collects/scribblings/guide/running.scrbl @@ -5,15 +5,23 @@ @title[#:tag "running" #:style 'toc]{Running and Creating Executables} +While developing programs, many PLT Scheme programmers use the +@seclink[#:doc '(lib "scribblings/drscheme/drscheme.scrbl") +"top"]{DrScheme} programming environment. To run a program without the +development environment, use @exec{mzscheme} (for console-based +programs) or @exec{mred} (for GUI program). This chapter mainly +explains how to run @exec{mzscheme} and @exec{mred}. + @local-table-of-contents[] @; ---------------------------------------------------------------------- -@section[#:tag "mzscheme"]{Running MzScheme and MrEd} +@section[#:tag "mzscheme"]{Running @exec{mzscheme} and @exec{mred}} -Depending on command-line arguments, MzScheme runs in -@seclink["start-interactive-mode"]{interactive mode}, -@seclink["start-module-mode"]{module mode}, or @seclink["start-load-mode"]{load mode}. +Depending on command-line arguments, @exec{mzscheme} or @exec{mred} +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} @@ -40,7 +48,7 @@ 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{mzscheme -e '(display "hi\n")' } +@commandline{mzscheme -e '(display "hi\n")' -i} displays ``hi'' on start-up, but still presents a @tech{REPL}. @@ -107,7 +115,14 @@ The @Flag{l} or @DFlag{lib} flag is similar to @commandline{mzscheme -l compiler} is the same as running the @exec{mzc} executable with no arguments, -since the @scheme[compiler] module is the main @exec{mzc} module. +since the @scheme[compiler] module is the main @exec{mzc} +module. + +Note that if you wanted to pass command-line flags to +@scheme[compiler] above, you would need to protect the flags with a +@Flag{-}, so that @exec{mzscheme} doesn't try to parse them itself: + +@commandline{mzscheme -l compiler -- --make prog.ss} @; ---------------------------------------- @@ -147,9 +162,13 @@ instead of @schememodname[scheme/init]. @; ---------------------------------------------------------------------- -@section[#:tag "exe"]{Creating Stand-Alone Executables} +@include-section["scripts.scrbl"] @; ---------------------------------------------------------------------- -@include-section["scripts.scrbl"] +@section[#:tag "exe"]{Creating Stand-Alone Executables} +@(define mzc-doc '(lib "scribblings/mzc/mzc.scrbl")) + +For information on creating and distributing executables, see +@secref[#:doc mzc-doc "sa"] in @other-manual[mzc-doc]. diff --git a/collects/scribblings/guide/scripts.scrbl b/collects/scribblings/guide/scripts.scrbl index 1db77d2468..087d8d474d 100644 --- a/collects/scribblings/guide/scripts.scrbl +++ b/collects/scribblings/guide/scripts.scrbl @@ -13,7 +13,7 @@ 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. -The simplest script format uses an absolute path to a MzScheme +The simplest script format uses an absolute path to a @exec{mzscheme} executable followed by a module declaration. For example, if @exec{mzscheme} is installed in @filepath{/usr/local/bin}, then a file containing the following text acts as a ``hello world'' script: diff --git a/collects/scribblings/guide/welcome.scrbl b/collects/scribblings/guide/welcome.scrbl index c61695cbd6..c11e185c04 100644 --- a/collects/scribblings/guide/welcome.scrbl +++ b/collects/scribblings/guide/welcome.scrbl @@ -170,6 +170,9 @@ options: @item{With Unix or Mac OS X, you can turn the program file into an executable script by inserting the line + @margin-note{See @secref["scripts"] for more information on + script files.} + @verbatim[#:indent 2]{#! /usr/bin/env mzscheme} at the very beginning of the file. Also, change the file diff --git a/collects/scribblings/mzc/exe.scrbl b/collects/scribblings/mzc/exe.scrbl index dbc6be2b1b..40de0947eb 100644 --- a/collects/scribblings/mzc/exe.scrbl +++ b/collects/scribblings/mzc/exe.scrbl @@ -5,12 +5,12 @@ @title[#:tag "exe"]{Stand-Alone Executables from Scheme Code} -The command-line flag @DFlag{exe} directs @|mzc| to embed a -module, from source or byte code, into a copy of the MzScheme +The command-line flag @DFlag{exe} directs @|mzc| to embed a module, +from source or byte code, into a copy of the @exec{mzscheme} executable. (Under Unix, the embedding executable is actually a copy of a wrapper executable.) The created executable invokes the embedded -module on startup. The @DFlag{gui-exe} flag is similar, but it -copies the MrEd executable. If the embedded module refers to other +module on startup. The @DFlag{gui-exe} flag is similar, but it copies +the @exec{mred} executable. If the embedded module refers to other modules via @scheme[require], then the other modules are also included in the embedding executable. @@ -20,7 +20,7 @@ For example, the command produces either @filepath{hello.exe} (Windows), @filepath{hello.app} (Mac OS X), or @filepath{hello} (Unix), which runs the same as -invoking the @filepath{hello.ss} module in MrEd. +invoking the @filepath{hello.ss} module in @exec{mred}. Library modules or other files that are referenced dynamically---through @scheme[eval], @scheme[load], or @@ -44,9 +44,9 @@ The @DFlag{exe} and @DFlag{gui-exe} flags work only with library provides a more general interface to the embedding mechanism. A stand-alone executable is ``stand-alone'' in the sense that you can -run it without starting MzScheme, MrEd, or DrScheme. However, the -executable depends on MzScheme and/or MrEd shared libraries, and -possibly other run-time files declared via +run it without starting @exec{mzscheme}, @exec{mred}, or +DrScheme. However, the executable depends on PLT Scheme shared +libraries, and possibly other run-time files declared via @scheme[define-runtime-path]. The executable can be packaged with support libraries to create a distribution, as described in @secref["exe-dist"]. diff --git a/collects/scribblings/mzc/sa.scrbl b/collects/scribblings/mzc/sa.scrbl index 2920210ea7..374b2d4c13 100644 --- a/collects/scribblings/mzc/sa.scrbl +++ b/collects/scribblings/mzc/sa.scrbl @@ -5,7 +5,7 @@ @title[#:tag "sa" #:style 'toc]{Creating and Distributing Stand-Alone Executables} Whether bytecode or native code, the compiled code produced by @|mzc| -relies on MzScheme (or MrEd) to provide run-time support to the +relies on PLT Scheme executables to provide run-time support to the compiled code. However, @|mzc| can also package code together with its run-time support to form a complete executable, and then the executable can be packaged into a distribution that works on other