suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

replace mzc and setup-plt docs with raco doc (which refers to the still-separate planet doc)

Browse Source
This commit is contained in:
Matthew Flatt 2010-05-02 11:04:48 -06:00
parent 6e42f95140
commit 166b92f9c8
43 changed files with 2326 additions and 2300 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
collects/make/make.scrbl
View File

@ -12,7 +12,7 @@
dynext/file-sig
compiler/sig))
@(define mzc-manual @other-manual['(lib "scribblings/mzc/mzc.scrbl")])
@(define raco-manual @other-manual['(lib "scribblings/raco/raco.scrbl")])
@title{@bold{Make}: Dependency Manager}
@ -27,8 +27,8 @@ syntax of @exec{make}, only in Scheme.
@section[#:tag "overview"]{Overview}
@margin-note{If you want to build Scheme modules with automatic
dependency tracking, just use @exec{mzc} as described in
@|mzc-manual|.}
dependency tracking, just use @exec{raco make} as described in
@|raco-manual|.}
If you are already familiar with @exec{make}, skip to the precise
details of the @schememodname[make] library in @secref["make"]. This
@ -238,8 +238,8 @@ A unit that imports nothing and exports @scheme[make^].}
The @schememodname[make/setup-extension] library helps compile C code
via Setup PLT's ``pre-install'' phase (triggered by a
@schemeidfont{pre-install-collection} item in @filepath{info.ss}; see
also @secref[#:doc '(lib "scribblings/setup-plt/setup-plt.scrbl")
@schemeidfont{pre-install-collection} item in @filepath{info.rkt}; see
also @secref[#:doc '(lib "scribblings/raco/raco.scrbl")
"setup-info"]).
The @scheme[pre-install] function takes a number of arguments that
@ -361,7 +361,7 @@ The arguments are as follows:
AIX-specific compile flag in this step when compiling under AIX.}
@item{@scheme[3m-too?]--- a boolean. If true, when the 3m variant is
installed, use the equivalent to @exec{mzc --xform} to transform
installed, use the equivalent to @exec{raco ctool --xform} to transform
the source file and then compile and link for 3m. Otherwise, the
extension is built only for CGC when the CGC variant is installed.}
@ -384,8 +384,8 @@ managing dependencies. Supply @scheme['#("zo")] as @scheme[argv] to
compile all files. The @scheme[collection-name] argument is used only
for printing status information.
Compilation is performed as with @exec{mzc --make} (see
@|mzc-manual|).}
Compilation is performed as with @exec{raco make} (see
@|raco-manual|).}
@subsection{Signature}

335
collects/planet/planet.scrbl
View File

@ -3,7 +3,7 @@
@(require scribble/manual
scribble/bnf
scribble/eval
(for-label scheme)
(for-label racket)
(for-label planet/config)
(for-label planet/util))
@ -20,9 +20,9 @@ The @PLaneT system is a method for automatically sharing code packages,
both as libraries and as full applications, that gives every user of a
@PLaneT client the illusion of having a local copy of every code
package on the server. It
consists of @link["http://planet.plt-scheme.org/"]{the central @PLaneT
consists of @link["http://planet.racket-lang.org/"]{the central @PLaneT
package repository}, a server that holds all PLaneT packages, and
the PLaneT client, built into PLT Scheme, which transparently
the PLaneT client, built into Racket, which transparently
interacts with the server on your behalf when necessary.
@table-of-contents[]
@ -30,41 +30,41 @@ interacts with the server on your behalf when necessary.
@section{Using PLaneT}
To use a @PLaneT package in a program, require it using the
@scheme[planet] @scheme[require] form (see @(secref "require" #:doc
@racket[planet] @racket[require] form (see @(secref "require" #:doc
'(lib "scribblings/reference/reference.scrbl")) for a full reference
on the features of the @scheme[require] statement in general and the
on the features of the @racket[require] statement in general and the
exact allowed grammar of PLaneT require statements). Here we explain
how to use PLaneT by example.
@subsection[#:tag "finding-a-package"]{Finding a Package}
If you are new to PLaneT, the first thing to do is visit
@link["http://planet.plt-scheme.org/"]{the PLaneT repository web site}
@link["http://planet.racket-lang.org/"]{the PLaneT repository web site}
and see what packages are available. People contribute new PLaneT
packages all the time --- if you want to be notified whenever a new or
updated package is released, you can subscribe to the
(announcement-only)
@link["http://mailman.cs.uchicago.edu/mailman/listinfo/planet-announce"]{PLaneT-announce mailing list}
or use an RSS reader to subscribe to
@link["http://planet.plt-scheme.org/300/planet.rss"]{PLaneT's RSS feed}.
@link["http://planet.racket-lang.org/300/planet.rss"]{PLaneT's RSS feed}.
To use a package from PLaneT in your program, the easiest thing to do
is copy the @scheme[require] code snippet off of that package's page
is copy the @racket[require] code snippet off of that package's page
and paste it ino your program. For instance, to use Schematics'
@link["http://planet.plt-scheme.org/users/schematics/spgsql.plt"]{spgsql.plt}
@link["http://planet.racket-lang.org/users/schematics/spgsql.plt"]{spgsql.plt}
package (a library for interacting with the
@link["http://www.postgresql.org/"]{PostgresQL} database), as of this
writing you would copy and paste the line:
@schemeblock[(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 3)))]
@racketblock[(require (planet "spgsql.rkt" ("schematics" "spgsql.plt" 2 3)))]
into your program. This line requires the file @filepath{spgsql.ss} in package
into your program. This line requires the file @filepath{spgsql.rkt} in package
version 2.3 of the @filepath{spgsql.plt} package written by
@filepath{schematics}. That does two things: first, it downloads and
installs a version of @filepath{spgsql.plt} that is compatible with
package version 2.3 from @link["http://planet.plt-scheme.org/"]{the
package version 2.3 from @link["http://planet.racket-lang.org/"]{the
central PLaneT repository} if a compatible version hasn't already been
installed. Second, it requires the module in file @filepath{spgsql.ss}
installed. Second, it requires the module in file @filepath{spgsql.rkt}
from that package, making all of its exported bindings available for use.
Unlike with most package-distribution systems, package downloading and
@ -76,17 +76,16 @@ will be deployed.
@subsection{Shorthand Syntax}
As of PLT Scheme version 4.0, the code snippet above can also be
written using a new shorter syntax:
The code snippet above can also be written using a new shorter syntax:
@schemeblock[(require (planet schematics/spgsql:2:3/spgsql))]
@racketblock[(require (planet schematics/spgsql:2:3/spgsql))]
The two forms behave identically. In the abbreviated syntax, however,
it is illegal to write the trailing @filepath{.ss} suffix on the file
it is illegal to write the trailing @filepath{.rkt} suffix on the file
name to be required or the trailing @filepath{.plt} on the package file
name. (They are mandatory for the long-form syntax.) It is also legal
in the abbreviated syntax to omit a filename to be required entirely;
in that case, PLaneT requires the file @filepath{main.ss} in the given
in that case, PLaneT requires the file @filepath{main.rkt} in the given
package.
@subsection{Networking troubles}
@ -94,15 +93,15 @@ package.
Sometimes, when PLaneT tries to download and install a
package for the first time, your operating system may block
it from access to the network. If you are uncomfortable
giving DrScheme free access to the network (or if your
giving DrRacket free access to the network (or if your
attempts to do so do not seem to work), then you can use
your browser to manually install a planet package.
To see how this works, lets assume you want to install the PLAI package
and @schemeblock[(require (planet plai/plai:1))] is not working for you.
and @racketblock[(require (planet plai/plai:1))] is not working for you.
@itemize[
@item{First,
fire up a command-line window and use @tt{planet url} to
fire up a command-line window and use @tt{raco planet url} to
determine the url for downloading the package.
To find the url for version @tt{(1 1)} of the plai package,
do this:
@ -111,7 +110,7 @@ do this:
and get this as a response:
@tt{http://planet.plt-scheme.org/servlets/planet-servlet.ss?lang=%224.1.5.3%22&name=%22plai.plt%22&maj=1&min-lo=1&min-hi=%23f&path=%28%22plai%22%29}}
@tt{http://planet.racket-lang.org/servlets/planet-servlet.rkt?lang=%224.1.5.3%22&name=%22plai.plt%22&maj=1&min-lo=1&min-hi=%23f&path=%28%22plai%22%29}}
@item{Copy and paste that url into your browser, which
should trigger the dowload of a file called
@ -130,7 +129,7 @@ repeat the above steps for that package first, and then
continue with the @tt{fileinject} command for PLAI.}
@item{Finally, to check that the installation is successful,
run @tt{planet show}. You should see output like this
run @tt{raco planet show}. You should see output like this
(possibly with slightly different version numbers, if the
packages have been updated since this was written):
@verbatim{
@ -141,7 +140,7 @@ Normally-installed packages:
]
Once that is complete, PLaneT will use that version of the
package for any subsequent @scheme[require]s and won't try
package for any subsequent @racket[require]s and won't try
to use the network.
@subsection{Fine-Grained Control Over Package Imports}
@ -159,11 +158,11 @@ number that encodes backwards-compatibility information.}
The most basic planet require line, which is what is used in the form
@schemeblock[(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 3)))]
@racketblock[(require (planet "spgsql.rkt" ("schematics" "spgsql.plt" 2 3)))]
in longhand notation, or
@schemeblock[(require (planet schematics/spgsql:2:3/spgsql))]
@racketblock[(require (planet schematics/spgsql:2:3/spgsql))]
in shorthand notation, should be read ``Require from PLaneT
@italic{any} release of Schematics' @filepath{spgsql.plt} package that
@ -172,11 +171,11 @@ package version used is determined by @seclink["search-order"]{the
PLaneT search order}.) To signal this explicitly, it is possible to
write
@schemeblock[(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 (+ 3))))]
@racketblock[(require (planet "spgsql.rkt" ("schematics" "spgsql.plt" 2 (+ 3))))]
or
@schemeblock[(require (planet schematics/spgsql:2:>=3/spgsql))]
@racketblock[(require (planet schematics/spgsql:2:>=3/spgsql))]
both of which mean the same thing as the first pair of require lines.
@ -199,12 +198,12 @@ in third-party libraries was already working around. In those cases,
it may help to make use of the ``upper bound'' form of the planet
require, in longhand form:
@schemeblock[(require (planet "reduction-semantics.ss"
@racketblock[(require (planet "reduction-semantics.rkt"
("robby" "redex.plt" 4 (- 3))))]
and using shorthand notation:
@schemeblock[(require (planet robby/redex:4:<=3/reduction-semantics))]
@racketblock[(require (planet robby/redex:4:<=3/reduction-semantics))]
In this require line, any version of the package @filepath{redex.plt}
from package version 4.0 to package version 4.3 will match the require
@ -215,11 +214,11 @@ which package is actually loaded).
It is also possible to specify both an upper and a lower bound, using
the planet require's ``range'' form:
@schemeblock[(require (planet "test.ss" ("schematics" "schemeunit.plt" 2 (9 10))))]
@racketblock[(require (planet "test.rkt" ("schematics" "schemeunit.plt" 2 (9 10))))]
or
@schemeblock[(require (planet schematics/schemeunit:2:9-10/test))]
@racketblock[(require (planet schematics/schemeunit:2:9-10/test))]
This form matches any package in the specified range (inclusive on
both ends), in this example the specifications match either package
@ -232,11 +231,11 @@ a package as a special case (choosing the upper and lower bounds to be
equal), but this is a common enough case that it has special support
with the ``exact-match'' form:
@schemeblock[(require (planet "unzip.ss" ("dherman" "zip.plt" 2 (= 1))))]
@racketblock[(require (planet "unzip.rkt" ("dherman" "zip.plt" 2 (= 1))))]
or
@schemeblock[(require (planet dherman/zip:2:=1/unzip))]
@racketblock[(require (planet dherman/zip:2:=1/unzip))]
match only the exact package version 2.1 of the @filepath{zip.plt} package.
@ -247,9 +246,9 @@ match only the exact package version 2.1 of the @filepath{zip.plt} package.
@subsection{Monitoring PLaneT's progress}
PLaneT logs information about what it is doing to the @tt{info}
log (via @scheme[log-info]).
In DrScheme, you can view the logs from the @onscreen{Show Log}
menu item in the @onscreen{View} menu, and MzScheme's logging output
log (via @racket[log-info]).
In DrRacket, you can view the logs from the @onscreen{Show Log}
menu item in the @onscreen{View} menu, and Racket's logging output
can be controlled via command-line options and via environment
variables. See
@secref["logging" #:doc '(lib "scribblings/reference/reference.scrbl")]
@ -292,22 +291,22 @@ it to satisfy the original requirement.
If the remote server cannot be contacted (or fails in any way to
deliver an acceptable package), the PLaneT client consults the
uninstalled-packages cache, a cache of all previously-downloaded
packages, even those that are not currently installed. PLT Scheme
packages, even those that are not currently installed. Racket
users who frequently upgrade their installations may have many
packages downloaded but not installed at any given time; this step
is intended to ensure that these users can still run programs even
if they temporarily lose network connection.
@section[#:tag "cmdline"]{The @exec{planet} Command-Line Tool}
@section[#:tag "cmdline"]{The @exec{raco planet} Command-Line Tool}
The @exec{planet} command-line tool allows a command-line interface to
The @exec{raco planet} command-line tool allows a command-line interface to
the most commonly-performed PLaneT tasks. It is invoked from the
command line as
@commandline{planet @italic{subcommand} arg ...}
@commandline{raco planet @italic{subcommand} @italic{arg} ...}
where @italic{command} is a subcommand from the following list, and
@exec{arg} is a sequence of arguments determined by that subcommand:
where @italic{subcommand} is a subcommand from the following list, and
@exec{@italic{arg}} is a sequence of arguments determined by that subcommand:
@(define (cmd name desc)
@item{@(seclink name (exec name)): @desc})
@ -329,31 +328,31 @@ where @italic{command} is a subcommand from the following list, and
Each of these commands is described in more detail below. All the
functionality of the command-line tool is also provided with a programmatic interface by
@seclink["util.ss"]{the @filepath{util.ss} library}.
@seclink["util.rkt"]{the @filepath{util.rkt} library}.
@subsection[#:tag "create"]{@exec{create}}
Usage:
@commandline{planet create [ <option> ... ] <path>}
@commandline{raco planet create [ <option> ... ] <path>}
Create a PLaneT archive in the current directory whose contents are the
directory @exec{<path>}.
@exec{<option>} is one of:
@itemize[
@item{@exec{-f, --force}: force a package to be created even if its info.ss file contains
@item{@exec{-f, --force}: force a package to be created even if its info.rkt file contains
errors.}]
@subsection[#:tag "install"]{@exec{install}}
Usage:
@commandline{planet install <owner> <pkg> <maj> <min>}
Download and install the package that @scheme[(require (planet "file.ss" (<owner> <pkg> <maj> <min>)))]
@commandline{raco planet install <owner> <pkg> <maj> <min>}
Download and install the package that @racket[(require (planet "file.rkt" (<owner> <pkg> <maj> <min>)))]
would install.
@subsection[#:tag "remove"]{@exec{remove}}
Usage:
@commandline{planet remove [ <option> ... ] <owner> <pkg> <maj> <min>}
@commandline{raco planet remove [ <option> ... ] <owner> <pkg> <maj> <min>}
Remove the specified package from the local cache, optionally also removing its
distribution file.
@ -365,7 +364,7 @@ distribution file.
@subsection[#:tag "show"]{@exec{show}}
Usage:
@commandline{planet show [ <option> ... ]}
@commandline{raco planet show [ <option> ... ]}
List the packages installed in the local cache.
@exec{<option>} is one of:
@ -377,13 +376,13 @@ List the packages installed in the local cache.
@subsection[#:tag "clearlinks"]{@exec{clearlinks}}
Usage:
@commandline{planet clearlinks}
@commandline{raco planet clearlinks}
Clear the linkage table, allowing upgrades.
@subsection[#:tag "fileinject"]{@exec{fileinject}}
Usage:
@commandline{planet fileinject <owner> <plt-file> <maj> <min>}
@commandline{raco planet fileinject <owner> <plt-file> <maj> <min>}
Install local file <plt-file> into the planet cache as though it had been
downloaded from the planet server. It is treated as though it had the given owner name as its owner name,
the given file's filename as the its package name, and the given major and minor version numbers.
@ -391,27 +390,27 @@ the given file's filename as the its package name, and the given major and minor
@subsection[#:tag "link"]{@exec{link}}
Usage:
@commandline{planet link <owner> <pkg> <maj> <min> <path>}
@commandline{raco planet link <owner> <pkg> <maj> <min> <path>}
Create a development link (see @secref{devlinks}) between the given
package specifier and the specified directory name.
@subsection[#:tag "unlink"]{@exec{unlink}}
Usage:
@commandline{planet unlink <owner> <pkg> <maj> <min>}
@commandline{raco planet unlink <owner> <pkg> <maj> <min>}
Remove any development link (see @secref{devlinks}) associated with
the given package.
@subsection[#:tag "fetch"]{@exec{fetch}}
Usage:
@commandline{planet fetch <owner> <pkg> <maj> <min>}
@commandline{raco planet fetch <owner> <pkg> <maj> <min>}
Download the given package file from the central PLaneT repository without installing it.
@subsection[#:tag "url"]{@exec{url}}
Usage:
@commandline{planet url <owner> <pkg> <maj> <min>}
@commandline{raco planet url <owner> <pkg> <maj> <min>}
Get a URL for the given package.
This is never necessary for normal use of planet, but may be helpful in some
@ -420,7 +419,7 @@ circumstances for retrieving packages.
@subsection[#:tag "open"]{@exec{open}}
Usage:
@commandline{planet open <plt-file> <target>}
@commandline{raco planet open <plt-file> <target>}
Unpack the contents of the given package into the given directory without
installing.
@ -430,7 +429,7 @@ you to inspect package contents offline without needing to install the package.
@subsection[#:tag "structure"]{@exec{structure}}
Usage:
@commandline{planet structure <plt-file>}
@commandline{raco planet structure <plt-file>}
Print the structure of the PLaneT archive named by <plt-file> to the standard
output port.
@ -439,25 +438,25 @@ This command does not unpack or install the named .plt file.
@subsection[#:tag "print"]{@exec{print}}
Usage:
@commandline{planet print <plt-file> <path>}
@commandline{raco planet print <plt-file> <path>}
Print the contents of the file named by <path>, which must be a relative path
within the PLaneT archive named by <plt-file>, to the standard output port.
This command does not unpack or install the named .plt file.
@section[#:tag "hash-lang-planet"]{The @schememodname[planet] Language}
@section[#:tag "hash-lang-planet"]{The @racketmodname[planet] Language}
@defmodulelang[planet]
When used with @hash-lang[], @schememodname[planet] must be followed
When used with @hash-lang[], @racketmodname[planet] must be followed
by a short-form PLaneT path. The path is used in the same way that
@hash-lang[] uses plain identifiers: @schemeidfont{/lang/reader} is
@hash-lang[] uses plain identifiers: @racketidfont{/lang/reader} is
added to the given path to determine a module that supplies a module
reader.
The @schememodname[planet] module (as opposed to the reader used with
@hash-lang[]) implements the @exec{planet} command-line tool.
The @racketmodname[planet] module (as opposed to the reader used with
@hash-lang[]) implements the @exec{raco planet} command-line tool.
@section{Utility Libraries}
@ -467,23 +466,23 @@ The planet collection provides configuration and utilities for using PLaneT.
@defmodule[planet/resolver]
The primary purpose of this library to for @scheme[require] to find
The primary purpose of this library to for @racket[require] to find
@PLaneT packages. It also, however, provides some utilities for manipulating
the resolvers behavior.
@defproc[(resolve-planet-path [planet-path any/c]) path?]{
Returns the path where the file named by the require spec @scheme[planet-path] is located in the current installation.
Returns the path where the file named by the require spec @racket[planet-path] is located in the current installation.
}
@defparam[download? dl? boolean?]{
A parameter that controls if @PLaneT attempts to download a planet package that isn't already present.
If the package isn't present, the resolver will raise the @scheme[exn:fail:planet?] exception
If the package isn't present, the resolver will raise the @racket[exn:fail:planet?] exception
instead of downloading it.
}
@defparam[install? inst? boolean?]{
A parameter that controls if @PLaneT attempts to install a planet package that isn't already installed.
If the package isn't installed, the resolver will raise the @scheme[exn:fail:planet?] exception
If the package isn't installed, the resolver will raise the @racket[exn:fail:planet?] exception
instead of installing it.
}
@ -491,20 +490,20 @@ the resolvers behavior.
@defmodule[planet/config]
The @schememodname[planet/config] library provides several parameters
The @racketmodname[planet/config] library provides several parameters
useful for configuring how PLaneT works.
Note that while these parameters can be useful to modify
programmatically, PLaneT code runs at module-expansion time, so
most user programs cannot set them until PLaneT has already
run. Therefore, to meaningfully change these settings, it is best to
manually edit the config.ss file.
manually edit the config.rkt file.
@defparam[PLANET-DIR dir path-string?]{
The root PLaneT directory. If the environment variable
@indexed-envvar{PLTPLANETDIR} is
set, default is its value; otherwise the default is the directory in
which @filepath{config.ss} is found.}
which @filepath{config.rkt} is found.}
@defparam[CACHE-DIR dir path-string?]{
The root of the PLaneT client's cache directory.}
@ -514,12 +513,12 @@ The root of the PLaneT client's uninstalled-packages cache. PLaneT
stores package distribution files in this directory, and searches for
them in this directory for them if necessary. Unlike the main PLaneT
cache, which contains compiled files and is specific to each
particular version of PLT Scheme, the uninstalled package cache is
shared by all versions of PLT Scheme that use the same package
particular version of Racket, the uninstalled package cache is
shared by all versions of Racket that use the same package
repository, and it is searched if a package is not installed in the
primary cache and cannot be downloaded from the central PLaneT repository
(for instance due to a loss of Internet connectivity). This behavior
is intended to primarily benefit users who upgrade their PLT Scheme
is intended to primarily benefit users who upgrade their Racket
installations frequently.}
@defparam[LINKAGE-FILE file path-string?]{
@ -530,41 +529,41 @@ occur after a package is installed. The default is the file @filepath{LINKAGE}
in the root PLaneT directory.}
@defparam[LOG-FILE file (or/c path-string? false?)]{
If @scheme[#f], indicates that no logging should take place. Otherwise
If @racket[#f], indicates that no logging should take place. Otherwise
specifies the file into which logging should be written. The default
is the file @filepath{INSTALL-LOG} in the root PLaneT directory.}
@defboolparam[USE-HTTP-DOWNLOADS? bool]{
PLaneT can use two different protocols to retrieve packages. If @scheme[#t],
PLaneT will use the HTTP protocol; if @scheme[#f] it will use the custom-built
PLaneT protocol. The default value for this parameter is @scheme[#t] and setting
this parameter to @scheme[#f] is not recommended.}
PLaneT can use two different protocols to retrieve packages. If @racket[#t],
PLaneT will use the HTTP protocol; if @racket[#f] it will use the custom-built
PLaneT protocol. The default value for this parameter is @racket[#t] and setting
this parameter to @racket[#f] is not recommended.}
@defparam[HTTP-DOWNLOAD-SERVLET-URL url string?]{
The URL for the servlet that will provide PLaneT packages if
@scheme[USE-HTTP-DOWNLOADS?] is @scheme[#t], represented as a string.
@racket[USE-HTTP-DOWNLOADS?] is @racket[#t], represented as a string.
This defaults to the value of the @indexed-envvar{PLTPLANETURL} environment
variable if it is set and otherwise is
@scheme["http://planet.plt-scheme.org/servlets/planet-servlet.ss"].}
@racket["http://planet.racket-lang.org/servlets/planet-servlet.rkt"].}
@defparam[PLANET-SERVER-NAME host string?]{
The name of the PLaneT server to which the client should connect if
@scheme[USE-HTTP-DOWNLOADS?] is @scheme[#f]. The default value for this parameter is
@scheme["planet.plt-scheme.org"].}
@racket[USE-HTTP-DOWNLOADS?] is @racket[#f]. The default value for this parameter is
@racket["planet.racket-lang.org"].}
@defparam[PLANET-SERVER-PORT port natural-number?]{
The port on the server the client should connect to if
@scheme[USE-HTTP-DOWNLOADS?] is @scheme[#f]. The default value for this parameter is
@scheme[270].}
@racket[USE-HTTP-DOWNLOADS?] is @racket[#f]. The default value for this parameter is
@racket[270].}
@subsection[#:tag "util.ss"]{Utilities}
@subsection[#:tag "util.rkt"]{Utilities}
@defmodule[planet/util]
The @schememodname[planet/util] library supports examination of the pieces of
The @racketmodname[planet/util] library supports examination of the pieces of
PLaneT. It is meant primarily to support debugging and to allow easier
development of higher-level package-management tools. The
functionality exposed by @seclink["cmdline"]{the @exec{planet} command-line tool} is
functionality exposed by @seclink["cmdline"]{the @exec{raco planet} command-line tool} is
also available programmatically through this library.
@defproc[(download/install-pkg [owner string?]
@ -624,13 +623,13 @@ Removes the specified package from the local planet cache.}
@defproc[(display-plt-file-structure [plt-file (or/c path-string? path?)])
any]{
Print a tree representing the file and directory structure of the
PLaneT archive .plt file named by @scheme[plt-file] to @scheme[(current-output-port)].}
PLaneT archive .plt file named by @racket[plt-file] to @racket[(current-output-port)].}
@defproc[(display-plt-archived-file [plt-file (or/c path-string? path?)]
[file-to-print string?])
any]{
Print the contents of the file named @scheme[file-to-print] within the
PLaneT archive .plt file named by @scheme[plt-file] to @scheme[(current-output-port)].}
Print the contents of the file named @racket[file-to-print] within the
PLaneT archive .plt file named by @racket[plt-file] to @racket[(current-output-port)].}
@defproc[(unlink-all) any]{
Removes the entire linkage table from the system, which will force all
@ -675,16 +674,16 @@ file within it actually exists.}
)]{
Macros that expand into expressions that evaluate to information about
the name, owner, and version number of the package in which they
appear. @scheme[this-package-version] returns a list consisting of a string
appear. @racket[this-package-version] returns a list consisting of a string
naming the package's owner, a string naming the package, a number
indicating the package major version and a number indicating the
package minor version, or @scheme[#f] if the expression appears outside the
package minor version, or @racket[#f] if the expression appears outside the
context of a package. The others are convenience macros that
select out the relevant field, or return @scheme[#f] if the expression
select out the relevant field, or return @racket[#f] if the expression
appears outside the context of a PLaneT package.}
@defproc[(exn:fail:planet? [val any/c]) boolean?]{
Returns @scheme[#t] if @scheme[val] is
Returns @racket[#t] if @racket[val] is
}
@subsection{Terse Status Updates}
@ -693,19 +692,19 @@ appears outside the context of a PLaneT package.}
This module provides access to some PLaneT status information. This
module is first loaded by PLaneT in the initial namespace (when
PLaneT's resolver is loaded), but PLaneT uses @scheme[dynamic-require] to load
PLaneT's resolver is loaded), but PLaneT uses @racket[dynamic-require] to load
this module each time it wants to announce information. Similarly, the
state of which procedures are registered (via @scheme[planet-terse-register])
state of which procedures are registered (via @racket[planet-terse-register])
is saved in the namespace, making the listening and information producing
namespace-specific.
@defproc[(planet-terse-register
[proc (-> (or/c 'download 'install 'finish) string? any/c)]
[namespace namespace? (current-namespace)]) void?]{
Registers @scheme[proc] as a function to be called when
@scheme[planet-terse-log] is called with a matching namespace argument.
Note that @scheme[proc] is called
asynchronously (ie, on some thread other than the one calling @scheme[planet-terse-register]).
Registers @racket[proc] as a function to be called when
@racket[planet-terse-log] is called with a matching namespace argument.
Note that @racket[proc] is called
asynchronously (ie, on some thread other than the one calling @racket[planet-terse-register]).
}
@defproc[(planet-terse-log [id (or/c 'download 'install 'finish)]
@ -726,18 +725,18 @@ PLaneT can distribute whatever programs you write, but keep
these guidelines in mind as you write:
@itemize[
@item{Organize your code into modules. Since the PLaneT client is
integrated into the @scheme[require] form, it works best if your code
integrated into the @racket[require] form, it works best if your code
is arranged into modules.}
@item{When one module in your program depends on another, it is best
to require it using the relative-file-name form rather than the
planet require form. For instance, if your program contains files
primary.ss and helper.ss where primary.ss requires helper, use the form
primary.rkt and helper.rkt where primary.rkt requires helper, use the form
@scheme[(require "helper.ss")]
@racket[(require "helper.rkt")]
instead of
@scheme[(require (planet "helper.ss" ("username" "packagename.plt" 1 0)))]
@racket[(require (planet "helper.rkt" ("username" "packagename.plt" 1 0)))]
in files that will also be a part of the package.}]
@ -747,7 +746,7 @@ To aid development, PLaneT allows users to establish direct
associations between a particular planet package
with an arbitrary directory on the filesystem, for instance connecting the package named by the require line
@scheme[(require (planet "file.ss" ("my" "mypackage.plt" 1 0)))]
@racket[(require (planet "file.rkt" ("my" "mypackage.plt" 1 0)))]
to the directory @filepath{/home/myname/svn/mypackages/devel/}.
@ -755,20 +754,20 @@ These associations are intended to allow developers to use their own
directory structures, version control systems, and so on while still
being able to use the packages they create as though they were
distributed directly by PLaneT. Development links are local to a
particular user and repository (but not to a particular MzScheme minor
particular user and repository (but not to a particular Racket minor
revision).
To establish a development link, use the @exec{planet} command-line tool:
To establish a development link, use the @exec{raco planet} command-line tool:
@commandline{planet link myname mypackage.plt 1 0 ~/svn/mypackages/devel}
@commandline{raco planet link myname mypackage.plt 1 0 ~/svn/mypackages/devel}
Once you are finished developing a package, you should remove any
development links you have established for it, again using the planet
command-line tool:
@commandline{planet unlink myname mypackage.plt 1 0}
@commandline{raco planet unlink myname mypackage.plt 1 0}
You may alternately use the functions @scheme[add-hard-link] and @scheme[remove-hard-link].
You may alternately use the functions @racket[add-hard-link] and @racket[remove-hard-link].
@subsection{Prepare Your Distribution}
@ -787,56 +786,56 @@ Use Scribble to write documentation for your package. See
@other-manual['(lib "scribblings/scribble/scribble.scrbl")]
for instructions on how to write Scribble documentation.
@subsubsection{Create an @filepath{info.ss} File [Optional]}
@subsubsection{Create an @filepath{info.rkt} File [Optional]}
If you put a file named @filepath{info.ss} in your package's root directory, the
PLaneT system (as well as the rest of the PLT Scheme tool suite) will
If you put a file named @filepath{info.rkt} in your package's root directory, the
PLaneT system (as well as the rest of the Racket tool suite) will
look in it for descriptive metadata about your package. The PLaneT
system looks for certain names in that file:
@itemize[
@item{The @indexed-scheme['blurb] field: If present, the blurb field
@item{The @indexed-racket['blurb] field: If present, the blurb field
should contain a list of XHTML fragments encoded as x-expressions (see
the xml collection for details) that PLaneT will use as a short
description of your project.}
@item{The @indexed-scheme['release-notes] field: If present, the
@item{The @indexed-racket['release-notes] field: If present, the
release-notes field should contain a list of XHTML fragments encoded
as x-expressions (see the xml collection for details) that PLaneT will
use as a short description of what's new in this release of your
package.}
@item{The @indexed-scheme['categories] field: If present, the categories
@item{The @indexed-racket['categories] field: If present, the categories
field should be a list of symbols corresponding to the categories
under which this package should be listed.
The valid categories are:
@itemize[
@item{@indexed-scheme['devtools]: Development Tools}
@item{@indexed-scheme['net]: Networking and Protocols}
@item{@indexed-scheme['media]: Graphics and Audio}
@item{@indexed-scheme['xml]: XML-Related}
@item{@indexed-scheme['datastructures]: Data Structures and Algorithms}
@item{@indexed-scheme['io]: Input/Output and Filesystem}
@item{@indexed-scheme['scientific]: Mathematical and Scientific}
@item{@indexed-scheme['system]: Hardware/Operating System-Specific Tools}
@item{@indexed-scheme['ui]: Textual and Graphical User Interface}
@item{@indexed-scheme['metaprogramming]: Metaprogramming Tools}
@item{@indexed-scheme['planet]: PLaneT-Related}
@item{@indexed-scheme['misc]: Miscellaneous}]
@item{@indexed-racket['devtools]: Development Tools}
@item{@indexed-racket['net]: Networking and Protocols}
@item{@indexed-racket['media]: Graphics and Audio}
@item{@indexed-racket['xml]: XML-Related}
@item{@indexed-racket['datastructures]: Data Structures and Algorithms}
@item{@indexed-racket['io]: Input/Output and Filesystem}
@item{@indexed-racket['scientific]: Mathematical and Scientific}
@item{@indexed-racket['system]: Hardware/Operating System-Specific Tools}
@item{@indexed-racket['ui]: Textual and Graphical User Interface}
@item{@indexed-racket['metaprogramming]: Metaprogramming Tools}
@item{@indexed-racket['planet]: PLaneT-Related}
@item{@indexed-racket['misc]: Miscellaneous}]
If you put symbols other than these the categories field, they will be
ignored. If you put no legal symbols in the categories field or do not
include this field in your info.ss file, your package will be
include this field in your info.rkt file, your package will be
categorized as "Miscellaneous."}
@item{The @indexed-scheme['can-be-loaded-with] field:
@item{The @indexed-racket['can-be-loaded-with] field:
If present, the can-be-loaded-with field should be a quoted datum of
one of the following forms:
@schemegrammar[
@racketgrammar[
can-be-loaded-with 'all
'none
(list 'all-except VER-SPEC ...)
@ -851,12 +850,12 @@ particular file and assumes that nothing else writes to that same
file, then multiple versions of the same package being loaded
simultaneously may be a problem. This field allows you to specify
whether your package can be loaded simultaneously with older versions
of itself. If its value is @indexed-scheme['all], then the package may be
loaded with any older version. If it is @indexed-scheme['none], then it
may not be loaded with older versions at all. If it is @scheme[(list
of itself. If its value is @indexed-racket['all], then the package may be
loaded with any older version. If it is @indexed-racket['none], then it
may not be loaded with older versions at all. If it is @racket[(list
'all-except VER-SPEC ...)] then any package except those that match
one of the given VER-SPEC forms may be loaded with this package; if it
is @scheme[(list 'only VER-SPEC ...)] then only packages that match
is @racket[(list 'only VER-SPEC ...)] then only packages that match
one of the given VER-SPEC forms may be loaded with this package.
When checking to see if a package may be loaded, PLaneT compares it to
@ -866,18 +865,18 @@ can-be-loaded-with field allows the older package to be loaded. If all
such comparisons succeed then the new package may be loaded; otherwise
PLaneT signals an error.
The default for this field is @indexed-scheme['none] as a conservative
The default for this field is @indexed-racket['none] as a conservative
protection measure. For many packages it is safe to set this field to
@indexed-scheme['any].}
@indexed-racket['any].}
@item{The @indexed-scheme['homepage] field:
@item{The @indexed-racket['homepage] field:
If present, the URL field should be a string corresponding to a URL
for the package. PLaneT provides this link with the description of your
package on the main PLaneT web page.}
@item{The @indexed-scheme['primary-file] field:
@item{The @indexed-racket['primary-file] field:
If present, the primary-file field should be a either a string
corresponding to the name (without path) of the main Scheme source
corresponding to the name (without path) of the main Racket source
file of your package, or a list of such strings. The PLaneT web page
corresponding to this package will present all files listed here as
interface files for your package; it will give direct links to each
@ -888,29 +887,29 @@ If you include only a single string, it will be used as the require
line printed on your package's page. If you include a list of strings,
then the first legal file string in the list will be used.}
@item{The @indexed-scheme['required-core-version] field: If present, the
@item{The @indexed-racket['required-core-version] field: If present, the
required-core-version field should be a string with the same syntax as
the output of the @scheme[version] function. Defining this field
indicates that PLaneT should only allow users of a version of mzscheme
the output of the @racket[version] function. Defining this field
indicates that PLaneT should only allow users of a version of Racket
equal to or more recent than the version specified by this field. This
allows you finer-grained control of your package's core-language
requirements than its inclusion in a particular repository; for
instance, setting this field to @scheme["300.2"] would cause the PLaneT server
not to serve it to MzScheme v300.1 or older clients.}
instance, setting this field to @racket["300.2"] would cause the PLaneT server
not to serve it to Racket v300.1 or older clients.}
@item{The @indexed-scheme['version] field:
@item{The @indexed-racket['version] field:
If present, the version field should be a string that describes the
version number of this code that should be presented to users (e.g.,
@scheme["0.15 alpha"]). This field does not override or in any way interact
@racket["0.15 alpha"]). This field does not override or in any way interact
with your package's package version number, which is assigned by
PLaneT, but may be useful to users.}
@item{The @indexed-scheme['repositories] field: If present, the repositories
@item{The @indexed-racket['repositories] field: If present, the repositories
field should be a list consisting of some subset of the strings
@scheme["4.x"] and @scheme["3xx"]. The string @scheme["4.x"] indicates
@racket["4.x"] and @racket["3xx"]. The string @racket["4.x"] indicates
that this package should be included in the v4.x repository (which
contains packages that are intended to run in PLT Scheme versions at
or above version 4.0), and the string @scheme["3xx"] indicates that
contains packages that are intended to run in Racket and PLT Scheme versions at
or above version 4.0), and the string @racket["3xx"] indicates that
the package should be included in the v3xx repository (containing
packages intended to run in PLT Scheme versions in the 3xx series). A
single package (and a single version of a package) may be included in
@ -918,58 +917,58 @@ multiple repositories with the same PLaneT version number.}]
In addition, PLaneT uses the setup-plt installer to install packages
on client machines, so most fields it looks for can be included with
their usual effects. In particular, adding a @indexed-scheme['name]
field indicates that the Scheme files in the package should be
their usual effects. In particular, adding a @indexed-racket['name]
field indicates that the Racket files in the package should be
compiled during installation; it is a good idea to add it.
An example info.ss file looks like this:
An example info.rkt file looks like this:
@schememod[
@racketmod[
setup/infotab
(define name "My Application")
(define blurb
'("My application runs 60% faster on 20% less peanut "
"butter. It even shows a fancy graphic!"))
(define primary-file "my-app.ss")
(define primary-file "my-app.rkt")
(define categories '(system xml))
]
See the PLT mzc: MzScheme Compiler Manual, chapter 7 for more
information on info.ss files.
See @secref[#:doc '(lib "scribblings/raco/raco.scrbl") "info.rkt"]
for more information on @filepath{info.rkt} files.
@subsection{Build a Distribution Archive}
Use the planet command-line tool in its archive-creation mode to
create a planet archive:
@commandline{planet create /home/jacob/my-app/}
@commandline{raco planet create /home/jacob/my-app/}
This will create a planet archive named @filepath{my-app.plt} in the current
directory whose contents are the contents of @filepath{/home/jacobm/my-app} and
all its subdirectories.
Alternately, you can run @scheme[make-planet-archive] with the name of the directory
Alternately, you can run @racket[make-planet-archive] with the name of the directory
you've prepared as its argument:
@scheme[(make-planet-archive "/home/jacob/my-app/")]
@racket[(make-planet-archive "/home/jacob/my-app/")]
This function will build a packaged version of your directory and
return the path to that package. The path will always be a file named
@filepath{X.plt}, where @filepath{X} is the name of the directory you
gave to @scheme[make-planet-archive], located in that same directory.
gave to @racket[make-planet-archive], located in that same directory.
You can now test that your archive file works as intended using the
planet command-line tool in its install mode:
@commandline{planet fileinject <owner> <path to your .plt file> <maj> <min>}
@commandline{raco planet fileinject <owner> <path to your .plt file> <maj> <min>}
installs the specified file into your local PLaneT cache as
though it had been downloaded from the PLaneT server with the given
owner name and major and minor versions. After you run this command,
you can require your package on your local machine using
@scheme[(require (planet <file> (<owner> <.plt file name without path> <maj> <min>)))]
@racket[(require (planet <file> (<owner> <.plt file name without path> <maj> <min>)))]
to verify everything works. After you do so, you can use
@commandline{planet remove <owner> <.plt file name without path> <maj> <min>}
@commandline{raco planet remove <owner> <.plt file name without path> <maj> <min>}
to remove the test package from your local cache. (Not removing it is
safe as long as you use the same name and version numbers the package
will have on the PLaneT server; otherwise you may experience
@ -984,7 +983,7 @@ previously-released version of your package should unmodified with the
new package. This means that at a minimum, a backwards compatible
update should:
@itemize[
@item{Contain all the same Scheme source files in that the previous
@item{Contain all the same Racket source files in that the previous
version contained in directories intended for public access}
@item{In each public file, provide at least all the bindings that the
previous version provided}
@ -1011,7 +1010,7 @@ best judgment.
@subsection{Submit Your Package}
Go to @link["http://planet.plt-scheme.org/"]{the central PLaneT
Go to @link["http://planet.racket-lang.org/"]{the central PLaneT
package repository web page} and click on the link marked "contribute
a package / log in" in the upper-right-hand corner. If you have not
yet created an account, then do so on that page by providing your

2
collects/r5rs/r5rs.scrbl
View File

@ -19,7 +19,7 @@
@(define r5rs @elem{R@superscript{5}RS})
@(define drs-doc '(lib "scribblings/drscheme/drscheme.scrbl"))
@title{@bold{R5RS}: Legacy Standard Language}
@title{@bold{R5RS}: Legacy Scheme}
The @link["../r5rs-std/index.html"]{The Revised@superscript{5} Report
on the Algorithmic Language Scheme} defines a dialect of Scheme. We

194
collects/r6rs/scribblings/r6rs.scrbl
View File

@ -11,7 +11,7 @@
rnrs/r5rs-6
rnrs/hashtables-6
r6rs
(only-in scheme/base
(only-in racket/base
lib
current-library-collection-paths
parameterize
@ -23,7 +23,7 @@
@(define r6rs @elem{R@superscript{6}RS})
@(define r5rs @elem{R@superscript{5}RS})
@title{@bold{R6RS}: Standard Language}
@title{@bold{R6RS}: Scheme}
The @link["../r6rs-std/index.html"]{The Revised@superscript{6} Report
on the Algorithmic Language Scheme} defines a dialect of Scheme. We
@ -32,13 +32,13 @@ defined by the standard.
@margin-note{See @seclink[#:doc '(lib "scribblings/guide/guide.scrbl")
"dialects"] for general information about different
dialects of Scheme within PLT Scheme.}
dialects of Scheme within Racket.}
@|r6rs| defines both @defterm{libraries} and @defterm{top-level
programs}. Both correspond to PLT Scheme @defterm{modules} (see
programs}. Both correspond to Rackey @defterm{modules} (see
@secref[#:doc guide-src "modules"]). That is, although @|r6rs| defines
top-level programs as entry points, you can just as easily treat a
library as an entry point when using PLT Scheme. The only difference
library as an entry point when using Racket. The only difference
is that an @|r6rs| top-level program cannot export any bindings to
other modules.
@ -59,7 +59,7 @@ To run a top-level program, either:
Additional command-line arguments are propagated as
command-line arguments to the program (accessed via
@scheme[command-line]).
@racket[command-line]).
To compile the file to bytecode (to speed future runs of the
program), use @exec{plt-r6rs} with the @DFlag{compile} flag:
@ -69,47 +69,47 @@ To run a top-level program, either:
The bytecode file is written in a @filepath{compiled}
sub-directory next to @nonterm{program-file}.
For example, if @filepath{hi.scm} contains
For example, if @filepath{hi.sps} contains
@schemeblock[
@racketblock[
(import (rnrs))
(display "hello\n")
]
then
@commandline{plt-r6rs hi.scm}
@commandline{plt-r6rs hi.sps}
prints ``hello.''}
@item{Prefix the program with @schememetafont{#!r6rs}, which counts
@item{Prefix the program with @racketmetafont{#!r6rs}, which counts
as a comment from the @|r6rs| perspective, but is a synonym for
@scheme[#,(hash-lang) r6rs] from the PLT Scheme perspective.
Such files can be run like any other PLT Scheme module, such as
using @exec{mzscheme}:
@racket[#,(hash-lang) r6rs] from the Racket perspective.
Such files can be run like any other Racket module, such as
using @exec{racket}:
@commandline{mzscheme @nonterm{program-file}}
@commandline{racket @nonterm{program-file}}
or using DrScheme with the @onscreen{Module} language. The
file can also be compiled to bytecode using @exec{mzc}:
or using DrRacket. The file can also be compiled to bytecode
using @exec{raco make}:
@commandline{mzc @nonterm{program-file}}
@commandline{raco make @nonterm{program-file}}
For example, if @filepath{hi.ss} contains
For example, if @filepath{hi.sps} contains
@schemeblock[
#,(schememetafont "#!r6rs")
@racketblock[
#,(racketmetafont "#!r6rs")
(import (rnrs))
(display "hello\n")
]
then
@commandline{mzscheme hi.ss}
@commandline{racket hi.sps}
prints ``hello.'' Similarly, opening @filepath{hi.ss} in
DrScheme and clicking @onscreen{Run} prints ``hello'' within
the DrScheme interactions window.}
prints ``hello.'' Similarly, opening @filepath{hi.sps} in
DrRacket and clicking @onscreen{Run} prints ``hello'' within
the DrRacket interactions window.}
]
@ -118,17 +118,17 @@ To run a top-level program, either:
@section{Installing Libraries}
To reference an @|r6rs| library from a top-level program or another
library, it must be installed as a collection-based library in PLT
Scheme.
library, it must be installed as a collection-based library in
Racket.
One way to produce an @|r6rs| installed library is to create in
a @techlink[#:doc guide-src]{collection} a file that starts with
@schememetafont{#!r6rs} and that contains a @scheme[library] form. For
example, the following file might be created in a @filepath{hello.ss}
@racketmetafont{#!r6rs} and that contains a @racket[library] form. For
example, the following file might be created in a @filepath{hello.sls}
file within a @filepath{examples} collection directory:
@schemeblock[
#,(schememetafont "#!r6rs")
@racketblock[
#,(racketmetafont "#!r6rs")
(library (examples hello)
(export greet)
(import (rnrs))
@ -138,16 +138,16 @@ file within a @filepath{examples} collection directory:
]
Alternately, the @exec{plt-r6rs} executable with the @DFlag{install}
flag accepts a sequence of @scheme[library] declarations and installs
flag accepts a sequence of @racket[library] declarations and installs
them into separate files in a collection directory, based on the
declared name of each library:
@commandline{plt-r6rs --install @nonterm{libraries-file}}
By default, libraries are installed into the user-specific collection
directory (see @scheme[find-user-collects-dir]). The @DFlag{all-users}
directory (see @racket[find-user-collects-dir]). The @DFlag{all-users}
flag causes the libraries to be installed into the main installation,
instead (see @scheme[find-collects-dir]):
instead (see @racket[find-collects-dir]):
@commandline{plt-r6rs --install --all-users @nonterm{libraries-file}}
@ -159,15 +159,15 @@ the files are written. Libraries installed by @exec{plt-r6rs
One final option is to supply a @as-index{@DPFlag{path}} flag to
@exec{plt-r6rs}. A path added with @DPFlag{path} extends the set of
directories that are searched to find a collection (i.e., it sets
@scheme[current-library-collection-paths]). If @nonterm{dir} contains
@racket[current-library-collection-paths]). If @nonterm{dir} contains
@filepath{duck} and @filepath{cow} sub-directories with
@filepath{duck/feather.sls} and @filepath{cow/bell.sls}, and if each
file is an @|r6rs| library prefixed with @schememetafont{#!r6rs}, then
file is an @|r6rs| library prefixed with @racketmetafont{#!r6rs}, then
@exec{plt-r6rs ++path @nonterm{dir}} directs the @|r6rs| library
references @scheme[(duck feather)] and @scheme[(cow bell)] to the
references @racket[(duck feather)] and @racket[(cow bell)] to the
files. Note that this technique does not support accessing
@filepath{duck.sls} directly within @nonterm{dir}, since the library
reference @scheme[(duck)] is treated like @scheme[(duck main)] for
reference @racket[(duck)] is treated like @racket[(duck main)] for
finding the library, as explained in @secref["libpaths"]. Multiple
paths can be provided with multiple uses of @DPFlag{path}; the paths
are searched in order, and before the installation's collections.
@ -178,14 +178,14 @@ are searched in order, and before the installation's collections.
@defmodulelang[r6rs]
The @schememodname[r6rs] language is usually used in the form
@schememetafont{#!}@schememodname[r6rs], which is equivalent to
@scheme[@#,hash-lang[] @#,schememodname[r6rs]] and is also valid
The @racketmodname[r6rs] language is usually used in the form
@racketmetafont{#!}@racketmodname[r6rs], which is equivalent to
@racket[@#,hash-lang[] @#,racketmodname[r6rs]] and is also valid
@|r6rs| syntax.
The @schememodname[r6rs] module language provides only a
@schemeidfont{#%module-begin} binding, which is used to process the
entire module body (see @scheme[module]). It allows the body of a
The @racketmodname[r6rs] module language provides only a
@racketidfont{#%module-begin} binding, which is used to process the
entire module body (see @racket[module]). It allows the body of a
module to use the syntax of either a @|r6rs| library or a @|r6rs|
top-level program.
@ -199,12 +199,12 @@ top-level program.
(import import-spec ...)
program-body ...)]]{
An @schememodname[r6rs] module that contains a single @scheme[library]
An @racketmodname[r6rs] module that contains a single @racket[library]
form defines an @|r6rs| library, while a module body that starts with
an @scheme[import] form defined an @|r6rs| top-level program.
an @racket[import] form defined an @|r6rs| top-level program.
The @scheme[library], @scheme[export], and @scheme[import] identifiers
are not exported by the @schememodname[r6rs] library; they are
The @racket[library], @racket[export], and @racket[import] identifiers
are not exported by the @racketmodname[r6rs] library; they are
recognized through equivalence to unbound identifiers.}
@; ----------------------------------------
@ -213,12 +213,12 @@ recognized through equivalence to unbound identifiers.}
An @|r6rs| library name is sequence of symbols, optionally followed by
a version as a sequence of exact, non-negative integers. Roughly, such
a name is converted to a PLT Scheme module pathname (see @secref[#:doc
a name is converted to a Racket module pathname (see @secref[#:doc
guide-src "module-paths"]) by concatenating the symbols with a
@litchar{/} separator, and then appending the version integers each
with a preceding @litchar{-}. As a special case, when an @|r6rs| path
contains a single symbol (optionally followed by a version), a
@schemeidfont{main} symbol is effectively inserted after the initial
@racketidfont{main} symbol is effectively inserted after the initial
symbol. See below for further encoding considerations.
When an @|r6rs| library or top-level program refers to another
@ -229,9 +229,9 @@ time by searching the set of installed files.
In addition, when an @|r6rs| library path is converted, a file
extension is selected at compile time based on installed files. The
search order for file extensions is @filepath{.mzscheme.ss},
@filepath{.mzscheme.sls}, @filepath{.ss}, and @filepath{.sls}. When
resolving version constraints, these extensions are all tried when
looking for matches.
@filepath{.mzscheme.sls}, @filepath{.ss}, @filepath{.sls}, and
@filepath{.rkt}. When resolving version constraints, these extensions
are all tried when looking for matches.
@ -250,44 +250,44 @@ applied to each symbol before concatenating them:
module paths.}
@item{If the @|r6rs| library reference has two symbol elements and
the second one is @schemeidfont{main} followed by any number of
the second one is @racketidfont{main} followed by any number of
underscores, then an extra underscore is added to that symbol. This
conversion avoids a collision between an explicit @schemeidfont{main}
and the implicit @schemeidfont{main} when a library path has a single
conversion avoids a collision between an explicit @racketidfont{main}
and the implicit @racketidfont{main} when a library path has a single
symbol element.}
]
Examples (assuming a typical PLT Scheme installation):
Examples (assuming a typical Racket installation):
@schemeblock[
(rnrs io simple (6)) @#,elem{means} (lib "rnrs/io/simple-6.ss")
(rnrs) @#,elem{means} (lib "rnrs/main-6.ss")
(rnrs main) @#,elem{means} (lib "rnrs/main_.ss")
(rnrs (6)) @#,elem{means} (lib "rnrs/main-6.ss")
(scheme base) @#,elem{means} (lib "scheme/base.ss")
(achtung!) @#,elem{means} (lib "achtung%21/main.ss")
(funco new-λ) @#,elem{means} (lib "funco/new-%ce%bb.ss")
@racketblock[
(rnrs io simple (6)) @#,elem{means} (lib "rnrs/io/simple-6.rkt")
(rnrs) @#,elem{means} (lib "rnrs/main-6.rkt")
(rnrs main) @#,elem{means} (lib "rnrs/main_.rkt")
(rnrs (6)) @#,elem{means} (lib "rnrs/main-6.rkt")
(racket base) @#,elem{means} (lib "racket/base.rkt")
(achtung!) @#,elem{means} (lib "achtung%21/main.rkt")
(funco new-λ) @#,elem{means} (lib "funco/new-%ce%bb.rkt")
]
@; ----------------------------------------
@section{Scheme Interoperability}
@section{Language Interoperability}
Using the conversion rules in @secref["libpaths"], and @r6rs library
can refer to modules that are implemented in other dialects supported
by PLT Scheme, and other PLT Scheme modules can refer to libraries
by Racket, and other Racket modules can refer to libraries
that are implemented in @|r6rs|.
Beware that a @defterm{pair} in @|r6rs| corresponds to a
@defterm{mutable pair} in @schememodname[scheme/base]. Otherwise,
@|r6rs| libraries and @schememodname[scheme/base] share the same
@defterm{mutable pair} in @racketmodname[racket/base]. Otherwise,
@|r6rs| libraries and @racketmodname[racket/base] share the same
datatype for numbers, characters, strings, bytevectors (a.k.a. byte
strings), vectors, and so on. Hash tables are different. Input and
output ports from @schememodname[scheme/base] can be used directly as
output ports from @racketmodname[racket/base] can be used directly as
binary ports with @|r6rs| libraries, and all @|r6rs| ports can be used
as ports in @schememodname[scheme/base] programs, but only textual
as ports in @racketmodname[racket/base] programs, but only textual
ports created via @|r6rs| libraries can be used by other @|r6rs|
operations that expect textual ports.
@ -295,21 +295,21 @@ operations that expect textual ports.
@section[#:tag "conformance"]{@|r6rs| Conformance}
PLT Scheme's @|r6rs| support does not conform with the standard in
Racket's @|r6rs| support does not conform with the standard in
several known ways:
@itemize[
@item{When @scheme[guard] catches an exception that no clause
matches, the exception is re-@scheme[raise]ed without restoring
@item{When @racket[guard] catches an exception that no clause
matches, the exception is re-@racket[raise]ed without restoring
the continuation to the one that raised the exception.
This difference can be made visible using
@scheme[dynamic-wind]. According to @|r6rs|, the following
@racket[dynamic-wind]. According to @|r6rs|, the following
program should print ``in'' and ``out'' twice, but each prints
once using PLT Scheme:
once using Racket:
@schemeblock[
@racketblock[
(guard (exn [(equal? exn 5) 'five])
(guard (exn [(equal? exn 6) 'six])
(dynamic-wind
@ -321,27 +321,27 @@ several known ways:
Along similar lines, continuation capture and invocation within
an exception handler is restricted. Unless the exception is
raised through @scheme[raise-continuable], a handler can escape
raised through @racket[raise-continuable], a handler can escape
only through a continuation that is a tail of the current
continuation, and a continuation captured within the handler
cannot be invoked after control escapes from the raise.
The initial exception handler does not return for
non-@scheme[&serious] conditions, but @scheme[raise] and
@scheme[raise-continuable] both install an uncaught-exception
handler (via @scheme[parameterize] and
@scheme[uncaught-exception-handler]) to one that returns for
non-@scheme[&serious] conditions.}
non-@racket[&serious] conditions, but @racket[raise] and
@racket[raise-continuable] both install an uncaught-exception
handler (via @racket[parameterize] and
@racket[uncaught-exception-handler]) to one that returns for
non-@racket[&serious] conditions.}
@item{Inexact numbers are printed without a precision indicator, and
precision indicators are ignored on input (e.g.,
@schemevalfont{0.5|7} is read the same as @scheme[0.5]).}
@racketvalfont{0.5|7} is read the same as @racket[0.5]).}
@item{Word boundaries for @scheme[string-downcase],
@scheme[string-upcase], and @scheme[string-titlecase] are not
@item{Word boundaries for @racket[string-downcase],
@racket[string-upcase], and @racket[string-titlecase] are not
determined as specified by Unicode Standard Annex #29.}
@item{When an identifier bound by @scheme[letrec] or @scheme[letrec*]
@item{When an identifier bound by @racket[letrec] or @racket[letrec*]
is referenced before it is bound, an exception is not raised;
instead, the reference produces @|undefined-const|.}
@ -357,13 +357,13 @@ several known ways:
automatically reset the port's position to counteract the
effects of buffering.}
@item{The bindings in a namespace produced by @scheme[null-environment]
or @scheme[scheme-report-environment] correspond to @|r5rs| bindings
instead of @|r6rs| bindings. In particular, @scheme[=>], @scheme[else],
@scheme[_], and @scheme[...] are not bound.}
@item{The bindings in a namespace produced by @racket[null-environment]
or @racket[racket-report-environment] correspond to @|r5rs| bindings
instead of @|r6rs| bindings. In particular, @racket[=>], @racket[else],
@racket[_], and @racket[...] are not bound.}
@item{Bindings for @schemeidfont{#%datum}, @schemeidfont{#%app},
@schemeidfont{#%top}, and @schemeidfont{#%top-interaction} are
@item{Bindings for @racketidfont{#%datum}, @racketidfont{#%app},
@racketidfont{#%top}, and @racketidfont{#%top-interaction} are
imported into every library and program, and at every phase
level for which the library or program has imports.}
@ -388,7 +388,7 @@ several known ways:
@(define-syntax-rule (r6rs-module mod-path lib html anchor title elem ...)
(begin
(subsection #:tag (format "~a" 'mod-path)
(scheme lib) ": " title)
(racket lib) ": " title)
(defmodule mod-path)
"Original specification: " (link (format "../~a/~a#~a" (dir-of html) html anchor)
title)
@ -398,7 +398,7 @@ several known ways:
@r6rs-module[rnrs/base-6 (rnrs base (6))
"r6rs-Z-H-14.html" "node_sec_11.4" "Base"
;; Generated with makeindex.ss --r6rs, then further converted and
;; Generated with makeindex.rkt --r6rs, then further converted and
;; filtered by hand
(* #f "r6rs-Z-H-14.html" "node_idx_496")
(+ #f "r6rs-Z-H-14.html" "node_idx_494")
@ -1119,10 +1119,10 @@ See also @secref["conformance"].
(equal-hash #f "r6rs-lib-Z-H-14.html" "node_idx_1218")]
A hashtable is a dictionary in the sense of
@schememodname[scheme/dict], and hash table operations interact with
@racketmodname[racket/dict], and hash table operations interact with
threads in the same way for hash tables created with
@scheme[make-hash] (e.g., @scheme[hashtable-ref] and
@scheme[hashtable-set!] are thread-safe).
@racket[make-hash] (e.g., @racket[hashtable-ref] and
@racket[hashtable-set!] are thread-safe).
@r6rs-module[rnrs/enums-6 (rnrs enums (6))
"r6rs-lib-Z-H-15.html" "node_idx_1226" "Enumerations"

2
collects/scribblings/guide/compile.scrbl
View File

@ -43,4 +43,4 @@ Racket installation.
]
For more information on @exec{raco}, see @other-manual['(lib
"scribblings/mzc/mzc.scrbl")].
"scribblings/raco/raco.scrbl")].

2
collects/scribblings/guide/futures.scrbl
View File

@ -152,7 +152,7 @@ As a general guideline, any operation that is inlined by the
that are not inlined (including all operations if the JIT compiler is
disabled) are considered unsafe. The @exec{mzc} decompiler tool
annotates operations that can be inlined by the compiler (see
@secref[#:doc '(lib "scribblings/mzc/mzc.scrbl") "decompile"]), so the
@secref[#:doc '(lib "scribblings/raco/raco.scrbl") "decompile"]), so the
decompiler can be used to help predict parallel performance.
To more directly report what is happening in a program that uses

2
collects/scribblings/guide/performance.scrbl
View File

@ -275,7 +275,7 @@ flonum-specific results that are bound with @racket[let] and consumed
by a later flonum-specific operation are unboxed within temporary
storage. Finally, the compiler can detect some flonum-valued loop
accumulators and avoid boxing of the accumulator. The bytecode
decompiler (see @secref[#:doc '(lib "scribblings/mzc/mzc.scrbl")
decompiler (see @secref[#:doc '(lib "scribblings/raco/raco.scrbl")
"decompile"]) annotates combinations where the JIT can avoid boxes with
@racketidfont{#%flonum}, @racketidfont{#%as-flonum}, and
@racketidfont{#%from-flonum}.

5
collects/scribblings/guide/running.scrbl
View File

@ -167,7 +167,8 @@ instead of @racketmodname[racket/init].
@section[#:tag "exe"]{Creating Stand-Alone Executables}
@(define mzc-doc '(lib "scribblings/mzc/mzc.scrbl"))
@(define raco-doc '(lib "scribblings/raco/raco.scrbl"))
For information on creating and distributing executables, see
@secref[#:doc mzc-doc "sa"] in @other-manual[mzc-doc].
@secref[#:doc raco-doc "exe"] and @secref[#:doc raco-doc "exe-dist"] in
@other-manual[raco-doc].

2
collects/scribblings/guide/welcome.scrbl
View File

@ -173,7 +173,7 @@ options:
@item{From a command-line prompt, run @exec{raco exe
@nonterm{src-filename}}, where @nonterm{src-filename} contains
the program. See @secref[#:doc '(lib
"scribblings/mzc/mzc.scrbl") "exe"] for more information.}
"scribblings/raco/raco.scrbl") "exe"] for more information.}
@item{With Unix or Mac OS X, you can turn the program file into an
executable script by inserting the line

17
collects/scribblings/mzc/c-mods.scrbl
View File

@ -1,17 +0,0 @@
#lang scribble/doc
@(require scribble/manual
"common.ss")
@title[#:tag "c-mods"]{Embedding Scheme Modules via C}
The @DFlag{c-mods} mode for @|mzc| takes a set of Scheme modules and
generates a C source file that can be used as part of program that
embeds the PLT Scheme run-time system. See @secref[#:doc inside-doc
"embedding"] in @other-manual[inside-doc] for an explanation of
embedding programs.
The generated source file embeds the specified modules, and it defines
a @tt{declare_modules} function that puts the module declarations
into a namespace. Thus, using the output of @exec{mzc --c-mods}, a
program can embed PLT Scheme with a set of modules so that it does not
need a @filepath{collects} directory to load modules at run time.

83
collects/scribblings/mzc/dist.scrbl
View File

@ -1,83 +0,0 @@
#lang scribble/doc
@(require scribble/manual
"common.ss"
(for-label scheme/runtime-path))
@title[#:tag "exe-dist"]{Distributing Stand-Alone Executables}
The command-line flag @DFlag{exe-dir} directs @|mzc| to combine a
stand-alone executable (created via @DFlag{exe} or @DFlag{gui-exe})
with all of the shared libraries that are needed to run it, along with
any run-time files declared via @scheme[define-runtime-path]. The
resulting package can be moved to other machines that run the same
operating system.
After the @DFlag{exe-dir} flag, supply a directory to contain the
combined files for a distribution. Each command-line argument is an
executable to include in the distribution, so multiple executables can
be packaged together. For example, under Windows,
@commandline{mzc --exe-dir greetings hello.exe goodbye.exe}
creates a directory @filepath{greetings} (if the directory doesn't
exist already), and it copies the executables @filepath{hello.exe} and
@filepath{goodbye.exe} into @filepath{greetings}. It also creates a
@filepath{lib} sub-directory in @filepath{greetings} to contain DLLs,
and it adjusts the copied @filepath{hello.exe} and
@filepath{goodbye.exe} to use the DLLs in @filepath{lib}.
The layout of files within a distribution directory is
platform-specific:
@itemize[
@item{Under Windows, executables are put directly into the
distribution directory, and DLLs and other run-time files go
into a @filepath{lib} sub-directory.}
@item{Under Mac OS X, @DFlag{gui-exe} executables go into the
distribution directory, @DFlag{exe} executables go into a
@filepath{bin} subdirectory, and frameworks (i.e., shared
libraries) go into a @filepath{lib} sub-directory along with
other run-time files. As a special case, if the distribution has
a single @DFlag{gui-exe} executable, then the @filepath{lib}
directory is hidden inside the application bundle.}
@item{Under Unix, executables go into a @filepath{bin} subdirectory,
shared libraries (if any) go into a @filepath{lib} subdirectory
along with other run-time files, and wrapped executables are
placed into a @filepath{lib/plt} subdirectory with
version-specific names. This layout is consistent with Unix
installation conventions; the version-specific names for shared
libraries and wrapped executables means that distributions can
be safely unpacked into a standard place on target machines
without colliding with an existing PLT Scheme installation or
other executables created by @|mzc|.}
]
A distribution also has a @filepath{collects} directory that is used
as the main library collection directory for the packaged executables.
By default, the directory is empty. Use @|mzc|'s
@as-index{@DPFlag{copy-collects}} flag to supply a directory whose
content is copied into the distribution's @filepath{collects}
directory. The @DPFlag{copy-collects} flag can be used multiple times
to supply multiple directories.
When multiple executables are disrtibuted together, then separately
creating the executables with @DFlag{exe} and @DFlag{gui-exe} can
generate multiple copies of collection-based libraries that are used
by multiple executables. To share the library code, instead, specify a
target directory for library copies using the
@as-index{@DFlag{collects-dest}} flag with @DFlag{exe} and
@DFlag{gui-exe}, and specify the same directory for each executable
(so that the set of libraries used by all executables are pooled
together). Finally, when packaging the distribution with
@DFlag{exe-dir}, use the @DPFlag{copy-collects} flag to include the
copied libraries in the distribution.
@; ----------------------------------------------------------------------
@include-section["dist-api.scrbl"]
@include-section["bundle-api.scrbl"]

56
collects/scribblings/mzc/exe.scrbl
View File

@ -1,56 +0,0 @@
#lang scribble/doc
@(require scribble/manual
"common.ss"
(for-label scheme/runtime-path))
@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 @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 @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.
For example, the command
@commandline{mzc --gui-exe hello hello.ss}
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 @exec{mred}.
Library modules or other files that are referenced
dynamically---through @scheme[eval], @scheme[load], or
@scheme[dynamic-require]---are not automatically embedded into the
created executable. Such modules can be explicitly included using
@|mzc|'s @DFlag{lib} flag. Alternately, use
@scheme[define-runtime-path] to embed references to the run-time files
in the executable; the files are then copied and packaged together
with the executable when creating a distribution (as described in
@secref["exe-dist"]).
Modules that are implemented directly by extensions---i.e., extensions
that are automatically loaded from @scheme[(build-path "compiled"
"native" (system-library-subpath))] to satisfy a
@scheme[require]---are treated like other run-time files: a generated
executable uses them from their original location, and they are copied
and packaged together when creating a distribution.
The @DFlag{exe} and @DFlag{gui-exe} flags work only with
@scheme[module]-based programs. The @schememodname[compiler/embed]
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 @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"].
@; ----------------------------------------------------------------------
@include-section["exe-api.scrbl"]

3
collects/scribblings/mzc/info.rkt
View File

@ -1,3 +0,0 @@
#lang setup/infotab
(define scribblings '(("mzc.scrbl" (multi-page) (tool 50))))

312
collects/scribblings/mzc/launcher.scrbl
View File

@ -1,312 +0,0 @@
#lang scribble/doc
@(require scribble/manual
"common.ss"
(for-label scheme/base
scheme/unit
scheme/contract
launcher/launcher
launcher/launcher-sig
launcher/launcher-unit
compiler/embed
scheme/gui/base))
@title[#:tag "launcher"]{Installation-Specific Launchers for Scheme Code}
@defmodule[launcher/launcher]
The @schememodname[launcher/launcher] library provides functions for
creating @defterm{launchers}, which are similar to stand-alone
executables, but sometimes smaller because they depend permanently on
the local PLT Scheme installation. In the case of Unix, in particular,
a launcher is simply a shell script. The @|mzc| tool provides no
direct support for creating launchers.
@section{Creating Launchers}
@defproc[(make-mred-launcher [args (listof string?)]
[dest path-string?]
[aux (listof (cons/c symbol? any/c)) null])
void?]{
Creates the launcher @scheme[dest], which starts MrEd with the
command-line arguments specified as strings in @scheme[args]. Extra
arguments passed to the launcher at run-time are appended (modulo
special Unix/X flag handling, as described below) to this list and
passed on to MrEd. If @scheme[dest] exists already, as either a file
or directory, it is replaced.
The optional @scheme[aux] argument is an association list for
platform-specific options (i.e., it is a list of pairs where the first
element of the pair is a key symbol and the second element is the
value for that key). See also @scheme[build-aux-from-path]. See
@scheme[create-embedding-executable] for a list that applies to both
stand-alone executables and launchers under Windows and Mac OS X MrEd;
the following additional associations apply to launchers:
@itemize[
@item{@scheme['independent?] (Windows) --- a boolean; @scheme[#t]
creates an old-style launcher that is independent of the
MzScheme or MrEd binary, like @exec{setup-plt.exe}. No other
@scheme[aux] associations are used for an old-style launcher.}
@item{@scheme['exe-name] (Mac OS X, @scheme['script-3m] or
@scheme['script-cgc] variant) --- provides the base name for a
@scheme['3m]-/@scheme['cgc]-variant launcher, which the script
will call ignoring @scheme[args]. If this name is not provided,
the script will go through the MrEd executable as usual.}
@item{@scheme['relative?] (all platforms) --- a boolean, where
@scheme[#t] means that the generated launcher should find the
base MrEd executable through a relative path.}
]
For Unix/X, the script created by @scheme[make-mred-launcher] detects
and handles X Windows flags specially when they appear as the initial
arguments to the script. Instead of appending these arguments to the
end of @scheme[args], they are spliced in after any X Windows flags
already listed listed in @scheme[args]. The remaining arguments (i.e.,
all script flags and arguments after the last X Windows flag or
argument) are then appended after the spliced @scheme[args].}
@defproc[(make-mzscheme-launcher [args (listof string?)]
[dest path-string?]
[aux (listof (cons/c symbol? any/c)) null])
void?]{
Like @scheme[make-mred-launcher], but for starting MzScheme. Under Mac
OS X, the @scheme['exe-name] @scheme[aux] association is ignored.}
@defproc[(make-mred-program-launcher [file string?]
[collection string?]
[dest path-string?])
void?]{
Calls @scheme[make-mred-launcher] with arguments that start the MrEd
program implemented by @scheme[file] in @scheme[collection]:
@scheme[(list "-l-" (string-append collection "/" file))]. The
@scheme[_aux] argument to @scheme[make-mred-launcher] is generated by
stripping the suffix (if any) from @scheme[file], adding it to the
path of @scheme[collection], and passing the result to
@scheme[build-aux-from-path].}
@defproc[(make-mzscheme-program-launcher [file string?]
[collection string?]
[dest path-string?])
void?]{
Like @scheme[make-mred-program-launcher], but for
@scheme[make-mzscheme-launcher].}
@defproc[(install-mred-program-launcher [file string?]
[collection string?]
[name string?])
void?]{
Same as
@schemeblock[
(make-mred-program-launcher
file collection
(mred-program-launcher-path name))
]}
@defproc[(install-mzscheme-program-launcher [file string?]
[collection string?]
[name string?])
void?]{
Same as
@schemeblock[
(make-mzscheme-program-launcher
file collection
(mzscheme-program-launcher-path name))
]}
@; ----------------------------------------------------------------------
@section{Launcher Path and Platform Conventions}
@defproc[(mred-program-launcher-path [name string?]) path?]{
Returns a pathname for an executable in the PLT Scheme installation
called something like @scheme[name]. For Windows, the @filepath{.exe}
suffix is automatically appended to @scheme[name]. For Unix,
@scheme[name] is changed to lowercase, whitespace is changed to
@litchar{-}, and the path includes the @filepath{bin} subdirectory of
the PLT Scheme installation. For Mac OS X, the @filepath{.app} suffix
is appended to @scheme[name].}
@defproc[(mzscheme-program-launcher-path [name string?]) path?]{
Returns the same path as @scheme[(mred-program-launcher-path name)]
for Unix and Windows. For Mac OS X, the result is the same as for
Unix.}
@defproc[(mred-launcher-is-directory?) boolean?]{
Returns @scheme[#t] if MrEd launchers for the current platform are
directories from the user's perspective. For all currently supported
platforms, the result is @scheme[#f].}
@defproc[(mzscheme-launcher-is-directory?) boolean?]{
Like @scheme[mred-launcher-is-directory?], but for MzScheme
launchers.}
@defproc[(mred-launcher-is-actually-directory?) boolean?]{
Returns @scheme[#t] if MrEd launchers for the current platform are
implemented as directories from the filesystem's perspective. The
result is @scheme[#t] for Mac OS X, @scheme[#f] for all other
platforms.}
@defproc[(mzscheme-launcher-is-actually-directory?) boolean?]{
Like @scheme[mred-launcher-is-actuall-directory?], but for MzScheme
launchers. The result is @scheme[#f] for all platforms.}
@defproc[(mred-launcher-add-suffix [path-string? path]) path?]{
Returns a path with a suitable executable suffix added, if it's not
present already.}
@defproc[(mzscheme-launcher-add-suffix [path-string? path]) path?]{
Like @scheme[mred-launcher-add-suffix], but for MzScheme launchers.}
@defproc[(mred-launcher-put-file-extension+style+filters)
(values (or/c string? false/c)
(listof (one-of/c 'packages 'enter-packages))
(listof (list/c string? string?)))]{
Returns three values suitable for use as the @scheme[extension],
@scheme[style], and @scheme[filters] arguments to @scheme[put-file],
respectively.
If MrEd launchers for the current platform were directories form the
user's perspective, the @scheme[style] result is suitable for use with
@scheme[get-directory], and the @scheme[extension] result may be a
string indicating a required extension for the directory name. }
@defproc[(mzscheme-launcher-put-file-extension+style+filters)
(values (or/c string? false/c)
(listof (one-of/c 'packages 'enter-packages))
(listof (list/c string? string?)))]{
Like @scheme[mred-launcher-get-file-extension+style+filters], but for
MzScheme launchers.}
@; ----------------------------------------------------------------------
@section{Launcher Configuration}
@defproc[(mred-launcher-up-to-date? [dest path-string?]
[aux (listof (cons/c symbol? any/c))])
boolean?]{
Returns @scheme[#t] if the MrEd launcher @scheme[dest] does not need
to be updated, assuming that @scheme[dest] is a launcher and its
arguments have not changed.}
@defproc[(mzscheme-launcher-up-to-date? [dest path-string?]
[aux (listof (cons/c symbol? any/c))])
boolean?]{
Analogous to @scheme[mred-launcher-up-to-date?], but for a MzScheme
launcher.}
@defproc[(build-aux-from-path [path path-string?])
(listof (cons/c symbol? any/c))]{
Creates an association list suitable for use with
@scheme[make-mred-launcher] or @scheme[create-embedding-executable].
It builds associations by adding to @scheme[path] suffixes, such as
@filepath{.icns}, and checking whether such a file exists.
The recognized suffixes are as follows:
@itemize[
@item{@filepath{.icns} @'rarr @scheme['icns] file for use under Mac
OS X}
@item{@filepath{.ico} @'rarr @scheme['ico] file for use under
Windows}
@item{@filepath{.lch} @'rarr @scheme['independent?] as @scheme[#t]
(the file content is ignored) for use under Windows}
@item{@filepath{.creator} @'rarr @scheme['creator] as the initial
four characters in the file for use under Mac OS X}
@item{@filepath{.filetypes} @'rarr @scheme['file-types] as
@scheme[read] content (a single S-expression), and
@scheme['resource-files] as a list constructed by finding
@scheme["CFBundleTypeIconFile"] entries in @scheme['file-types]
(and filtering duplicates); for use under Mac OS X}
@item{@filepath{.utiexports} @'rarr @scheme['uti-exports] as
@scheme[read] content (a single S-expression); for use under
Mac OS X}
]}
@defparam[current-launcher-variant variant symbol?]{
A parameter that indicates a variant of MzScheme or MrEd to use for
launcher creation and for generating launcher names. The default is
the result of @scheme[(system-type 'gc)]. Under Unix and Windows, the
possibilities are @scheme['cgc] and @scheme['3m]. Under Mac OS X, the
@scheme['script-3m] and @scheme['script-cgc] variants are also
available for MrEd launchers.}
@defproc[(available-mred-variants) (listof symbol?)]{
Returns a list of symbols corresponding to available variants of MrEd
in the current PLT Scheme installation. The list normally includes at
least one of @scheme['3m] or @scheme['cgc]--- whichever is the result
of @scheme[(system-type 'gc)]---and may include the other, as well as
@scheme['script-3m] and/or @scheme['script-cgc] under Mac OS X.}
@defproc[(available-mzscheme-variants) (listof symbol?)]{
Returns a list of symbols corresponding to available variants of
MzScheme in the current PLT Scheme installation. The list normally
includes at least one of @scheme['3m] or @scheme['cgc]---whichever is
the result of @scheme[(system-type 'gc)]---and may include the other.}
@; ----------------------------------------
@section{Launcher Creation Signature}
@defmodule[launcher/launcher-sig]
@defsignature/splice[launcher^ ()]{
Includes the identifiers provided by @schememodname[launcher/launcher].}
@; ----------------------------------------
@section{Launcher Creation Unit}
@defmodule[launcher/launcher-unit]
@defthing[launcher@ unit?]{
A unit that imports nothing and exports @scheme[launcher^].}

316
collects/scribblings/mzc/make.scrbl
View File

@ -1,316 +0,0 @@
#lang scribble/doc
@(require scribble/manual
scribble/bnf
"common.ss"
(for-label scheme/base
scheme/include
scheme/contract
compiler/cm
compiler/cm-accomplice))
@title[#:tag "make"]{Compiling Modified Modules to Bytecode}
The default mode for @|mzc| is to accept filenames for Scheme modules
to be compiled to bytecode format. Modules are re-compiled only if the
source Scheme file is newer than the bytecode file, or if any imported
module is recompiled.
@; ----------------------------------------------------------------------
@section{Bytecode Files}
A file @filepath{@nonterm{name}.@nonterm{ext}} is compiled to bytecode
that is saved as @filepath{compiled/@nonterm{name}_@nonterm{ext}.zo}
relative to the file. As a result, the bytecode file is normally used
automatically when @filepath{@nonterm{name}.@nonterm{ext}} is required
as a module, since the underlying @scheme[load/use-compiled] operation
detects such a bytecode file.
For example, in a directory that contains the following files:
@itemize[
@item{@filepath{a.scm}:
@schememod[
scheme
(require "b.scm" "c.scm")
(+ b c)
]}
@item{@filepath{b.scm}:
@schememod[
scheme
(provide b)
(define b 1)
]}
@item{@filepath{c.scm}:
@schememod[
scheme
(provide c)
(define c 1)
]}]
then
@commandline{mzc a.scm}
triggers the creation of @filepath{compiled/a_ss.zo},
@filepath{compiled/b_ss.zo}, and @filepath{compiled/c_ss.zo}.
A subsequent
@commandline{mzscheme a.scm}
loads bytecode from the generated @filepath{.zo} files, paying attention
to the @filepath{.scm} sources only to confirm that each
@filepath{.zo} file has a later timestamp.
In contrast,
@commandline{mzc b.scm c.scm}
would create only @filepath{compiled/b_scm.zo} and
@filepath{compiled/c_scm.zo}, since neither @filepath{b.scm} nor
@filepath{c.scm} imports @filepath{a.scm}.
@; ----------------------------------------------------------------------
@section{Dependency Files}
In addition to a bytecode file, @|mzc| creates a file
@filepath{compiled/@nonterm{name}_@nonterm{ext}.dep} that records
dependencies of the compiled module on other module files and the
source file's SHA-1 hash. Using this dependency information, a
re-compilation request via @|mzc| can consult both the source file's
timestamp/hash and the timestamps/hashes for the bytecode of imported
modules. Furthermore, imported modules are themselves compiled as
necessary, including updating the bytecode and dependency files for
the imported modules, transitively.
Continuing the @exec{mzc a.scm} example from the previous section, the
@|mzc| creates @filepath{compiled/a_scm.dep},
@filepath{compiled/b_scm.dep}, and @filepath{compiled/c_scm.dep} at
the same time as the @filepath{.zo} files. The
@filepath{compiled/a_scm.dep} file records the dependency of
@filepath{a.scm} on @filepath{b.scm}, @filepath{c.scm} and the
@schememodname[scheme] library. If the @filepath{b.scm} file is
modified (so that its timestamp and SHA-1 hash changes), then running
@commandline{mzc a.scm}
again rebuilds @filepath{compiled/a_ss.zo} and
@filepath{compiled/b_ss.zo}.
For module files that are within library collections, @exec{setup-plt}
uses the same @filepath{.zo} and @filepath{.dep} conventions and files
as @|mzc|, so the two tools can be used together.
@; ----------------------------------------------------------------------
@section{Scheme Compilation Manager API}
@defmodule[compiler/cm]{The @schememodname[compiler/cm] module
implements the compilation and dependency management used by @|mzc|
and @exec{setup-plt}.}
@defproc[(make-compilation-manager-load/use-compiled-handler)
(path? (or/c symbol? false/c) . -> . any)]{
Returns a procedure suitable as a value for the
@scheme[current-load/use-compiled] parameter. The returned procedure
passes it arguments on to the @scheme[current-load/use-compiled]
procedure that is installed when
@scheme[make-compilation-manager-load/use-compiled-handler] is called,
but first it automatically compiles a source file to a @filepath{.zo}
file if
@itemize[
@item{the file is expected to contain a module (i.e., the second
argument to the handler is a symbol);}
@item{the value of each of @scheme[(current-eval)],
@scheme[(current-load)], and @scheme[(namespace-module-registry
(current-namespace))] is the same as when
@scheme[make-compilation-manager-load/use-compiled-handler] was
called;}
@item{the value of @scheme[use-compiled-file-paths] contains the
first path that was present when
@scheme[make-compilation-manager-load/use-compiled-handler] was
called;}
@item{the value of @scheme[current-load/use-compiled] is the result
of this procedure; and}
@item{one of the following holds:
@itemize[
@item{the source file is newer than the @filepath{.zo} file in the
first sub-directory listed in @scheme[use-compiled-file-paths]
(at the time that
@scheme[make-compilation-manager-load/use-compiled-handler]
was called), and either no @filepath{.dep} file exists or it
records a source-file SHA-1 hash that differs from the current
version and source-file SHA-1 hash;}
@item{no @filepath{.dep} file exists next to the @filepath{.zo}
file;}
@item{the version recorded in the @filepath{.dep} file does not
match the result of @scheme[(version)];}
@item{one of the files listed in the @filepath{.dep} file has a
@filepath{.zo} timestamp newer than the target @filepath{.zo},
and the combined hashes of the dependencies recorded in the
@filepath{.dep} file does not match the combined hash recorded
in the @filepath{.dep} file.}
]}
]
If SHA-1 hashes override a timestamp-based decision to recompile the
file, then the target @filepath{.zo} file's timestamp is updated to
the current time.
After the handler procedure compiles a @filepath{.zo} file, it creates
a corresponding @filepath{.dep} file that lists the current version
and the identification of every file that is directly
@scheme[require]d by the module in the compiled file. Additional
dependencies can be installed during compilation via
@schememodname[compiler/cm-accomplice]. The @filepath{.dep} file also
records the SHA-1 hash of the module's source, and it records a
combined SHA-1 hash of all of the dependencies that includes their
recursive dependencies.
The handler caches timestamps when it checks @filepath{.dep} files,
and the cache is maintained across calls to the same handler. The
cache is not consulted to compare the immediate source file to its
@filepath{.zo} file, which means that the caching behavior is
consistent with the caching of the default module name resolver (see
@scheme[current-module-name-resolver]).
If @scheme[use-compiled-file-paths] contains an empty list when
@scheme[make-compilation-manager-load/use-compiled-handler] is called,
then @scheme[exn:fail:contract] exception is raised.
@emph{Do not} install the result of
@scheme[make-compilation-manager-load/use-compiled-handler] when the
current namespace contains already-loaded versions of modules that may
need to be recompiled---unless the already-loaded modules are never
referenced by not-yet-loaded modules. References to already-loaded
modules may produce compiled files with inconsistent timestamps and/or
@filepath{.dep} files with incorrect information.}
@defproc[(managed-compile-zo [file path-string?]
[read-src-syntax (any/c input-port? . -> . syntax?) read-syntax])
void?]{
Compiles the given module source file to a @filepath{.zo}, installing
a compilation-manager handler while the file is compiled (so that
required modules are also compiled), and creating a @filepath{.dep} file
to record the timestamps of immediate files used to compile the source
(i.e., files @scheme[require]d in the source).
If @scheme[file] is compiled from source, then
@scheme[read-src-syntax] is used in the same way as
@scheme[read-syntax] to read the source module. The normal
@scheme[read-syntax] is used for any required files, however.}
@defboolparam[trust-existing-zos trust?]{
A parameter that is intended for use by @exec{setup-plt} when
installing with pre-built @filepath{.zo} files. It causes a
compilation-manager @scheme[load/use-compiled] handler to ``touch''
out-of-date @filepath{.zo} files instead of re-compiling from source.}
@defproc[(make-caching-managed-compile-zo
[read-src-syntax (any/c input-port? . -> . syntax?)])
(path-string? . -> . void?)]{
Returns a procedure that behaves like @scheme[managed-compile-zo]
(providing the same @scheme[read-src-syntax] each time), but a cache
of timestamp information is preserved across calls to the procedure.}
@defparam[manager-compile-notify-handler notify (path? . -> . any)]{
A parameter for a procedure of one argument that is called whenever a
compilation starts. The argument to the procedure is the file's path.}
@defparam[manager-trace-handler notify (string? . -> . any)]{
A parameter for a procedure of one argument that is called to report
compilation-manager actions, such as checking a file. The argument to
the procedure is a string.}
@defparam[manager-skip-file-handler proc (-> path? (or/c (cons/c number? promise?) #f))]{
A parameter whose value is called for each file that is loaded and
needs recompilation. If the procedure returns a pair, then the file
is skipped (i.e., not compiled); the number in the pair is used as
the timestamp for the file's bytecode, and the promise may be
@scheme[force]d to obtain a string that is used as hash of the
compiled file plus its dependencies. If the procedure returns
@scheme[#f], then the file is compiled as usual. The default is
@scheme[(lambda (x) #f)].}
@defproc[(file-stamp-in-collection [p path?]) (or/c (cons/c number? promise?) #f)]{
Calls @scheme[file-stamp-in-paths] with @scheme[p] and
@scheme[(current-library-collection-paths)].}
@defproc[(file-stamp-in-paths [p path?] [paths (listof path?)]) (or/c (cons/c number? promise?) #f)]{
Returns the file-modification date and @scheme[delay]ed hash of
@scheme[p]or its bytecode form (i.e., @filepath{.zo} file), whichever
exists and is newer, if @scheme[p] is an extension of any path in
@scheme[paths] (i.e., exists in the directory, a subdirectory,
etc.). Otherwise, the result is @scheme[#f].
This function is intended for use with @scheme[manager-skip-file-handler].}
@defproc[(get-file-sha1 [p path?]) (or/c string? #f)]{
Computes a SHA-1 hash for the file @racket[p]; the result is
@racket[#f] if @racket[p] cannot be opened.}
@defproc[(get-compiled-file-sha1 [p path?]) (or/c string? #f)]{
Computes a SHA-1 hash for the bytecode file @racket[p], appending any
dependency-describing hash available from a @filepath{.dep} file when
available (i.e., the suffix on @racket[p] is replaced by
@filepath{.dep} to locate dependency information). The result is
@racket[#f] if @racket[p] cannot be opened.}
@; ----------------------------------------------------------------------
@section{Compilation Manager Hook for Syntax Transformers}
@defmodule[compiler/cm-accomplice]
@defproc[(register-external-file [file (and path? complete-path?)]) void?]{
Logs a message (see @scheme[log-message]) at level @scheme['info]. The
message data is a @schemeidfont{file-dependency} prefab structure type
with one field whose value is @scheme[file].
A compilation manager implemented by @schememodname[compiler/cm] looks
for such messages to register an external dependency. The compilation
manager records (in a @filepath{.dep} file) the path as contributing
to the implementation of the module currently being
compiled. Afterward, if the registered file is modified, the
compilation manager will know to recompile the module.
The @scheme[include] macro, for example, calls this procedure with the
path of an included file as it expands an @scheme[include] form.}

75
collects/scribblings/mzc/mzc.scrbl
View File

@ -1,75 +0,0 @@
#lang scribble/doc
@(require scribble/manual
"common.ss")
@(define rare @emph{This mode is rarely useful.})
@title{@exec{mzc}: PLT Compilation and Packaging}
The @exec{mzc} tool supports various PLT Scheme compilation and
packaging tasks.
@table-of-contents[]
@section{Running @|mzc|}
The main action of @|mzc| is determined through one of the following
command-line flags:
@itemize[
@item{@as-index{@DFlag{make}} (the default), @as-index{@Flag{k}}
or @as-index{@DFlag{make-collection}} :
Compiles Scheme modules and all transitive imports to
bytecode. See @secref["make"].}
@item{@as-index{@DFlag{exe}}, @as-index{@DFlag{gui-exe}}, or
@as-index{@DFlag{exe-dir}} : Creates an executable to run a
Scheme module, or assembles all support libraries to move an
executable to a new filesystem. See @secref["exe"].}
@item{@as-index{@DFlag{collection-plt}} or @as-index{@DFlag{plt}} :
packages Scheme code for installation into a different PLT
Scheme installation. See @secref["plt"]. @|PLaneT| is usually a
better alternative.}
@item{@as-index{@DFlag{cc}}, @as-index{@DFlag{ld}},
@as-index{@DFlag{xform}} or @as-index{@Flag{x}} : Compiles,
links or transforms (for GC cooperation) C code to extend the
PLT Scheme runtime system. See @secref["cc"]. Using the
@scheme[scheme/foreign] FFI is often better; see
@other-manual['(lib "scribblings/foreign/foreign.scrbl")].}
@item{@as-index{@DFlag{c-mods}} : Creates C source to embed Scheme
modules into an executable that also embeds PLT Scheme. See
@secref["c-mods"].}
@item{@as-index{@DFlag{expand}} : Pretty-prints the macro-expanded
form of a Scheme program.}
@item{@as-index{@DFlag{decompile}} : Parses a bytecode file and
prints its content as quasi-Scheme. See @secref["decompile"].}
@item{@as-index{@DFlag{zo}}, @as-index{@Flag{z}}, or
@as-index{@DFlag{collection-zo}} : Compiles Scheme code to
bytecode, without following transitive imports. See
@secref["zo"]. @|rare|}
@item{@as-index{@DFlag{extension}}, @as-index{@Flag{e}},
@as-index{@DFlag{c-source}}, or @as-index{@Flag{c}} : Compiles
Scheme code to a native-code extension via C. See
@secref["ext"]. @|rare|}
]
@include-section["make.scrbl"]
@include-section["sa.scrbl"]
@include-section["plt.scrbl"]
@include-section["cc.scrbl"]
@include-section["c-mods.scrbl"]
@include-section["decompile.scrbl"]
@include-section["zo.scrbl"]
@include-section["ext.scrbl"]
@include-section["api.scrbl"]
@index-section[]

146
collects/scribblings/mzc/plt.scrbl
View File

@ -1,146 +0,0 @@
#lang scribble/doc
@(require scribble/manual
"common.ss"
(for-label scheme/base))
@title[#:tag "plt"]{Packaging Library Collections}
@margin-note{Before creating a @filepath{.plt} archive to distribute,
consider instead posting your package on
@link["http://planet.plt-scheme.org/"]{@|PLaneT|}.}
The command-line flags @DFlag{plt} and @DFlag{collection-plt} direct
@|mzc| to create an archive for distributing library files to PLT Scheme
users. A distribution archive usually has the suffix
@as-index{@filepath{.plt}}, which DrScheme recognizes as an archive to
provide automatic unpacking facilities. The @exec{setup-plt} program
also supports @filepath{.plt} unpacking.
An archive contains the following elements:
@itemize[
@item{A set of files and directories to be unpacked, and flags
indicating whether they are to be unpacked relative to the PLT Scheme
add-ons directory (which is user-specific), the PLT Scheme installation
directory, or a user-selected directory.
The files and directories for an archive are provided on the command
line to @|mzc|, either directly with @DFlag{plt} or in the form of
collection names with @DFlag{collection-plt}.
The @as-index{@DFlag{at-plt}} flag indicates that the files and
directories should be unpacked relative to the user's add-ons
directory, unless the user specifies the PLT Scheme installation
directory when unpacking. The @as-index{@DFlag{collection-plt}} flag
implies @DFlag{at-plt}. The @as-index{@DFlag{all-users}} flag
overrides @DFlag{at-plt}, and it indicates that the files and
directories should be unpacked relative to the PLT Scheme
installation directory, always.}
@item{A flag for each file indicating whether it overwrites an
existing file when the archive is unpacked; the default is to leave
the old file in place, but @|mzc|'s @as-index{@DFlag{replace}} flag
enables replacing for all files in the archive.}
@item{A list of collections to be set-up (via Setup PLT) after the
archive is unpacked; @|mzc|'s @as-index{@DPFlag{setup}} flag adds a
collection name to the archive's list, but each collection for
@DFlag{collection-plt} is added automatically.}
@item{A name for the archive, which is reported to the user by the
unpacking interface; @|mzc|'s @as-index{@DFlag{plt-name}} flag sets
the archive's name, but a default name is determined automatically
for @DFlag{collection-plt}.}
@item{A list of required collections (with associated version
numbers) and a list of conflicting collections; @|mzc| always names
the @filepath{mzscheme} collection in the required list (using the
collection's pack-time version), @|mzc| names each packed collection
in the conflict list (so that a collection is not unpacked on top of
a different version of the same collection), and @|mzc| extracts
other requirements and conflicts from the @filepath{info.ss} files of
collections for @DFlag{collection-plt}.}
]
Use the @DFlag{plt} flag to specify individual directories and files
for the archive. Each file and directory must be specified with a
relative path. By default, if the archive is unpacked with DrScheme,
the user will be prompted for a target directory, and if
@exec{setup-plt} is used to unpack the archive, the files and
directories will be unpacked relative to the current directory. If the
@DFlag{at-plt} flag is provided to @|mzc|, the files and directories
will be unpacked relative to the user's PLT Scheme add-ons directory,
instead. Finally, if the @DFlag{all-users} flag is provided to @|mzc|,
the files and directories will be unpacked relative to the PLT Scheme
installation directory, instead.
Use the @DFlag{collection-plt} flag to pack one or more collections;
sub-collections can be designated by using a @litchar{/} as a path
separator on all platforms. In this mode, @|mzc| automatically uses
paths relative to the PLT Scheme installation or add-ons directory for
the archived files, and the collections will be set-up after
unpacking. In addition, @|mzc| consults each collection's
@filepath{info.ss} file, as described below, to determine the set of
required and conflicting collections. Finally, @|mzc| consults the
first collection's @filepath{info.ss} file to obtain a default name
for the archive. For example, the following command creates a
@filepath{sirmail.plt} archive for distributing a @filepath{sirmail}
collection:
@commandline{mzc --collection-plt sirmail.plt sirmail}
When packing collections, @|mzc| checks the following fields of each
collection's @filepath{info.ss} file (see @secref["info.ss" #:doc
'(lib "scribblings/setup-plt/setup-plt.scrbl")]):
@itemize[
@item{@scheme[requires] --- A list of the form @scheme[(list (list
_coll _vers) ...)] where each @scheme[_coll] is a non-empty list of
relative-path strings, and each @scheme[_vers] is a (possibly empty)
list of exact integers. The indicated collections must be installed
at unpacking time, with version sequences that match as much of the
version sequence specified in the corresponding @scheme[vers].
A collection's version is indicated by a @scheme[version] field in
it's @filepath{info.ss} file, and the default version is the empty list.
The version sequence generalized major and minor version numbers. For
example, version @scheme['(2 5 4 7)] of a collection can be used when
any of @scheme['()], @scheme['(2)], @scheme['(2 5)], @scheme['(2 5
4)], or @scheme['(2 5 4 7)] is required.}
@item{@scheme[conflicts] --- A list of the form @scheme[(list _coll
...)] where each @scheme[_coll] is a non-empty list of relative-path
strings. The indicated collections must @emph{not} be installed at
unpacking time.}
]
For example, the @filepath{info.ss} file in the @filepath{sirmail} collection
might contain the following @scheme[info] declaration:
@schememod[
setup/infotab
(define name "SirMail")
(define mred-launcher-libraries (list "sirmail.ss"))
(define mred-launcher-names (list "SirMail"))
(define requires (list (list "mred")))
]
Then, the @filepath{sirmail.plt} file (created by the command-line
example above) will contain the name ``SirMail.'' When the archive is
unpacked, the unpacker will check that the MrEd collection is
installed (not just MzScheme), and that MrEd has the same version as
when @filepath{sirmail.plt} was created.
@; ----------------------------------------
@section{Scheme API for Packaging}
Although @|mzc|'s command-line interface is sufficient for most
purposes, see the @schememodname[setup/pack] library for a more
general interface for constructing archives.

18
collects/scribblings/mzc/sa.scrbl
View File

@ -1,18 +0,0 @@
#lang scribble/doc
@(require scribble/manual
"common.ss")
@title[#:tag "sa" #:style 'toc]{Creating and Distributing Stand-Alone Executables}
Whether bytecode or native code, the compiled code produced by @|mzc|
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
machines.
@local-table-of-contents[]
@include-section["exe.scrbl"]
@include-section["dist.scrbl"]
@include-section["launcher.scrbl"]

58
collects/scribblings/mzc/zo.scrbl
View File

@ -1,58 +0,0 @@
#lang scribble/doc
@(require scribble/manual
(for-label scheme/base
scheme/class
scheme/unit)
"common.ss")
@title[#:tag "zo"]{Compiling to Raw Bytecode}
The @DFlag{zo}/@Flag{z} mode for @|mzc| is an improverished form of
the default @DFlag{make}/@Flag{k} mode (which is described in
@secref["make"]), because it does not track import dependencies. It
does, however, support compilation of non-module source.
By default, the generated bytecode is placed in the same directory as
the source file---which is not where it will be found automatically
when loading the source. Use the @as-index{@DFlag{auto-dir}} flag to
redirect the output to a @filepath{compiled} subdirectory, where it
will be found automatically when loading the source file.
Outside of a module, top-level @scheme[define-syntaxes],
@scheme[module], @scheme[#%require],
@scheme[define-values-for-syntax], and and @scheme[begin]
expressions are handled specially by @exec{mzc --zo}: the compile-time
portion of the expression is evaluated, because it might affect later
expressions. (The @Flag{m} or @DFlag{module} flag turns off this
special handling.)
For example, when compiling the file containing
@schemeblock[
(require scheme/class)
(define f (class% object% (super-new)))
]
the @scheme[class] form from the @schememodname[scheme/class] library
must be bound in the compilation namespace at compile time. Thus, the
@scheme[require] expression is both compiled (to appear in the output
code) and evaluated (for further computation).
Many definition forms expand to @scheme[define-syntaxes]. For example,
@scheme[define-signature] expands to @scheme[define-syntaxes]. In
@scheme[--zo] mode, @|mzc| detects @scheme[define-syntaxes] and other
expressions after expansion, so top-level @scheme[define-signature]
expressions affect the compilation of later expressions, as a
programmer would expect.
In contrast, a @scheme[load] or @scheme[eval] expression in a source
file is compiled---but @emph{not evaluated!}---as the source file is
compiled. Even if the @scheme[load] expression loads syntax or
signature definitions, these will not be loaded as the file is
compiled. The same is true of application expressions that affect the
reader, such as @scheme[(read-case-sensitive #t)]. The @Flag{p} or
@DFlag{prefix} flag for @|mzc| takes a file and loads it before
compiling the source files specified on the command line.
In general, a better solution is to put all code to compile into a
module and use @|mzc| in its default mode.

18
collects/scribblings/mzc/api.scrbl → collects/scribblings/raco/api.scrbl
View File

@ -11,7 +11,7 @@
compiler/comp-unit
launcher/launcher))
@title{Scheme API for Compilation}
@title{API for Raw Compilation}
@defmodule[compiler/compiler]{
@ -73,16 +73,15 @@ file is reported through the current output port.}
Compiles the specified collection's files to @filepath{.zo} files.
The @filepath{.zo} files are placed into the collection's
@filepath{compiled} directory. By default, all files with the
extension @filepath{.ss} or @filepath{.scm} in a collection are
extension @filepath{.rkt}, @filepath{.ss}, or @filepath{.scm} in a collection are
compiled, as are all such files within subdirectories, execept that
any file or directory whose path starts with @scheme[scheme-path] is
skipped. (``Starts with'' means that the simplified path @scheme[_p]'s
byte-string form after @scheme[(simplify-path _p #f)]starts with the
byte-string form of @scheme[(simplify-path skip-path #f)].)
The collection compiler reads the collection's @filepath{info.ss} file
(see @secref[#:doc '(lib "scribblings/setup-plt/setup-plt.scrbl")
"info.ss"]) to obtain further instructions for compiling the
The collection compiler reads the collection's @filepath{info.rkt} file
(see @secref["info.rkt"]) to obtain further instructions for compiling the
collection. The following fields are used:
@itemize[
@ -112,8 +111,9 @@ collection. The following fields are used:
@item{@indexed-scheme[scribblings] : A list of pairs, each of which
starts with a path for documentation source. The sources (and
the files that they require) are compiled in the same way as
@filepath{.ss} and @filepath{.scm} files, unless the provided
@scheme[skip-docs?] argument is a true value.}
@filepath{.rkt}, @filepath{.ss}, and @filepath{.scm} files,
unless the provided @scheme[skip-docs?] argument is a true
value.}
]
@ -130,8 +130,8 @@ The compilation process for an individual file is driven by
Like @scheme[compile-collection-zos], but compiles the given directory
rather than a collection. The @scheme[info] function behaves like the
result of @scheme[get-info] to supply @filepath{info.ss} fields,
instead of using an @filepath{info.ss} file (if any) in the directory.}
result of @scheme[get-info] to supply @filepath{info.rkt} fields,
instead of using an @filepath{info.rkt} file (if any) in the directory.}
@; ----------------------------------------------------------------------

24
collects/scribblings/mzc/bundle-api.scrbl → collects/scribblings/raco/bundle-api.scrbl
View File

@ -2,16 +2,16 @@
@(require scribble/manual
scribble/bnf
(for-label scheme/gui
(for-label racket/gui
compiler/bundle-dist))
@title{Scheme API for Bundling Distributions}
@title{API for Bundling Distributions}
@defmodule[compiler/bundle-dist]{
The @schememodname[compiler/bundle-dist] library provides a function
The @racketmodname[compiler/bundle-dist] library provides a function
to pack a directory (usually assembled by
@scheme[assemble-distribution]) into a distribution file. Under
@racket[assemble-distribution]) into a distribution file. Under
Windows, the result is a @filepath{.zip} archive; under Mac OS X, it's
a @filepath{.dmg} disk image; under Unix, it's a @filepath{.tgz}
archive.}
@ -22,17 +22,17 @@ archive.}
[for-exe? any/c #f])
void?]{
Packages @scheme[dir] into @scheme[dist-file]. If @scheme[dist-file]
Packages @racket[dir] into @racket[dist-file]. If @racket[dist-file]
has no extension, a file extension is added automatcially (using the
first result of @scheme[bundle-put-file-extension+style+filters]).
first result of @racket[bundle-put-file-extension+style+filters]).
The created archive contains a directory with the same name as
@scheme[dir]---except under Mac OS X when @scheme[for-exe?] is true
and @scheme[dir] contains a single a single file or directory, in
@racket[dir]---except under Mac OS X when @racket[for-exe?] is true
and @racket[dir] contains a single a single file or directory, in
which case the created disk image contains just the file or
directory. The default for @scheme[for-exe?] is @scheme[#f].
directory. The default for @racket[for-exe?] is @racket[#f].
Archive creation fails if @scheme[dist-file] exists.}
Archive creation fails if @racket[dist-file] exists.}
@defproc[(bundle-put-file-extension+style+filters)
@ -40,6 +40,6 @@ Archive creation fails if @scheme[dist-file] exists.}
(listof (one-of/c 'packages 'enter-packages))
(listof (list/c string? string?)))]{
Returns three values suitable for use as the @scheme[extension],
@scheme[style], and @scheme[filters] arguments to @scheme[put-file],
Returns three values suitable for use as the @racket[extension],
@racket[style], and @racket[filters] arguments to @racket[put-file],
respectively to select a distribution-file name.}

17
collects/scribblings/raco/c-mods.scrbl Normal file
View File

@ -0,0 +1,17 @@
#lang scribble/doc
@(require scribble/manual
"common.ss")
@title[#:tag "c-mods"]{Embedding Modules via C}
The @DFlag{c-mods} mode for @exec{raco ctool} takes a set of Scheme
modules and generates a C source file that can be used as part of
program that embeds the Racket run-time system. See @secref[#:doc
inside-doc "embedding"] in @other-manual[inside-doc] for an
explanation of embedding programs.
The generated source file embeds the specified modules, and it defines
a @tt{declare_modules} function that puts the module declarations into
a namespace. Thus, using the output of @exec{raco ctool --c-mods}, a
program can embed PLT Scheme with a set of modules so that it does not
need a @filepath{collects} directory to load modules at run time.

42
collects/scribblings/mzc/cc.scrbl → collects/scribblings/raco/cc.scrbl
View File

@ -11,41 +11,41 @@
@title[#:tag "cc"]{Compiling and Linking C Extensions}
A @deftech{dynamic extension} is a shared library (a.k.a. DLL) that
extends PLT Scheme using the C API. An extension can be loaded
explicitly via @scheme[load-extension], or it can be loaded implicitly
through @scheme[require] or @scheme[load/use-compiled] in place of a
source @scheme[_file] when the extension is located at
extends Racket using the C API. An extension can be loaded explicitly
via @racket[load-extension], or it can be loaded implicitly through
@racket[require] or @racket[load/use-compiled] in place of a source
@racket[_file] when the extension is located at
@schemeblock[
@racketblock[
(build-path "compiled" "native" (system-library-subpath)
(path-add-suffix _file (system-type 'so-suffix)))
]
relative to @scheme[_file].
relative to @racket[_file].
For information on writing extensions, see @other-manual[inside-doc].
Three @|mzc| modes help for building extensions:
Three @exec{raco ctool} modes help for building extensions:
@itemize[
@item{@DFlag{cc} : Runs the host system's C compiler, automatically
supplying flags to locate the PLT Scheme header files and to
supplying flags to locate the Racket header files and to
compile for inclusion in a shared library.}
@item{@DFlag{ld} : Runs the host system's C linker, automatically
supplying flags to locate and link to the PLT Scheme libraries
supplying flags to locate and link to the Racket libraries
and to generate a shared library.}
@item{@DFlag{xform} : Transforms C code that is written without
explicit GC-cooperation hooks to cooperate with PLT Scheme's 3m
explicit GC-cooperation hooks to cooperate with Racket's 3m
garbage collector; see @secref[#:doc inside-doc "overview"] in
@other-manual[inside-doc].}
]
Compilation and linking build on the @schememodname[dynext/compile]
and @schememodname[dynext/link] libraries. The following @|mzc| flags
Compilation and linking build on the @racketmodname[dynext/compile]
and @racketmodname[dynext/link] libraries. The following @exec{raco ctool} flags
correspond to setting or accessing parameters for those libraries: @xflag{tool},
@xflag{compiler}, @xflag{ccf}, @xflag{ccf}, @xflag{ccf-clear},
@xflag{ccf-show}, @xflag{linker}, @pxflag{ldf}, @xflag{ldf},
@ -53,13 +53,13 @@ correspond to setting or accessing parameters for those libraries: @xflag{tool},
@pxflag{cppf}, @pxflag{cppf} @pxflag{cppf-clear}, and @xflag{cppf-show}.
The @as-index{@DFlag{3m}} flag specifies that the extension is to be
loaded into the 3m variant of PLT Scheme. The @as-index{@DFlag{cgc}}
loaded into the 3m variant of Racket. The @as-index{@DFlag{cgc}}
flag specifies that the extension is to be used with the CGC. The
default depends on @|mzc|: @DFlag{3m} if @|mzc| itself is running in
3m, @DFlag{cgc} if @|mzc| itself is running in CGC.
default depends on @exec{raco}: @DFlag{3m} if @exec{raco} itself is running in
3m, @DFlag{cgc} if @exec{raco} itself is running in CGC.
@section[#:tag "xform-api"]{Scheme API for 3m Transformation}
@section[#:tag "xform-api"]{API for 3m Transformation}
@defmodule[compiler/xform]
@ -71,15 +71,15 @@ default depends on @|mzc|: @DFlag{3m} if @|mzc| itself is running in
any/c]{
Transforms C code that is written without explicit GC-cooperation
hooks to cooperate with PLT Scheme's 3m garbage collector; see
hooks to cooperate with Racket's 3m garbage collector; see
@secref[#:doc '(lib "scribblings/inside/inside.scrbl") "overview"] in
@other-manual['(lib "scribblings/inside/inside.scrbl")].
The arguments are as for @scheme[compile-extension]; in addition
@scheme[keep-lines?] can be @scheme[#t] to generate GCC-style
The arguments are as for @racket[compile-extension]; in addition
@racket[keep-lines?] can be @racket[#t] to generate GCC-style
annotations to connect the generated C code with the original source
locations.
The file generated by @scheme[xform] can be compiled via
@scheme[compile-extension].}
The file generated by @racket[xform] can be compiled via
@racket[compile-extension].}

5
collects/scribblings/mzc/common.rkt → collects/scribblings/raco/common.rkt
View File

@ -1,10 +1,7 @@
#lang scheme/base
(require scribble/manual)
(provide mzc
inside-doc)
(define mzc (exec "mzc"))
(provide inside-doc)
(define inside-doc
'(lib "scribblings/inside/inside.scrbl"))

18
collects/scribblings/raco/ctool.scrbl Normal file
View File

@ -0,0 +1,18 @@
#lang scribble/doc
@(require scribble/manual
"common.ss")
@title[#:tag "ctool" #:style 'toc]{@exec{raco ctool}: Working with C Code}
The @exec{raco ctool} command works in various modes (as determined by
command-line flags) to support various tasks involving C code.
@local-table-of-contents[]
@; ----------------------------------------------------------------------
@include-section["cc.scrbl"]
@include-section["c-mods.scrbl"]
@include-section["ext.scrbl"]
@include-section["api.scrbl"]

89
collects/scribblings/mzc/decompile.scrbl → collects/scribblings/raco/decompile.scrbl
View File

@ -1,21 +1,22 @@
#lang scribble/doc
@(require scribble/manual
"common.ss"
(for-label scheme/base
(for-label racket/base
compiler/decompile
(only-in compiler/zo-parse compilation-top? req)
compiler/zo-marshal))
@title[#:tag "decompile"]{Decompiling Bytecode}
@title[#:tag "decompile"]{@exec{raco decompile}: Decompiling Bytecode}
The @DFlag{decompile} mode for @|mzc| takes a bytecode file (which
usually has the file extension @filepath{.zo}) and converts it back
to an approximation of Scheme code. Decompiled bytecode is mostly
useful for checking the compiler's transformation and optimization of
the source program.
The @exec{raco decompile} command takes a bytecode file (which usually
has the file extension @filepath{.zo}) or a source file with an
associated bytecode file (usually created with @exec{raco make}) and
converts it back to an approximation of Racket code. Decompiled
bytecode is mostly useful for checking the compiler's transformation
and optimization of the source program.
Many forms in the decompiled code, such as @scheme[module],
@scheme[define], and @scheme[lambda], have the same meanings as
Many forms in the decompiled code, such as @racket[module],
@racket[define], and @racket[lambda], have the same meanings as
always. Other forms and transformations are specific to the rendering
of bytecode, and they reflect a specific execution model:
@ -28,83 +29,83 @@ Many forms in the decompiled code, such as @scheme[module],
moreover, have a suffix that indicates the source module.
Non-local variables are always accessed indirectly though an implicit
@schemeidfont{#%globals} or @schemeidfont{#%modvars} variable that
@racketidfont{#%globals} or @racketidfont{#%modvars} variable that
resides on the value stack (which otherwise contains local
variables). Variable accesses are further wrapped with
@schemeidfont{#%checked} when the compiler cannot prove that the
@racketidfont{#%checked} when the compiler cannot prove that the
variable will be defined before the access.
Uses of core primitives are shown without a leading @litchar{_}, and
they are never wrapped with @schemeidfont{#%checked}.}
they are never wrapped with @racketidfont{#%checked}.}
@item{Local-variable access may be wrapped with
@schemeidfont{#%sfs-clear}, which indicates that the variable-stack
@racketidfont{#%sfs-clear}, which indicates that the variable-stack
location holding the variable will be cleared to prevent the
variable's value from being retained by the garbage collector.
Variables whose name starts with @schemeidfont{unused} are never
Variables whose name starts with @racketidfont{unused} are never
actually stored on the stack, and so they never have
@schemeidfont{#%sfs-clear} annotations. (The bytecode compiler
@racketidfont{#%sfs-clear} annotations. (The bytecode compiler
normally eliminates such bindings, but sometimes it cannot, either
because it cannot prove that the right-hand side produces the right
number of values, or the discovery that the variable is unused
happens too late with the compiler.)
Mutable variables are converted to explicitly boxed values using
@schemeidfont{#%box}, @schemeidfont{#%unbox}, and
@schemeidfont{#%set-boxes!} (which works on multiple boxes at once).
A @schemeidfont{set!-rec-values} operation constructs
@racketidfont{#%box}, @racketidfont{#%unbox}, and
@racketidfont{#%set-boxes!} (which works on multiple boxes at once).
A @racketidfont{set!-rec-values} operation constructs
mutually-recursive closures and simultaneously updates the
corresponding variable-stack locations that bind the closures. A
@schemeidfont{set!}, @schemeidfont{set!-values}, or
@schemeidfont{set!-rec-values} form is always used on a local
@racketidfont{set!}, @racketidfont{set!-values}, or
@racketidfont{set!-rec-values} form is always used on a local
variable before it is captured by a closure; that ordering reflects
how closures capture values in variable-stack locations, as opposed
to stack locations.}
@item{In a @scheme[lambda] form, if the procedure produced by the
@scheme[lambda] has a name (accessible via @scheme[object-name])
@item{In a @racket[lambda] form, if the procedure produced by the
@racket[lambda] has a name (accessible via @racket[object-name])
and/or source-location information, then it is shown as a quoted
constant at the start of the procedure's body. Afterward, if the
@scheme[lambda] form captures any bindings from its context, those
@racket[lambda] form captures any bindings from its context, those
bindings are also shown in a quoted constant. Neither constant
corresponds to a computation when the closure is called, though the
list of captured bindings corresponds to a closure allocation when
the @scheme[lambda] form itself is evaluated.
the @racket[lambda] form itself is evaluated.
A @scheme[lambda] form that closes over no bindings is wrapped with
@schemeidfont{#%closed} plus an identifier that is bound to the
A @racket[lambda] form that closes over no bindings is wrapped with
@racketidfont{#%closed} plus an identifier that is bound to the
closure. The binding's scope covers the entire decompiled output, and
it may be referenced directly in other parts of the program; the
binding corresponds to a constant closure value that is shared, and
it may even contain cyclic references to itself or other constant
closures.}
@item{A form @scheme[(#%apply-values _proc _expr)] is equivalent to
@scheme[(call-with-values (lambda () _expr) _proc)], but the run-time
system avoids allocating a closure for @scheme[_expr].}
@item{A form @racket[(#%apply-values _proc _expr)] is equivalent to
@racket[(call-with-values (lambda () _expr) _proc)], but the run-time
system avoids allocating a closure for @racket[_expr].}
@item{Some applications of core primitives are annotated with
@schemeidfont{#%in}, which indicates that the JIT compiler will
@racketidfont{#%in}, which indicates that the JIT compiler will
inline the operation. (Inlining information is not part of the
bytecode, but is instead based on an enumeration of primitives that
the JIT is known to handle specially.) Operations from
@schememodname[scheme/flonum] and @schememodname[scheme/unsafe/ops]
are always inlined, so @schemeidfont{#%in} is not shown for them.}
@racketmodname[racket/flonum] and @racketmodname[racket/unsafe/ops]
are always inlined, so @racketidfont{#%in} is not shown for them.}
@item{Some applications of flonum operations from @schememodname[scheme/flonum]
and @schememodname[scheme/unsafe/ops] are annotated with
@schemeidfont{#%flonum}, indicating a place where the JIT compiler
@item{Some applications of flonum operations from @racketmodname[racket/flonum]
and @racketmodname[racket/unsafe/ops] are annotated with
@racketidfont{#%flonum}, indicating a place where the JIT compiler
might avoid allocation for intermediate flonum results. A single
@schemeidfont{#%flonum} by itself is not useful, but a
@schemeidfont{#%flonum} operation that consumes a
@schemeidfont{#%flonum} or @schemeidfont{#%from-flonum} argument
@racketidfont{#%flonum} by itself is not useful, but a
@racketidfont{#%flonum} operation that consumes a
@racketidfont{#%flonum} or @racketidfont{#%from-flonum} argument
indicates a potential performance improvement. A
@schemeidfont{#%from-flonum} wraps an identifier that is bound by
@scheme[let] with a @schemeidfont{#%as-flonum} around its value,
@racketidfont{#%from-flonum} wraps an identifier that is bound by
@racket[let] with a @racketidfont{#%as-flonum} around its value,
which indicates a local binding that can avoid boxing (when used as
an argument to an operation that can work with unboxed values).}
@item{A @schemeidfont{#%decode-syntax} form corresponds to a syntax
@item{A @racketidfont{#%decode-syntax} form corresponds to a syntax
object. Future improvements to the decompiler will convert such
syntax objects to a readable form.}
@ -112,7 +113,7 @@ Many forms in the decompiled code, such as @scheme[module],
@; ------------------------------------------------------------
@section{Scheme API for Decompiling}
@section{API for Decompiling}
@defmodule[compiler/decompile]
@ -127,7 +128,7 @@ Consumes the result of parsing bytecode and returns an S-expression
@; ------------------------------------------------------------
@section{Scheme API for Marshaling Bytecode}
@section{API for Marshaling Bytecode}
@defmodule[compiler/zo-marshal]
@ -135,5 +136,5 @@ Consumes the result of parsing bytecode and returns an S-expression
Consumes a representation of bytecode and generates a byte string for
the marshaled bytecode. Currently, syntax objects are not supported,
including in @scheme[req] for a top-level @scheme[#%require].}
including in @racket[req] for a top-level @racket[#%require].}

22
collects/scribblings/mzc/dist-api.scrbl → collects/scribblings/raco/dist-api.scrbl
View File

@ -2,16 +2,16 @@
@(require scribble/manual
scribble/bnf
(for-label scheme/gui
(for-label racket/gui
compiler/distribute
launcher/launcher))
@title{Scheme API for Distributing Executables}
@title{API for Distributing Executables}
@defmodule[compiler/distribute]{
The @schememodname[compiler/distribute] library provides a function to
perform the same work as @exec{mzc --exe} or @exec{mzc --gui-exe}.}
The @racketmodname[compiler/distribute] library provides a function to
perform the same work as @exec{raco distribute}.}
@defproc[(assemble-distribution [dest-dir path-string?]
@ -20,19 +20,19 @@ perform the same work as @exec{mzc --exe} or @exec{mzc --gui-exe}.}
[#:copy-collects dirs (listof path-string?) null])
void?]{
Copies the executables in @scheme[exec-files] to the directory
@scheme[dest-dir], along with DLLs, frameworks, and/or shared
Copies the executables in @racket[exec-files] to the directory
@racket[dest-dir], along with DLLs, frameworks, and/or shared
libraries that the executables need to run a different machine.
The arrangement of the executables and support files in
@scheme[dest-dir] depends on the platform. In general
@scheme[assemble-distribution] tries to do the Right Thing.
@racket[dest-dir] depends on the platform. In general
@racket[assemble-distribution] tries to do the Right Thing.
If a @scheme[#:collects-path] argument is given, it overrides the
If a @racket[#:collects-path] argument is given, it overrides the
default location of the main @filepath{collects} directory for the
packaged executables. It should be relative to the @scheme[dest-dir]
packaged executables. It should be relative to the @racket[dest-dir]
directory (typically inside it).
The content of each directory in the @scheme[#:copy-collects] argument
The content of each directory in the @racket[#:copy-collects] argument
is copied into the main @filepath{collects} directory for the packaged
executables.}

83
collects/scribblings/raco/dist.scrbl Normal file
View File

@ -0,0 +1,83 @@
#lang scribble/doc
@(require scribble/manual
"common.ss"
(for-label racket/runtime-path))
@title[#:tag "exe-dist"]{@exec{raco distribute}: Sharing Stand-Alone Executables}
The @exec{raco distribute} command combines a
stand-alone executable created by @exec{raco exe} with all of the
shared libraries that are needed to run it, along with any run-time
files declared via @racket[define-runtime-path]. The resulting
package can be moved to other machines that run the same operating
system.
After the @exec{raco distribute} command, supply a directory to
contain the combined files for a distribution. Each command-line
argument is an executable to include in the distribution, so multiple
executables can be packaged together. For example, under Windows,
@commandline{raco distribute greetings hello.exe goodbye.exe}
creates a directory @filepath{greetings} (if the directory doesn't
exist already), and it copies the executables @filepath{hello.exe} and
@filepath{goodbye.exe} into @filepath{greetings}. It also creates a
@filepath{lib} sub-directory in @filepath{greetings} to contain DLLs,
and it adjusts the copied @filepath{hello.exe} and
@filepath{goodbye.exe} to use the DLLs in @filepath{lib}.
The layout of files within a distribution directory is
platform-specific:
@itemize[
@item{Under Windows, executables are put directly into the
distribution directory, and DLLs and other run-time files go
into a @filepath{lib} sub-directory.}
@item{Under Mac OS X, GUI executables go into the distribution
directory, other executables go into a @filepath{bin}
subdirectory, and frameworks (i.e., shared libraries) go into a
@filepath{lib} sub-directory along with other run-time files. As
a special case, if the distribution has a single @DFlag{gui-exe}
executable, then the @filepath{lib} directory is hidden inside
the application bundle.}
@item{Under Unix, executables go into a @filepath{bin} subdirectory,
shared libraries (if any) go into a @filepath{lib} subdirectory
along with other run-time files, and wrapped executables are
placed into a @filepath{lib/plt} subdirectory with
version-specific names. This layout is consistent with Unix
installation conventions; the version-specific names for shared
libraries and wrapped executables means that distributions can
be safely unpacked into a standard place on target machines
without colliding with an existing Racket installation or
other executables created by @exec{raco exe}.}
]
A distribution also has a @filepath{collects} directory that is used
as the main library collection directory for the packaged executables.
By default, the directory is empty. Use the
@as-index{@DPFlag{copy-collects}} flag of @exec{raco distribute} to
supply a directory whose content is copied into the distribution's
@filepath{collects} directory. The @DPFlag{copy-collects} flag can be
used multiple times to supply multiple directories.
When multiple executables are distributed together, then separately
creating the executables with @exec{raco exe} can generate multiple
copies of collection-based libraries that are used by multiple
executables. To share the library code, instead, specify a target
directory for library copies using the
@as-index{@DFlag{collects-dest}} flag with @exec{raco exe}, and
specify the same directory for each executable (so that the set of
libraries used by all executables are pooled together). Finally, when
packaging the distribution with @exec{raco distribute}, use the
@DPFlag{copy-collects} flag to include the copied libraries in the
distribution.
@; ----------------------------------------------------------------------
@include-section["dist-api.scrbl"]
@include-section["bundle-api.scrbl"]

257
collects/scribblings/mzc/exe-api.scrbl → collects/scribblings/raco/exe-api.scrbl
View File

@ -2,7 +2,7 @@
@(require scribble/manual
scribble/bnf
(for-label scheme/gui
(for-label racket/gui
compiler/compiler
compiler/sig
compiler/compiler-unit
@ -13,32 +13,32 @@
compiler/embed
compiler/embed-sig
compiler/embed-unit
scheme/runtime-path
racket/runtime-path
launcher/launcher))
@title{Scheme API for Creating Executables}
@title{API for Creating Executables}
@defmodule[compiler/embed]{
The @schememodname[compiler/embed] library provides a function to
embed Scheme code into a copy of MzScheme or MrEd, thus creating a
stand-alone Scheme executable. To package the executable into a
distribution that is indpendent of your PLT installation, use
@scheme[assemble-distribution] from
@schememodname[compiler/distribute].}
The @racketmodname[compiler/embed] library provides a function to
embed Racket code into a copy of Racket or GRacket, thus creating a
stand-alone Racket executable. To package the executable into a
distribution that is indpendent of your Racket installation, use
@racket[assemble-distribution] from
@racketmodname[compiler/distribute].}
Embedding walks the module dependency graph to find all modules needed
by some initial set of top-level modules, compiling them if needed,
and combining them into a ``module bundle.'' In addition to the module
code, the bundle extends the module name resolver, so that modules can
be @scheme[require]d with their original names, and they will be
be @racket[require]d with their original names, and they will be
retrieved from the bundle instead of the filesystem.
The @scheme[create-embedding-executable] function combines the bundle
with an executable (MzScheme or MrEd). The
@scheme[write-module-bundle] function prints the bundle to the current
output port, instead; this stream can be @scheme[load]ed directly by a
running program, as long as the @scheme[read-accept-compiled]
The @racket[create-embedding-executable] function combines the bundle
with an executable (Racket or GRacket). The
@racket[write-module-bundle] function prints the bundle to the current
output port, instead; this stream can be @racket[load]ed directly by a
running program, as long as the @racket[read-accept-compiled]
parameter is true.
@defproc[(create-embedding-executable [dest path-string?]
@ -62,6 +62,7 @@ parameter is true.
null)]
[#:cmdline cmdline (listof string?)
null]
[#:gracket? gracket? any/c #f]
[#:mred? mred? any/c #f]
[#:variant variant (one-of/c 'cgc '3m)
(system-type 'gc)]
@ -89,177 +90,177 @@ parameter is true.
(lambda (p m) null)])
void?]{
Copies the MzScheme (if @scheme[mred?] is @scheme[#f]) or MrEd
(otherwise) binary, embedding code into the copied executable to be
loaded on startup. Under Unix, the binary is actually a wrapper
executable that execs the original; see also the
@scheme['original-exe?] tag for @scheme[aux].
Copies the Racket (if @racket[gracket?] and @racket[mred?] are
@racket[#f]) or GRacket (otherwise) binary, embedding code into the
copied executable to be loaded on startup. Under Unix, the binary is
actually a wrapper executable that execs the original; see also the
@racket['original-exe?] tag for @racket[aux].
The embedding executable is written to @scheme[dest], which is
The embedding executable is written to @racket[dest], which is
overwritten if it exists already (as a file or directory).
The embedded code consists of module declarations followed by
additional (arbitrary) code. When a module is embedded, every module
that it imports is also embedded. Library modules are embedded so that
they are accessible via their @scheme[lib] paths in the initial
namespace except as specified in @scheme[mod-list], other modules
they are accessible via their @racket[lib] paths in the initial
namespace except as specified in @racket[mod-list], other modules
(accessed via local paths and absolute paths) are embedded with a
generated prefix, so that they are not directly accessible.
The @scheme[#:modules] argument @scheme[mod-list] designates modules
to be embedded, as described below. The @scheme[#:literal-files] and
@scheme[#:literal-expressions] arguments specify literal code to be
The @racket[#:modules] argument @racket[mod-list] designates modules
to be embedded, as described below. The @racket[#:literal-files] and
@racket[#:literal-expressions] arguments specify literal code to be
copied into the executable: the content of each file in
@scheme[literal-files] is copied in order (with no intervening space),
followed by each element of @scheme[literal-sexps]. The
@scheme[literal-files] files or @scheme[literal-sexps] list can
@racket[literal-files] is copied in order (with no intervening space),
followed by each element of @racket[literal-sexps]. The
@racket[literal-files] files or @racket[literal-sexps] list can
contain compiled bytecode, and it's possible that the content of the
@scheme[literal-files] files only parse when concatenated; the files
@racket[literal-files] files only parse when concatenated; the files
and expression are not compiled or inspected in any way during the
embedding process. Beware that the initial namespace contains no
bindings; use compiled expressions to bootstrap the namespace. If
@scheme[literal-sexp] is @scheme[#f], no literal expression is
included in the executable. The @scheme[#:literal-expression]
@racket[literal-sexp] is @racket[#f], no literal expression is
included in the executable. The @racket[#:literal-expression]
(singular) argument is for backward compatibility.
If the @scheme[#:configure-via-first-module?] argument is specified as
true, then the language of the first module in @scheme[mod-list] is
If the @racket[#:configure-via-first-module?] argument is specified as
true, then the language of the first module in @racket[mod-list] is
used to configure the run-time environment before the expressions
added by @scheme[#:literal-files] and @scheme[#:literal-expressions]
added by @racket[#:literal-files] and @racket[#:literal-expressions]
are evaluated. See also @secref[#:doc '(lib
"scribblings/reference/reference.scrbl") "configure-runtime"].
The @scheme[#:cmdline] argument @scheme[cmdline] contains command-line
The @racket[#:cmdline] argument @racket[cmdline] contains command-line
strings that are prefixed onto any actual command-line arguments that
are provided to the embedding executable. A command-line argument that
evaluates an expression or loads a file will be executed after the
embedded code is loaded.
Each element of the @scheme[#:modules] argument @scheme[mod-list] is a
Each element of the @racket[#:modules] argument @racket[mod-list] is a
two-item list, where the first item is a prefix for the module name,
and the second item is a module path datum (that's in the format
understood by the default module name resolver). The prefix can be a
symbol, @scheme[#f] to indicate no prefix, or @scheme[#t] to indicate
symbol, @racket[#f] to indicate no prefix, or @racket[#t] to indicate
an auto-generated prefix. For example,
@schemeblock['((#f "m.ss"))]
@racketblock['((#f "m.ss"))]
embeds the module @scheme[m] from the file @filepath{m.ss}, without
prefixing the name of the module; the @scheme[literal-sexpr] argument
to go with the above might be @scheme['(require m)].
embeds the module @racket[m] from the file @filepath{m.ss}, without
prefixing the name of the module; the @racket[literal-sexpr] argument
to go with the above might be @racket['(require m)].
Modules are normally compiled before they are embedded into the target
executable; see also @scheme[#:compiler] and @scheme[#:src-filter]
executable; see also @racket[#:compiler] and @racket[#:src-filter]
below. When a module declares run-time paths via
@scheme[define-runtime-path], the generated executable records the
@racket[define-runtime-path], the generated executable records the
path (for use both by immediate execution and for creating a
distribution that contains the executable).
The optional @scheme[#:aux] argument is an association list for
The optional @racket[#:aux] argument is an association list for
platform-specific options (i.e., it is a list of pairs where the first
element of the pair is a key symbol and the second element is the
value for that key). See also @scheme[build-aux-from-path]. The
value for that key). See also @racket[build-aux-from-path]. The
currently supported keys are as follows:
@itemize[
@item{@scheme['icns] (Mac OS X) : An icon file path (suffix
@item{@racket['icns] (Mac OS X) : An icon file path (suffix
@filepath{.icns}) to use for the executable's desktop icon.}
@item{@scheme['ico] (Windows) : An icon file path (suffix
@item{@racket['ico] (Windows) : An icon file path (suffix
@filepath{.ico}) to use for the executable's desktop icon;
the executable will have 16x16, 32x32, and 48x48 icons at
4-bit, 8-bit, and 32-bit (RBBA) depths; the icons are copied
and generated from any 16x16, 32x32, and 48x48 icons in the
@filepath{.ico} file.}
@item{@scheme['creator] (Mac OS X) : Provides a 4-character string
@item{@racket['creator] (Mac OS X) : Provides a 4-character string
to use as the application signature.}
@item{@scheme['file-types] (Mac OS X) : Provides a list of
@item{@racket['file-types] (Mac OS X) : Provides a list of
association lists, one for each type of file handled by the
application; each association is a two-element list, where the
first (key) element is a string recognized by Finder, and the
second element is a plist value (see
@schememodname[xml/plist]). See @filepath{drscheme.filetypes}
in the @filepath{drscheme} collection for an example.}
@racketmodname[xml/plist]). See @filepath{drracket.filetypes}
in the @filepath{drracket} collection for an example.}
@item{@scheme['uti-exports] (Mac OS X) : Provides a list of
@item{@racket['uti-exports] (Mac OS X) : Provides a list of
association lists, one for each @as-index{Uniform Type
Identifier} (UTI) exported by the executable; each association
is a two-element list, where the first (key) element is a
string recognized in a UTI declaration, and the second element
is a plist value (see @schememodname[xml/plist]). See
@filepath{drscheme.utiexports} in the @filepath{drscheme}
is a plist value (see @racketmodname[xml/plist]). See
@filepath{drracket.utiexports} in the @filepath{drracket}
collection for an example.}
@item{@scheme['resource-files] (Mac OS X) : extra files to copy into
@item{@racket['resource-files] (Mac OS X) : extra files to copy into
the @filepath{Resources} directory of the generated
executable.}
@item{@scheme['framework-root] (Mac OS X) : A string to prefix the
executable's path to the MzScheme and MrEd frameworks
@item{@racket['framework-root] (Mac OS X) : A string to prefix the
executable's path to the Racket and GRacket frameworks
(including a separating slash); note that when the prefix
starts @filepath{@"@"executable_path/} works for a
MzScheme-based application, the corresponding prefix start for
a MrEd-based application is
@filepath{@"@"executable_path/../../../}; if @scheme[#f] is
Racket-based application, the corresponding prefix start for
a GRacket-based application is
@filepath{@"@"executable_path/../../../}; if @racket[#f] is
supplied, the executable's framework path is left as-is,
otherwise the original executable's path to a framework is
converted to an absolute path if it was relative.}
@item{@scheme['dll-dir] (Windows) : A string/path to a directory
that contains PLT DLLs needed by the executable, such as
@filepath{pltmzsch@nonterm{version}.dll}, or a boolean; a path
can be relative to the executable; if @scheme[#f] is supplied,
the path is left as-is; if @scheme[#t] is supplied, the path
@item{@racket['dll-dir] (Windows) : A string/path to a directory
that contains Racket DLLs needed by the executable, such as
@filepath{racket@nonterm{version}.dll}, or a boolean; a path
can be relative to the executable; if @racket[#f] is supplied,
the path is left as-is; if @racket[#t] is supplied, the path
is dropped (so that the DLLs must be in the system directory
or the user's @envvar{PATH}); if no value is supplied the
original executable's path to DLLs is converted to an absolute
path if it was relative.}
@item{@scheme['subsystem] (Windows) : A symbol, either
@scheme['console] for a console application or
@scheme['windows] for a consoleless application; the default
is @scheme['console] for a MzScheme-based application and
@scheme['windows] for a MrEd-based application; see also
@scheme['single-instance?], below.}
@item{@racket['subsystem] (Windows) : A symbol, either
@racket['console] for a console application or
@racket['windows] for a consoleless application; the default
is @racket['console] for a Racket-based application and
@racket['windows] for a GRacket-based application; see also
@racket['single-instance?], below.}
@item{@scheme['single-instance?] (Windows) : A boolean for
MrEd-based apps; the default is @scheme[#t], which means that
@item{@racket['single-instance?] (Windows) : A boolean for
GRacket-based apps; the default is @racket[#t], which means that
the app looks for instances of itself on startup and merely
brings the other instance to the front; @scheme[#f] means that
brings the other instance to the front; @racket[#f] means that
multiple instances are expected.}
@item{@scheme['forget-exe?] (Windows, Mac OS X) : A boolean;
@scheme[#t] for a launcher (see @scheme[launcher?] below) does
@item{@racket['forget-exe?] (Windows, Mac OS X) : A boolean;
@racket[#t] for a launcher (see @racket[launcher?] below) does
not preserve the original executable name for
@scheme[(find-system-path 'exec-file)]; the main consequence
@racket[(find-system-path 'exec-file)]; the main consequence
is that library collections will be found relative to the
launcher instead of the original executable.}
@item{@scheme['original-exe?] (Unix) : A boolean; @scheme[#t] means
that the embedding uses the original MzScheme or MrEd
@item{@racket['original-exe?] (Unix) : A boolean; @racket[#t] means
that the embedding uses the original Racket or GRacket
executable, instead of a wrapper binary that execs the
original; the default is @scheme[#f].}
original; the default is @racket[#f].}
@item{@scheme['relative?] (Unix, Windows, Mac OS X): A boolean;
@scheme[#t] means that, to the degree that the generated
@item{@racket['relative?] (Unix, Windows, Mac OS X): A boolean;
@racket[#t] means that, to the degree that the generated
executable must refer to another, it can use a relative path
(so the executables can be moved together, but not
seperately); a @scheme[#f] value (the default) means that
seperately); a @racket[#f] value (the default) means that
absolute paths should be used (so the generated executable can
be moved).}
]
If the @scheme[#:collects-path] argument is @scheme[#f], then the
If the @racket[#:collects-path] argument is @racket[#f], then the
created executable maintains its built-in (relative) path to the main
@filepath{collects} directory---which will be the result of
@scheme[(find-system-path 'collects-dir)] when the executable is
@racket[(find-system-path 'collects-dir)] when the executable is
run---plus a potential list of other directories for finding library
collections---which are used to initialize the
@scheme[current-library-collection-paths] list in combination with
@racket[current-library-collection-paths] list in combination with
@envvar{PLTCOLLECTS} environment variable. Otherwise, the argument
specifies a replacement; it must be either a path, string, or
non-empty list of paths and strings. In the last case, the first path
@ -269,55 +270,55 @@ order, after the user-specific @filepath{collects} directory, but
before the main @filepath{collects} directory; then the search list is
combined with @envvar{PLTCOLLECTS}, if it is defined).
If the @scheme[#:launcher?] argument is @scheme[#t], then no
@scheme[module]s should be null, @scheme[literal-files] should be
null, @scheme[literal-sexp] should be @scheme[#f], and the platform
If the @racket[#:launcher?] argument is @racket[#t], then no
@racket[module]s should be null, @racket[literal-files] should be
null, @racket[literal-sexp] should be @racket[#f], and the platform
should be Windows or Mac OS X. The embedding executable is created in
such a way that @scheme[(find-system-path 'exec-file)] produces the
source MzScheme or MrEd path instead of the embedding executable (but
the result of @scheme[(find-system-path 'run-file)] is still the
such a way that @racket[(find-system-path 'exec-file)] produces the
source Racket or GRacket path instead of the embedding executable (but
the result of @racket[(find-system-path 'run-file)] is still the
embedding executable).
The @scheme[#:variant] argument indicates which variant of the
The @racket[#:variant] argument indicates which variant of the
original binary to use for embedding. The default is
@scheme[(system-type 'gc)]; see also
@scheme[current-launcher-variant].
@racket[(system-type 'gc)]; see also
@racket[current-launcher-variant].
The @scheme[#:compiler] argument is used to compile the source of
The @racket[#:compiler] argument is used to compile the source of
modules to be included in the executable (when a compiled form is not
already available). It should accept a single argument that is a
syntax object for a @scheme[module] form. The default procedure uses
@scheme[compile] parameterized to set the current namespace to
@scheme[expand-namespace].
syntax object for a @racket[module] form. The default procedure uses
@racket[compile] parameterized to set the current namespace to
@racket[expand-namespace].
The @scheme[#:expand-namespace] argument selects a namespace for
The @racket[#:expand-namespace] argument selects a namespace for
expanding extra modules (and for compiling using the default
@scheme[compile-proc]). Extra-module expansion is needed to detect
@racket[compile-proc]). Extra-module expansion is needed to detect
run-time path declarations in included modules, so that the path
resolutions can be directed to the current locations (and, ultimately,
redirected to copies in a distribution).
The @scheme[#:src-filter] argument takes a path and returns true if
The @racket[#:src-filter] argument takes a path and returns true if
the corresponding file source should be included in the embedding
executable in source form (instead of compiled form), @scheme[#f]
otherwise. The default returns @scheme[#f] for all paths. Beware that
executable in source form (instead of compiled form), @racket[#f]
otherwise. The default returns @racket[#f] for all paths. Beware that
the current output port may be redirected to the result executable
when the filter procedure is called.
If the @scheme[#:on-extension] argument is a procedure, the procedure
If the @racket[#:on-extension] argument is a procedure, the procedure
is called when the traversal of module dependencies arrives at an
extension (i.e., a DLL or shared object). The default, @scheme[#f],
extension (i.e., a DLL or shared object). The default, @racket[#f],
causes a reference to a single-module extension (in its current
location) to be embedded into the executable. The procedure is called
with two arguments: a path for the extension, and a @scheme[#f] (for
with two arguments: a path for the extension, and a @racket[#f] (for
historical reasons).
The @scheme[#:get-extra-imports] argument takes a source pathname and
The @racket[#:get-extra-imports] argument takes a source pathname and
compiled module for each module to be included in the executable. It
returns a list of quoted module paths (absolute, as opposed to
relative to the module) for extra modules to be included in the
executable in addition to the modules that the source module
@scheme[require]s. For example, these modules might correspond to
@racket[require]s. For example, these modules might correspond to
reader extensions needed to parse a module that will be included as
source, as long as the reader is referenced through an absolute module
path.}
@ -336,7 +337,7 @@ path.}
[variant (one-of/c 'cgc '3m) (system-type 'gc)])
void?]{
Old (keywordless) interface to @scheme[create-embedding-executable].}
Old (keywordless) interface to @racket[create-embedding-executable].}
@defproc[(write-module-bundle [verbose? any/c]
@ -346,29 +347,29 @@ Old (keywordless) interface to @scheme[create-embedding-executable].}
[literal-sexp any/c])
void?]{
Like @scheme[make-embedding-executable], but the module bundle is
Like @racket[make-embedding-executable], but the module bundle is
written to the current output port instead of being embedded into an
executable. The output of this function can be @scheme[read] to load
and instantiate @scheme[mod-list] and its dependencies, adjust the
executable. The output of this function can be @racket[read] to load
and instantiate @racket[mod-list] and its dependencies, adjust the
module name resolver to find the newly loaded modules, evaluate the
forms included from @scheme[literal-files], and finally evaluate
@scheme[literal-sexpr]. The @scheme[read-accept-compiled] parameter
forms included from @racket[literal-files], and finally evaluate
@racket[literal-sexpr]. The @racket[read-accept-compiled] parameter
must be true to read the stream.}
@defproc[(embedding-executable-is-directory? [mred? any/c]) boolean]{
Indicates whether MzScheme/MrEd executables for the current platform
Indicates whether Racket/GRacket executables for the current platform
correspond to directories from the user's perspective. The result is
currently @scheme[#f] for all platforms.}
currently @racket[#f] for all platforms.}
@defproc[(embedding-executable-is-actually-directory? [mred? any/c])
boolean?]{
Indicates whether MzScheme/MrEd executables for the current platform
actually correspond to directories. The result is @scheme[#t] under
Mac OS X when @scheme[mred?] is @scheme[#t], @scheme[#f] otherwise.}
Indicates whether Racket/GRacket executables for the current platform
actually correspond to directories. The result is @racket[#t] under
Mac OS X when @racket[mred?] is @racket[#t], @racket[#f] otherwise.}
@defproc[(embedding-executable-put-file-extension+style+filters [mred? any/c])
@ -376,13 +377,13 @@ Mac OS X when @scheme[mred?] is @scheme[#t], @scheme[#f] otherwise.}
(listof (one-of/c 'packages 'enter-packages))
(listof (list/c string? string?)))]{
Returns three values suitable for use as the @scheme[extension],
@scheme[style], and @scheme[filters] arguments to @scheme[put-file],
Returns three values suitable for use as the @racket[extension],
@racket[style], and @racket[filters] arguments to @racket[put-file],
respectively.
If MzScheme/MrEd launchers for the current platform were directories
form the user's perspective, the @scheme[style] result is suitable for
use with @scheme[get-directory], and the @scheme[extension] result may
If Racket/GRacket launchers for the current platform were directories
form the user's perspective, the @racket[style] result is suitable for
use with @racket[get-directory], and the @racket[extension] result may
be a string indicating a required extension for the directory name. }
@ -400,7 +401,7 @@ Adds a suitable executable suffix, if it's not present already.}
@defsignature/splice[compiler:embed^ ()]{
Includes the identifiers provided by @schememodname[compiler/embed].}
Includes the identifiers provided by @racketmodname[compiler/embed].}
@; ----------------------------------------
@ -410,4 +411,4 @@ Includes the identifiers provided by @schememodname[compiler/embed].}
@defthing[compiler:embed@ unit?]{
A unit that imports nothing and exports @scheme[compiler:embed^].}
A unit that imports nothing and exports @racket[compiler:embed^].}

63
collects/scribblings/raco/exe.scrbl Normal file
View File

@ -0,0 +1,63 @@
#lang scribble/doc
@(require scribble/manual
"common.ss"
(for-label racket/runtime-path))
@title[#:tag "exe"]{@exec{raco exe}: Creating Stand-Alone Executables}
Compiled code produced by @exec{raco make} relies on Racket
executables to provide run-time support to the compiled code. However,
@exec{raco exe} can package code together with its run-time support to
form an executable, and @exec{raco distribute} can packaged the
executable into a distribution that works on other machines.
The @exec{raco make} command embeds a module, from source or byte
code, into a copy of the @exec{racket} 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} flag causes the program to be embedded in a copy of the
@exec{gracket} executable. If the embedded module refers to other
modules via @racket[require], then the other modules are also included
in the embedding executable.
For example, the command
@commandline{raco exe --gui hello.rkt}
produces either @filepath{hello.exe} (Windows), @filepath{hello.app}
(Mac OS X), or @filepath{hello} (Unix), which runs the same as running
the @filepath{hello.rkt} module in @exec{gracket}.
Library modules or other files that are referenced
dynamically---through @racket[eval], @racket[load], or
@racket[dynamic-require]---are not automatically embedded into the
created executable. Such modules can be explicitly included using the
@DFlag{lib} flag to @exec{raco exe}. Alternately, use
@racket[define-runtime-path] to embed references to the run-time files
in the executable; the files are then copied and packaged together
with the executable when creating a distribution (as described in
@secref["exe-dist"]).
Modules that are implemented directly by extensions---i.e., extensions
that are automatically loaded from @racket[(build-path "compiled"
"native" (system-library-subpath))] to satisfy a
@racket[require]---are treated like other run-time files: a generated
executable uses them from their original location, and they are copied
and packaged together when creating a distribution.
The @exec{raco exe} command works only with module-based programs. The
@racketmodname[compiler/embed] 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 @exec{racket}, @exec{gracket}, or
DrRacket. However, the executable depends on Racket shared libraries,
and possibly other run-time files declared via
@racket[define-runtime-path]. The executable can be packaged with
support libraries to create a distribution using @exec{raco
distribute}, as described in @secref["exe-dist"].
@; ----------------------------------------------------------------------
@include-section["exe-api.scrbl"]
@include-section["launcher.scrbl"]

22
collects/scribblings/mzc/ext.scrbl → collects/scribblings/raco/ext.scrbl
View File

@ -4,31 +4,31 @@
@title[#:tag "ext"]{Compiling to Native Code via C}
The @DFlag{extension}/@Flag{e} mode for @|mzc| is similar to the
@DFlag{zo} mode, except that the compiled form of the module is a
native-code shared library instead of bytecode. Native code is
generated with the help of the host system's C compiler. This mode is
rarely useful, because the just-in-time (JIT) compiler that is built
into PLT Scheme provides better performance with lower overhead on the
platforms where it is supported (see @secref[#:doc '(lib
"scribblings/guide/guide.scrbl") "performance"]).
The @DFlag{extension}/@Flag{e} mode for @exec{raco ctool} is similar
to the @exec{raco make --zo} (see @secref["zo"]), except that the
compiled form of the module is a native-code shared library instead of
bytecode. Native code is generated with the help of the host system's
C compiler. This mode is rarely useful, because the just-in-time (JIT)
compiler that is built into Racket provides better performance
with lower overhead on the platforms where it is supported (see
@secref[#:doc '(lib "scribblings/guide/guide.scrbl") "performance"]).
As with @DFlag{zo} mode, the generated shared library by default is
placed in the same directory as the source file---which is not where
it will be found automatically when loading the source. Use the
@as-index{@DFlag{auto-dir}} flag to redirect the output to a
@scheme[(build-path "compiled" "native" (system-library-subpath))]
@racket[(build-path "compiled" "native" (system-library-subpath))]
subdirectory, where it will be found automatically when loading the
source file.
The @DFlag{c-source}/@Flag{c} mode for @|mzc| is like the
The @DFlag{c-source}/@Flag{c} mode for @exec{raco ctool} is like the
@DFlag{extension}/@Flag{e} mode, except that compilation stops with
the generation of C code.
All of the C compiler and linker flags that apply to @DFlag{cc} and
@DFlag{ld} mode also apply to @DFlag{extension} mode; see
@secref["cc"]. In addition, a few flag provide some control over the
Scheme-to-C compiler: @as-index{@DFlag{no-prop}},
Racket-to-C compiler: @as-index{@DFlag{no-prop}},
@as-index{@DFlag{inline}}, @as-index{@DFlag{no-prim}},
@as-index{@DFlag{stupid}},
@as-index{@DFlag{unsafe-disable-interrupts}},

3
collects/scribblings/raco/info.rkt Normal file
View File

@ -0,0 +1,3 @@
#lang setup/infotab
(define scribblings '(("raco.scrbl" (multi-page) (tool 50))))

40
collects/scribblings/setup-plt/info.scrbl → collects/scribblings/raco/info.scrbl
View File

@ -4,17 +4,17 @@
string-constants
setup/getinfo))
@title[#:tag "info.ss"]{@filepath{info.ss} File Format}
@title[#:tag "info.rkt"]{@filepath{info.rkt} File Format}
@defmodulelang[setup/infotab]
In each collection, a special module file @filepath{info.ss} provides
In each collection, a special module file @filepath{info.rkt} provides
general information about a collection for use by various tools. For
example, an @filepath{info.ss} file specifies how to build the
example, an @filepath{info.rkt} file specifies how to build the
documentation for a collection, and it lists plug-in tools for
DrScheme that the collection provides.
DrRacket or commands for @exec{raco} that the collection provides.
Although an @filepath{info.ss} file contains a module declaration, the
Although an @filepath{info.rkt} file contains a module declaration, the
declaration has a highly constrained form. It must match the following
grammar of @scheme[_info-module]:
@ -28,8 +28,11 @@ grammar of @scheme[_info-module]:
[info-module (module info intotab-mod-path
(define id info-expr)
...)]
[intotab-mod-path (lib "infotab.ss" "setup")
setup/infotab]
[intotab-mod-path setup/infotab
(lib "setup/infotab.ss")
(lib "setup/infotab.rkt")
(lib "infotab.rkt" "setup")
(lib "infotab.ss" "setup")]
[info-expr (quote datum)
(quasiquote datum)
(info-primitive info-expr ...)
@ -45,27 +48,20 @@ grammar of @scheme[_info-module]:
system-library-subpath]
]
For example, the following declaration could be the @filepath{info.ss}
library of the @filepath{help} collection. It contains definitions for
three info tags, @scheme[name], @scheme[mzscheme-launcher-libraries], and
@scheme[mzscheme-launcher-names].
For example, the following declaration could be the @filepath{info.rkt}
library of the @filepath{games} collection. It contains definitions for
three info tags, @scheme[name], @scheme[racket-launcher-libraries], and
@scheme[racket-launcher-names].
@schememod[
setup/infotab
(define name "Help")
(define mzscheme-launcher-libraries '("help.ss"))
(define mzscheme-launcher-names '("PLT Help"))
(define name "Games")
(define gracket-launcher-libraries '("main.rkt"))
(define gracket-launcher-names '("PLT Games"))
]
As illustrated in this example, an @filepath{info.ss} file can use
As illustrated in this example, an @filepath{info.rkt} file can use
@hash-lang[] notation, but only with the @schememodname[setup/infotab]
language.
@;{
The @scheme[name] tag is required for @exec{setup-plt} to recognize
the collection and compile its files to bytecode. Similarly, an
@filepath{info.ss} file in a sub-directory of a collection causes the
sub-directory's files to be compiled.
;}
See also @scheme[get-info] from @schememodname[setup/getinfo].

392
collects/scribblings/raco/launcher.scrbl Normal file
View File

@ -0,0 +1,392 @@
#lang scribble/doc
@(require scribble/manual
"common.ss"
(for-label racket/base
racket/unit
racket/contract
launcher/launcher
launcher/launcher-sig
launcher/launcher-unit
compiler/embed
racket/gui/base))
@title[#:tag "launcher"]{Installation-Specific Launchers}
@defmodule[launcher/launcher]
The @racketmodname[launcher/launcher] library provides functions for
creating @defterm{launchers}, which are similar to stand-alone
executables, but sometimes smaller because they depend permanently on
the local Racket installation. In the case of Unix, in particular,
a launcher is simply a shell script. The @exec{raco exe} command provides no
direct support for creating launchers.
@section{Creating Launchers}
@defproc[(make-gracket-launcher [args (listof string?)]
[dest path-string?]
[aux (listof (cons/c symbol? any/c)) null])
void?]{
Creates the launcher @racket[dest], which starts GRacket with the
command-line arguments specified as strings in @racket[args]. Extra
arguments passed to the launcher at run-time are appended (modulo
special Unix/X flag handling, as described below) to this list and
passed on to GRacket. If @racket[dest] exists already, as either a file
or directory, it is replaced.
The optional @racket[aux] argument is an association list for
platform-specific options (i.e., it is a list of pairs where the first
element of the pair is a key symbol and the second element is the
value for that key). See also @racket[build-aux-from-path]. See
@racket[create-embedding-executable] for a list that applies to both
stand-alone executables and launchers under Windows and Mac OS X GRacket;
the following additional associations apply to launchers:
@itemize[
@item{@racket['independent?] (Windows) --- a boolean; @racket[#t]
creates an old-style launcher that is independent of the
MzRacket or GRacket binary, like @exec{setup-plt.exe}. No other
@racket[aux] associations are used for an old-style launcher.}
@item{@racket['exe-name] (Mac OS X, @racket['script-3m] or
@racket['script-cgc] variant) --- provides the base name for a
@racket['3m]-/@racket['cgc]-variant launcher, which the script
will call ignoring @racket[args]. If this name is not provided,
the script will go through the GRacket executable as usual.}
@item{@racket['relative?] (all platforms) --- a boolean, where
@racket[#t] means that the generated launcher should find the
base GRacket executable through a relative path.}
]
For Unix/X, the script created by @racket[make-mred-launcher] detects
and handles X Windows flags specially when they appear as the initial
arguments to the script. Instead of appending these arguments to the
end of @racket[args], they are spliced in after any X Windows flags
already listed listed in @racket[args]. The remaining arguments (i.e.,
all script flags and arguments after the last X Windows flag or
argument) are then appended after the spliced @racket[args].}
@defproc[(make-racket-launcher [args (listof string?)]
[dest path-string?]
[aux (listof (cons/c symbol? any/c)) null])
void?]{
Like @racket[make-gracket-launcher], but for starting Racket. Under Mac
OS X, the @racket['exe-name] @racket[aux] association is ignored.}
@defproc[(make-gracket-program-launcher [file string?]
[collection string?]
[dest path-string?])
void?]{
Calls @racket[make-gracket-launcher] with arguments that start the
GRacket program implemented by @racket[file] in @racket[collection]:
@racket[(list "-l-" (string-append collection "/" file))]. The
@racket[_aux] argument to @racket[make-gracket-launcher] is generated
by stripping the suffix (if any) from @racket[file], adding it to the
path of @racket[collection], and passing the result to
@racket[build-aux-from-path].}
@defproc[(make-racket-program-launcher [file string?]
[collection string?]
[dest path-string?])
void?]{
Like @racket[make-gracket-program-launcher], but for
@racket[make-racket-launcher].}
@defproc[(install-gracket-program-launcher [file string?]
[collection string?]
[name string?])
void?]{
Same as
@racketblock[
(make-gracket-program-launcher
file collection
(gracket-program-launcher-path name))
]}
@defproc[(install-racket-program-launcher [file string?]
[collection string?]
[name string?])
void?]{
Same as
@racketblock[
(make-racket-program-launcher
file collection
(racket-program-launcher-path name))
]}
@deftogether[(
@defproc[(make-mred-launcher [args (listof string?)]
[dest path-string?]
[aux (listof (cons/c symbol? any/c)) null])
void?]
@defproc[(make-mred-program-launcher [file string?]
[collection string?]
[dest path-string?])
void?]
@defproc[(install-mred-program-launcher [file string?]
[collection string?]
[name string?])
void?]
)]{
Backward-compatible version of @racket[make-gracket-launcher], etc.,
that adds @racket["-I" "scheme/gui/init"] to the start of the
command-line arguments.}
@deftogether[(
@defproc[(make-mzscheme-launcher [args (listof string?)]
[dest path-string?]
[aux (listof (cons/c symbol? any/c)) null])
void?]
@defproc[(make-mzscheme-program-launcher [file string?]
[collection string?]
[dest path-string?])
void?]
@defproc[(install-mzscheme-program-launcher [file string?]
[collection string?]
[name string?])
void?]
)]{
Backward-compatible version of @racket[make-racket-launcher], etc.,
that adds @racket["-I" "scheme/init"] to the start of the command-line
arguments.}
@; ----------------------------------------------------------------------
@section{Launcher Path and Platform Conventions}
@defproc[(gracket-program-launcher-path [name string?]) path?]{
Returns a pathname for an executable in the Racket installation
called something like @racket[name]. For Windows, the @filepath{.exe}
suffix is automatically appended to @racket[name]. For Unix,
@racket[name] is changed to lowercase, whitespace is changed to
@litchar{-}, and the path includes the @filepath{bin} subdirectory of
the Racket installation. For Mac OS X, the @filepath{.app} suffix
is appended to @racket[name].}
@defproc[(racket-program-launcher-path [name string?]) path?]{
Returns the same path as @racket[(gracket-program-launcher-path name)]
for Unix and Windows. For Mac OS X, the result is the same as for
Unix.}
@defproc[(gracket-launcher-is-directory?) boolean?]{
Returns @racket[#t] if GRacket launchers for the current platform are
directories from the user's perspective. For all currently supported
platforms, the result is @racket[#f].}
@defproc[(racket-launcher-is-directory?) boolean?]{
Like @racket[gracket-launcher-is-directory?], but for Racket
launchers.}
@defproc[(gracket-launcher-is-actually-directory?) boolean?]{
Returns @racket[#t] if GRacket launchers for the current platform are
implemented as directories from the filesystem's perspective. The
result is @racket[#t] for Mac OS X, @racket[#f] for all other
platforms.}
@defproc[(racket-launcher-is-actually-directory?) boolean?]{
Like @racket[gracket-launcher-is-actuall-directory?], but for Racket
launchers. The result is @racket[#f] for all platforms.}
@defproc[(gracket-launcher-add-suffix [path-string? path]) path?]{
Returns a path with a suitable executable suffix added, if it's not
present already.}
@defproc[(racket-launcher-add-suffix [path-string? path]) path?]{
Like @racket[gracket-launcher-add-suffix], but for Racket launchers.}
@defproc[(gracket-launcher-put-file-extension+style+filters)
(values (or/c string? false/c)
(listof (one-of/c 'packages 'enter-packages))
(listof (list/c string? string?)))]{
Returns three values suitable for use as the @racket[extension],
@racket[style], and @racket[filters] arguments to @racket[put-file],
respectively.
If GRacket launchers for the current platform were directories form the
user's perspective, the @racket[style] result is suitable for use with
@racket[get-directory], and the @racket[extension] result may be a
string indicating a required extension for the directory name. }
@defproc[(racket-launcher-put-file-extension+style+filters)
(values (or/c string? false/c)
(listof (one-of/c 'packages 'enter-packages))
(listof (list/c string? string?)))]{
Like @racket[gracket-launcher-get-file-extension+style+filters], but for
Racket launchers.}
@deftogether[(
@defproc[(mred-program-launcher-path [name string?]) path?]
@defproc[(mred-launcher-is-directory?) boolean?]
@defproc[(mred-launcher-is-actually-directory?) boolean?]
@defproc[(mred-launcher-add-suffix [path-string? path]) path?]
@defproc[(mred-launcher-put-file-extension+style+filters)
(values (or/c string? false/c)
(listof (one-of/c 'packages 'enter-packages))
(listof (list/c string? string?)))]
)]{
Backward-compatible aliases for
@racket[gracket-program-launcher-path], etc.}
@deftogether[(
@defproc[(mzscheme-program-launcher-path [name string?]) path?]
@defproc[(mzscheme-launcher-is-directory?) boolean?]
@defproc[(mzscheme-launcher-is-actually-directory?) boolean?]
@defproc[(mzscheme-launcher-add-suffix [path-string? path]) path?]
@defproc[(mzscheme-launcher-put-file-extension+style+filters)
(values (or/c string? false/c)
(listof (one-of/c 'packages 'enter-packages))
(listof (list/c string? string?)))]
)]{
Backward-compatible aliases for
@racket[racket-program-launcher-path], etc.}
@; ----------------------------------------------------------------------
@section{Launcher Configuration}
@defproc[(gracket-launcher-up-to-date? [dest path-string?]
[aux (listof (cons/c symbol? any/c))])
boolean?]{
Returns @racket[#t] if the GRacket launcher @racket[dest] does not need
to be updated, assuming that @racket[dest] is a launcher and its
arguments have not changed.}
@defproc[(racket-launcher-up-to-date? [dest path-string?]
[aux (listof (cons/c symbol? any/c))])
boolean?]{
Analogous to @racket[gracket-launcher-up-to-date?], but for a Racket
launcher.}
@defproc[(build-aux-from-path [path path-string?])
(listof (cons/c symbol? any/c))]{
Creates an association list suitable for use with
@racket[make-gracket-launcher] or @racket[create-embedding-executable].
It builds associations by adding to @racket[path] suffixes, such as
@filepath{.icns}, and checking whether such a file exists.
The recognized suffixes are as follows:
@itemize[
@item{@filepath{.icns} @'rarr @racket['icns] file for use under Mac
OS X}
@item{@filepath{.ico} @'rarr @racket['ico] file for use under
Windows}
@item{@filepath{.lch} @'rarr @racket['independent?] as @racket[#t]
(the file content is ignored) for use under Windows}
@item{@filepath{.creator} @'rarr @racket['creator] as the initial
four characters in the file for use under Mac OS X}
@item{@filepath{.filetypes} @'rarr @racket['file-types] as
@racket[read] content (a single S-expression), and
@racket['resource-files] as a list constructed by finding
@racket["CFBundleTypeIconFile"] entries in @racket['file-types]
(and filtering duplicates); for use under Mac OS X}
@item{@filepath{.utiexports} @'rarr @racket['uti-exports] as
@racket[read] content (a single S-expression); for use under
Mac OS X}
]}
@defparam[current-launcher-variant variant symbol?]{
A parameter that indicates a variant of Racket or GRacket to use for
launcher creation and for generating launcher names. The default is
the result of @racket[(system-type 'gc)]. Under Unix and Windows, the
possibilities are @racket['cgc] and @racket['3m]. Under Mac OS X, the
@racket['script-3m] and @racket['script-cgc] variants are also
available for GRacket launchers.}
@defproc[(available-gracket-variants) (listof symbol?)]{
Returns a list of symbols corresponding to available variants of GRacket
in the current Racket installation. The list normally includes at
least one of @racket['3m] or @racket['cgc]--- whichever is the result
of @racket[(system-type 'gc)]---and may include the other, as well as
@racket['script-3m] and/or @racket['script-cgc] under Mac OS X.}
@defproc[(available-racket-variants) (listof symbol?)]{
Returns a list of symbols corresponding to available variants of
Racket in the current Racket installation. The list normally
includes at least one of @racket['3m] or @racket['cgc]---whichever is
the result of @racket[(system-type 'gc)]---and may include the other.}
@deftogether[(
@defproc[(mred-launcher-up-to-date? [dest path-string?]
[aux (listof (cons/c symbol? any/c))])
boolean?]
@defproc[(mzscheme-launcher-up-to-date? [dest path-string?]
[aux (listof (cons/c symbol? any/c))])
boolean?]
@defproc[(available-mred-variants) (listof symbol?)]
@defproc[(available-mzscheme-variants) (listof symbol?)]
)]{
Backward-compatible aliases for
@racket[gracket-launcher-up-to-date?], etc.}
@; ----------------------------------------
@section{Launcher Creation Signature}
@defmodule[launcher/launcher-sig]
@defsignature/splice[launcher^ ()]{
Includes the identifiers provided by @racketmodname[launcher/launcher].}
@; ----------------------------------------
@section{Launcher Creation Unit}
@defmodule[launcher/launcher-unit]
@defthing[launcher@ unit?]{
A unit that imports nothing and exports @racket[launcher^].}

371
collects/scribblings/raco/make.scrbl Normal file
View File

@ -0,0 +1,371 @@
#lang scribble/doc
@(require scribble/manual
scribble/bnf
"common.ss"
(for-label racket/base
racket/include
racket/contract
compiler/cm
compiler/cm-accomplice))
@title[#:tag "make"]{@exec{raco make}: Compiling Source to Bytecode}
The @exec{raco make} command accept filenames for Racket modules to be
compiled to bytecode format. Modules are re-compiled only if the
source Racket file is newer than the bytecode file and has a different
SHA-1 hash, or if any imported module is recompiled or has a different
SHA-1 hash for its compiled form plus dependencies.
@; ----------------------------------------------------------------------
@section{Bytecode Files}
A file @filepath{@nonterm{name}.@nonterm{ext}} is compiled to bytecode
that is saved as @filepath{compiled/@nonterm{name}_@nonterm{ext}.zo}
relative to the file. As a result, the bytecode file is normally used
automatically when @filepath{@nonterm{name}.@nonterm{ext}} is required
as a module, since the underlying @racket[load/use-compiled] operation
detects such a bytecode file.
For example, in a directory that contains the following files:
@itemize[
@item{@filepath{a.rkt}:
@racketmod[
racket
(require "b.rkt" "c.rkt")
(+ b c)
]}
@item{@filepath{b.rkt}:
@racketmod[
racket
(provide b)
(define b 1)
]}
@item{@filepath{c.rkt}:
@racketmod[
racket
(provide c)
(define c 1)
]}]
then
@commandline{raco make a.rkt}
triggers the creation of @filepath{compiled/a_rkt.zo},
@filepath{compiled/b_rkt.zo}, and @filepath{compiled/c_rkt.zo}.
A subsequent
@commandline{racket a.rkt}
loads bytecode from the generated @filepath{.zo} files, paying
attention to the @filepath{.rkt} sources only to confirm that each
@filepath{.zo} file has a later timestamp.
In contrast,
@commandline{racket b.rkt c.rkt}
would create only @filepath{compiled/b_rkt.zo} and
@filepath{compiled/c_rkt.zo}, since neither @filepath{b.rkt} nor
@filepath{c.rkt} imports @filepath{a.rkt}.
@; ----------------------------------------------------------------------
@section{Dependency Files}
In addition to a bytecode file, @exec{raco make} creates a file
@filepath{compiled/@nonterm{name}_@nonterm{ext}.dep} that records
dependencies of the compiled module on other module files and the
source file's SHA-1 hash. Using this dependency information, a
re-compilation request via @exec{raco make} can consult both the
source file's timestamp/hash and the timestamps/hashes for the
bytecode of imported modules. Furthermore, imported modules are
themselves compiled as necessary, including updating the bytecode and
dependency files for the imported modules, transitively.
Continuing the @exec{raco make a.rkt} example from the previous
section, the @exec{raco make} command creates
@filepath{compiled/a_rkt.dep}, @filepath{compiled/b_rkt.dep}, and
@filepath{compiled/c_rkt.dep} at the same time as the @filepath{.zo}
files. The @filepath{compiled/a_rkt.dep} file records the dependency
of @filepath{a.rkt} on @filepath{b.rkt}, @filepath{c.rkt} and the
@racketmodname[racket] library. If the @filepath{b.rkt} file is
modified (so that its timestamp and SHA-1 hash changes), then running
@commandline{raco make a.rkt}
again rebuilds @filepath{compiled/a_rkt.zo} and
@filepath{compiled/b_rkt.zo}.
For module files that are within library collections, @exec{raco
setup} uses the same @filepath{.zo} and @filepath{.dep} conventions
and files as @exec{raco make}, so the two tools can be used together.
@; ----------------------------------------------------------------------
@section{API for Making Bytecode}
@defmodule[compiler/cm]{The @racketmodname[compiler/cm] module
implements the compilation and dependency management used by
@exec{raco make} and @exec{raco setup}.}
@defproc[(make-compilation-manager-load/use-compiled-handler)
(path? (or/c symbol? false/c) . -> . any)]{
Returns a procedure suitable as a value for the
@racket[current-load/use-compiled] parameter. The returned procedure
passes it arguments on to the @racket[current-load/use-compiled]
procedure that is installed when
@racket[make-compilation-manager-load/use-compiled-handler] is called,
but first it automatically compiles a source file to a @filepath{.zo}
file if
@itemize[
@item{the file is expected to contain a module (i.e., the second
argument to the handler is a symbol);}
@item{the value of each of @racket[(current-eval)],
@racket[(current-load)], and @racket[(namespace-module-registry
(current-namespace))] is the same as when
@racket[make-compilation-manager-load/use-compiled-handler] was
called;}
@item{the value of @racket[use-compiled-file-paths] contains the
first path that was present when
@racket[make-compilation-manager-load/use-compiled-handler] was
called;}
@item{the value of @racket[current-load/use-compiled] is the result
of this procedure; and}
@item{one of the following holds:
@itemize[
@item{the source file is newer than the @filepath{.zo} file in the
first sub-directory listed in @racket[use-compiled-file-paths]
(at the time that
@racket[make-compilation-manager-load/use-compiled-handler]
was called), and either no @filepath{.dep} file exists or it
records a source-file SHA-1 hash that differs from the current
version and source-file SHA-1 hash;}
@item{no @filepath{.dep} file exists next to the @filepath{.zo}
file;}
@item{the version recorded in the @filepath{.dep} file does not
match the result of @racket[(version)];}
@item{one of the files listed in the @filepath{.dep} file has a
@filepath{.zo} timestamp newer than the target @filepath{.zo},
and the combined hashes of the dependencies recorded in the
@filepath{.dep} file does not match the combined hash recorded
in the @filepath{.dep} file.}
]}
]
If SHA-1 hashes override a timestamp-based decision to recompile the
file, then the target @filepath{.zo} file's timestamp is updated to
the current time.
After the handler procedure compiles a @filepath{.zo} file, it creates
a corresponding @filepath{.dep} file that lists the current version
and the identification of every file that is directly
@racket[require]d by the module in the compiled file. Additional
dependencies can be installed during compilation via
@racketmodname[compiler/cm-accomplice]. The @filepath{.dep} file also
records the SHA-1 hash of the module's source, and it records a
combined SHA-1 hash of all of the dependencies that includes their
recursive dependencies.
The handler caches timestamps when it checks @filepath{.dep} files,
and the cache is maintained across calls to the same handler. The
cache is not consulted to compare the immediate source file to its
@filepath{.zo} file, which means that the caching behavior is
consistent with the caching of the default module name resolver (see
@racket[current-module-name-resolver]).
If @racket[use-compiled-file-paths] contains an empty list when
@racket[make-compilation-manager-load/use-compiled-handler] is called,
then @racket[exn:fail:contract] exception is raised.
@emph{Do not} install the result of
@racket[make-compilation-manager-load/use-compiled-handler] when the
current namespace contains already-loaded versions of modules that may
need to be recompiled---unless the already-loaded modules are never
referenced by not-yet-loaded modules. References to already-loaded
modules may produce compiled files with inconsistent timestamps and/or
@filepath{.dep} files with incorrect information.}
@defproc[(managed-compile-zo [file path-string?]
[read-src-syntax (any/c input-port? . -> . syntax?) read-syntax])
void?]{
Compiles the given module source file to a @filepath{.zo}, installing
a compilation-manager handler while the file is compiled (so that
required modules are also compiled), and creating a @filepath{.dep} file
to record the timestamps of immediate files used to compile the source
(i.e., files @racket[require]d in the source).
If @racket[file] is compiled from source, then
@racket[read-src-syntax] is used in the same way as
@racket[read-syntax] to read the source module. The normal
@racket[read-syntax] is used for any required files, however.}
@defboolparam[trust-existing-zos trust?]{
A parameter that is intended for use by @exec{setup-plt} when
installing with pre-built @filepath{.zo} files. It causes a
compilation-manager @racket[load/use-compiled] handler to ``touch''
out-of-date @filepath{.zo} files instead of re-compiling from source.}
@defproc[(make-caching-managed-compile-zo
[read-src-syntax (any/c input-port? . -> . syntax?)])
(path-string? . -> . void?)]{
Returns a procedure that behaves like @racket[managed-compile-zo]
(providing the same @racket[read-src-syntax] each time), but a cache
of timestamp information is preserved across calls to the procedure.}
@defparam[manager-compile-notify-handler notify (path? . -> . any)]{
A parameter for a procedure of one argument that is called whenever a
compilation starts. The argument to the procedure is the file's path.}
@defparam[manager-trace-handler notify (string? . -> . any)]{
A parameter for a procedure of one argument that is called to report
compilation-manager actions, such as checking a file. The argument to
the procedure is a string.}
@defparam[manager-skip-file-handler proc (-> path? (or/c (cons/c number? promise?) #f))]{
A parameter whose value is called for each file that is loaded and
needs recompilation. If the procedure returns a pair, then the file
is skipped (i.e., not compiled); the number in the pair is used as
the timestamp for the file's bytecode, and the promise may be
@racket[force]d to obtain a string that is used as hash of the
compiled file plus its dependencies. If the procedure returns
@racket[#f], then the file is compiled as usual. The default is
@racket[(lambda (x) #f)].}
@defproc[(file-stamp-in-collection [p path?]) (or/c (cons/c number? promise?) #f)]{
Calls @racket[file-stamp-in-paths] with @racket[p] and
@racket[(current-library-collection-paths)].}
@defproc[(file-stamp-in-paths [p path?] [paths (listof path?)]) (or/c (cons/c number? promise?) #f)]{
Returns the file-modification date and @racket[delay]ed hash of
@racket[p]or its bytecode form (i.e., @filepath{.zo} file), whichever
exists and is newer, if @racket[p] is an extension of any path in
@racket[paths] (i.e., exists in the directory, a subdirectory,
etc.). Otherwise, the result is @racket[#f].
This function is intended for use with @racket[manager-skip-file-handler].}
@defproc[(get-file-sha1 [p path?]) (or/c string? #f)]{
Computes a SHA-1 hash for the file @racket[p]; the result is
@racket[#f] if @racket[p] cannot be opened.}
@defproc[(get-compiled-file-sha1 [p path?]) (or/c string? #f)]{
Computes a SHA-1 hash for the bytecode file @racket[p], appending any
dependency-describing hash available from a @filepath{.dep} file when
available (i.e., the suffix on @racket[p] is replaced by
@filepath{.dep} to locate dependency information). The result is
@racket[#f] if @racket[p] cannot be opened.}
@; ----------------------------------------------------------------------
@section{Compilation Manager Hook for Syntax Transformers}
@defmodule[compiler/cm-accomplice]
@defproc[(register-external-file [file (and path? complete-path?)]) void?]{
Logs a message (see @racket[log-message]) at level @racket['info]. The
message data is a @racketidfont{file-dependency} prefab structure type
with one field whose value is @racket[file].
A compilation manager implemented by @racketmodname[compiler/cm] looks
for such messages to register an external dependency. The compilation
manager records (in a @filepath{.dep} file) the path as contributing
to the implementation of the module currently being
compiled. Afterward, if the registered file is modified, the
compilation manager will know to recompile the module.
The @racket[include] macro, for example, calls this procedure with the
path of an included file as it expands an @racket[include] form.}
@; ----------------------------------------------------------------------
@section[#:tag "zo"]{Compiling to Raw Bytecode}
The @DFlag{zo}/@Flag{z} mode for @exec{raco make} is an improverished
form of the compilation, because it does not track import
dependencies. It does, however, support compilation of non-module
source.
By default, the generated bytecode is placed in the same directory as
the source file---which is not where it will be found automatically
when loading the source. Use the @as-index{@DFlag{auto-dir}} flag to
redirect the output to a @filepath{compiled} subdirectory, where it
will be found automatically when loading the source file.
Outside of a module, top-level @racket[define-syntaxes],
@racket[module], @racket[#%require],
@racket[define-values-for-syntax], and and @racket[begin] expressions
are handled specially by @exec{raco make --zo}: the compile-time
portion of the expression is evaluated, because it might affect later
expressions. (The @Flag{m} or @DFlag{module} flag turns off this
special handling.)
For example, when compiling the file containing
@racketblock[
(require racket/class)
(define f (class% object% (super-new)))
]
the @racket[class] form from the @racketmodname[racket/class] library
must be bound in the compilation namespace at compile time. Thus, the
@racket[require] expression is both compiled (to appear in the output
code) and evaluated (for further computation).
Many definition forms expand to @racket[define-syntaxes]. For example,
@racket[define-signature] expands to @racket[define-syntaxes]. In
@racket[--zo] mode, @exec{raco make --zo} detects
@racket[define-syntaxes] and other expressions after expansion, so
top-level @racket[define-signature] expressions affect the compilation
of later expressions, as a programmer would expect.
In contrast, a @racket[load] or @racket[eval] expression in a source
file is compiled---but @emph{not evaluated!}---as the source file is
compiled. Even if the @racket[load] expression loads syntax or
signature definitions, these will not be loaded as the file is
compiled. The same is true of application expressions that affect the
reader, such as @racket[(read-case-sensitive #t)]. The @Flag{p} or
@DFlag{prefix} flag for @exec{raco make} takes a file and loads it before
compiling the source files specified on the command line.
In general, a better solution is to put all code to compile into a
module and use @exec{raco make} in its default mode.

9
collects/scribblings/raco/planet.scrbl Normal file
View File

@ -0,0 +1,9 @@
#lang scribble/doc
@(require scribble/manual
"common.ss")
@title[#:tag "planet"]{@exec{raco planet}: Automatic Package Distribution}
See @other-manual['(lib "planet/planet.scrbl")] for information on the
@exec{raco planet} command, which is used for managing packages that
can be automatically downloaded and installed from the @|PLaneT| server.

318
collects/scribblings/raco/plt.scrbl Normal file
View File

@ -0,0 +1,318 @@
#lang scribble/doc
@(require scribble/manual
"common.ss"
(for-label racket/base))
@title[#:tag "plt"]{@exec{raco pack}: Packaging Library Collections}
@margin-note{Before creating a @filepath{.plt} archive to distribute,
consider instead posting your package on
@link["http://planet.racket-lang.org/"]{@|PLaneT|}.}
The @exec{raco pack} command creates an archive for distributing
library files to Racket users. A distribution archive usually has the
suffix @as-index{@filepath{.plt}}, which DrRacket recognizes as an
archive to provide automatic unpacking facilities. The @exec{raco
setup} command also supports @filepath{.plt} unpacking.
An archive contains the following elements:
@itemize[
@item{A set of files and directories to be unpacked, and flags
indicating whether they are to be unpacked relative to the Racket
add-ons directory (which is user-specific), the Racket installation
directory, or a user-selected directory.
The files and directories for an archive are provided on the command
line to @exec{raco pack}, either directly or in the form of
collection names when the @DFlag{collect} flag is used.
The @as-index{@DFlag{at-plt}} flag indicates that the files and
directories should be unpacked relative to the user's add-ons
directory, unless the user specifies the Racket installation
directory when unpacking. The @as-index{@DFlag{collection-plt}} flag
implies @DFlag{at-plt}. The @as-index{@DFlag{all-users}} flag
overrides @DFlag{at-plt}, and it indicates that the files and
directories should be unpacked relative to the Racket
installation directory, always.}
@item{A flag for each file indicating whether it overwrites an
existing file when the archive is unpacked; the default is to leave
the old file in place, but the @as-index{@DFlag{replace}} flag
enables replacing for all files in the archive.}
@item{A list of collections to be set-up (via @exec{raco setup})
after the archive is unpacked; the @as-index{@DPFlag{setup}} flag
adds a collection name to the archive's list, but each collection for
@DFlag{collection-plt} is added automatically.}
@item{A name for the archive, which is reported to the user by the
unpacking interface; the @as-index{@DFlag{plt-name}} flag sets the
archive's name, but a default name is determined automatically when
using @DFlag{collect}.}
@item{A list of required collections (with associated version
numbers) and a list of conflicting collections; the @exec{raco pack}
command always names the @filepath{racket} collection in the required
list (using the collection's pack-time version), @exec{raco pack}
names each packed collection in the conflict list (so that a
collection is not unpacked on top of a different version of the same
collection), and @exec{raco pack} extracts other requirements and
conflicts from the @filepath{info.rkt} files of collections when
using @DFlag{collect}.}
]
Specify individual directories and files for the archive when not
using @DFlag{collect}. Each file and directory must be specified with
a relative path. By default, if the archive is unpacked with DrRacket,
the user will be prompted for a target directory, and if @exec{raco
setup} is used to unpack the archive, the files and directories will
be unpacked relative to the current directory. If the @DFlag{at-plt}
flag is provided, the files and directories will be unpacked relative
to the user's Racket add-ons directory, instead. Finally, if the
@DFlag{all-users} flag is provided, the files and directories will be
unpacked relative to the Racket installation directory, instead.
Use the @DFlag{collect} flag to pack one or more collections;
sub-collections can be designated by using a @litchar{/} as a path
separator on all platforms. In this mode, @exec{raco pack}
automatically uses paths relative to the Racket installation or
add-ons directory for the archived files, and the collections will be
set-up after unpacking. In addition, @exec{raco pack} consults each
collection's @filepath{info.rkt} file, as described below, to
determine the set of required and conflicting collections. Finally,
@exec{raco pack} consults the first collection's @filepath{info.ss}
file to obtain a default name for the archive. For example, the
following command creates a @filepath{sirmail.plt} archive for
distributing a @filepath{sirmail} collection:
@commandline{raco pack --collect sirmail.plt sirmail}
When packing collections, @exec{raco pack} checks the following fields
of each collection's @filepath{info.rkt} file (see @secref["info.rkt"]):
@itemize[
@item{@racket[requires] --- A list of the form @racket[(list (list
_coll _vers) ...)] where each @racket[_coll] is a non-empty list of
relative-path strings, and each @racket[_vers] is a (possibly empty)
list of exact integers. The indicated collections must be installed
at unpacking time, with version sequences that match as much of the
version sequence specified in the corresponding @racket[vers].
A collection's version is indicated by a @racket[version] field in
it's @filepath{info.ss} file, and the default version is the empty list.
The version sequence generalized major and minor version numbers. For
example, version @racket['(2 5 4 7)] of a collection can be used when
any of @racket['()], @racket['(2)], @racket['(2 5)], @racket['(2 5
4)], or @racket['(2 5 4 7)] is required.}
@item{@racket[conflicts] --- A list of the form @racket[(list _coll
...)] where each @racket[_coll] is a non-empty list of relative-path
strings. The indicated collections must @emph{not} be installed at
unpacking time.}
]
For example, the @filepath{info.rkt} file in the @filepath{sirmail} collection
might contain the following @racket[info] declaration:
@racketmod[
setup/infotab
(define name "SirMail")
(define mred-launcher-libraries (list "sirmail.rkt"))
(define mred-launcher-names (list "SirMail"))
(define requires (list (list "mred")))
]
Then, the @filepath{sirmail.plt} file (created by the command-line
example above) will contain the name ``SirMail.'' When the archive is
unpacked, the unpacker will check that the @filepath{mred} collection
is installed, and that @filepath{mred} has the same version as when
@filepath{sirmail.plt} was created.
@; ----------------------------------------
@section{API for Packaging}
@defmodule[setup/pack]{Although the @exec{raco pack} command can be
used to create most @filepath{.plt} files, the
@racketmodname[setup/pack] library provides a more general API for
making @filepath{.plt} archives.}
@defproc[(pack-collections-plt
(dest path-string?)
(name string?)
(collections (listof (listof path-string?)))
[#:replace? replace? boolean? #f]
[#:at-plt-home? at-home? boolean? #f]
[#:test-plt-collects? test? boolean? #t]
[#:extra-setup-collections collection-list (listof path-string?) null]
[#:file-filter filter-proc (path-string? . -> . boolean?) std-filter]) void?]{
Creates the @filepath{.plt} file specified by the pathname @racket[dest],
using the @racket[name] as the name reported to @exec{raco setup}
as the archive's description.
The archive contains the collections listed in @racket[collections], which
should be a list of collection paths; each collection path is, in
turn, a list of relative-path strings.
If the @racket[#:replace?] argument is @racket[#f], then attempting to
unpack the archive will report an error when any of the collections exist
already, otherwise unpacking the archive will overwrite an existing
collection.
If the @racket[#:at-plt-home?] argument is @racket[#t], then the archived
collections will be installed into the Racket installation directory
instead of the user's directory if the main @filepath{collects} directory
is writable by the user. If the @racket[#:test-plt-collects?] argument is
@racket[#f] (the default is @racket[#t]) and the @racket[#:at-plt-home?] argument
is @racket[#t], then installation fails if the main @filepath{collects}
directory is not writable.
The optional @racket[#:extra-setup-collections] argument is a list of
collection paths that are not included in the archive, but are
set-up when the archive is unpacked.
The optional @racket[#:file-filter] argument is the same as for
@racket[pack-plt].}
@defproc[(pack-collections
(dest path-string?)
(name string?)
(collections (listof (listof path-string?)))
(replace? boolean?)
(extra-setup-collections (listof path-string?))
[filter (path-string? . -> . boolean?) std-filter]
[at-plt-home? boolean? #f]) void?]{
Old, keywordless variant of @racket[pack-collections-plt] for backward compatibility.}
@defproc[(pack-plt
(dest path-string?)
(name string?)
(paths (listof path-string?))
[#:file-filter filter-proc
(path-string? . -> . boolean?) std-filter]
[#:encode? encode? boolean? #t]
[#:file-mode file-mode-sym symbol? 'file]
[#:unpack-unit unit200-expr any/c #f]
[#:collections collection-list (listof path-string?) null]
[#:plt-relative? plt-relative? any/c #f]
[#:at-plt-home? at-plt-home? any/c #f]
[#:test-plt-dirs dirs (or/c (listof path-string?) false/c) #f]
[#:requires mod-and-version-list
(listof (listof path-string?)
(listof exact-integer?))
null]
[#:conflicts mod-list
(listof (listof path-string?)) null])
void?]{
Creates the @filepath{.plt} file specified by the pathname @racket[dest],
using the string @racket[name] as the name reported to @exec{raco setup} as
the archive's description. The @racket[paths] argument must be a list of
relative paths for directories and files; the contents of these files and
directories will be packed into the archive.
The @racket[#:file-filter] procedure is called with the relative path of each
candidate for packing. If it returns @racket[#f] for some path, then that
file or directory is omitted from the archive. If it returns @racket['file]
or @racket['file-replace] for a file, the file is packed with that mode,
rather than the default mode. The default is @racket[std-filter].
If the @racket[#:encode?] argument is @racket[#f], then the output archive
is in raw form, and still must be gzipped and mime-encoded (in that
order). The default value is @racket[#t].
The @racket[#:file-mode] argument must be @racket['file] or
@racket['file-replace], indicating the default mode for a file in the
archive. The default is @racket['file].
The @racket[#:unpack-unit] argument is usually
@racket[#f]. Otherwise, it must be an S-expression for a
@racket[mzlib/unit200]-style unit that performs the work of
unpacking; see @secref["format-of-.plt-archives"] more information
about the unit. If the @racket[#:unpack-unit] argument is
@racket[#f], an appropriate unpacking unit is generated.
The @racket[#:collections] argument is a list of collection paths to be
compiled after the archive is unpacked. The default is the @racket[null].
If the @racket[#:plt-relative?] argument is true (the default is
@racket[#f]), the archive's files and directories are to be unpacked
relative to the user's add-ons directory or the Racket installation
directories, depending on whether the @racket[#:at-plt-home?]
argument is true and whether directories specified by
@racket[#:test-plt-dirs] are writable by the user.
If the @racket[#:at-plt-home?] argument is true (the default is
@racket[#f]), then @racket[#:plt-relative?] must be true, and the
archive is unpacked relative to the Racket installation directory. In
that case, a relative path that starts with @filepath{collects} is
mapped to the installation's main @filepath{collects} directory, and
so on, for the following the initial directory names:
@itemize[
@item{@filepath{collects}}
@item{@filepath{doc}}
@item{@filepath{lib}}
@item{@filepath{include}}
]
If @racket[#:test-plt-dirs] is a @racket[list], then
@racket[#:at-plt-home?] must be @racket[#t]. In that case, when the archive
is unpacked, if any of the relative directories in the
@racket[#:test-plt-dirs] list is unwritable by the current user, then the
archive is unpacked in the user's add-ons directory after all.
The @racket[#:requires] argument should have the shape @racket[(list
(list _coll-path _version) _...)] where each
@racket[_coll-path] is a non-empty list of relative-path
strings, and each @@racket[_version] is a (possibly empty) list
of exact integers. The indicated collections must be installed
at unpacking time, with version sequences that match as much of
the version sequence specified in the corresponding
@@racket[_version]. A collection's version is indicated by the
@racketidfont{version} field of its @filepath{info.ss} file.
The @racket[#:conflicts] argument should have the shape
@racket[(list _coll-path _...)] where each @racket[_coll-path]
is a non-empty list of relative-path strings. The indicated
collections must @emph{not} be installed at unpacking time.}
@defproc[(pack
(dest path-string?)
(name string?)
(paths (listof path-string?))
(collections (listof path-string?))
[filter (path-string? . -> . boolean?) std-filter]
[encode? boolean? #t]
[file-mode symbol? 'file]
[unpack-unit boolean? #f]
[plt-relative? boolean? #t]
[requires (listof (listof path-string?)
(listof exact-integer?)) null]
[conflicts (listof (listof path-string?)) null]
[at-plt-home? boolean? #f]) void?]{
Old, keywordless variant of @racket[pack-plt] for backward compatibility.}
@defproc[(std-filter (p path-string?)) boolean?]{
Returns @racket[#t] unless @racket[p], after stripping its
directory path and converting to a byte string, matches one of the
following regular expressions: @litchar{^CVS$}, @litchar{^[.]svn$},
@litchar{^[.]cvsignore}, @litchar{^compiled$}, @litchar{^doc},
@litchar{~$}, @litchar{^#.*#$}, @litchar{^[.]#}, or @litchar{[.]plt$}.}
@defproc[(mztar (path path-string?)
(output output-port?)
(filter (path-string? . -> . boolean?))
(file-mode (symbols 'file 'file-replace))) void?]{
Called by @racket[pack] to write one directory/file @racket[path] to the
output port @racket[output] using the filter procedure @racket[filter]
(see @racket[pack] for a description of @racket[filter]). The
@racket[file-mode] argument specifies the default mode for packing a file,
either @racket['file] or @racket['file-replace].}

26
collects/scribblings/raco/raco.scrbl Normal file
View File

@ -0,0 +1,26 @@
#lang scribble/doc
@(require scribble/manual
"common.ss")
@title{@exec{raco}: Racket Command-Line Tools}
The @exec{raco} program supports various Racket tasks from a command
line. The first argument to @exec{raco} is always a specific command
name. For example, @exec{raco make} starts a command to compile a
Racket source module to bytecode format.
The set of commands available through @exec{raco} is extensible. Use
@exec{raco help} to get a complete list of available commands for your
installation. This manual covers the commands that are available in
a typical Racket installation.
@table-of-contents[]
@include-section["make.scrbl"]
@include-section["exe.scrbl"]
@include-section["dist.scrbl"]
@include-section["plt.scrbl"]
@include-section["planet.scrbl"]
@include-section["setup.scrbl"]
@include-section["decompile.scrbl"]
@include-section["ctool.scrbl"]

823
collects/scribblings/setup-plt/setup-plt.scrbl → collects/scribblings/raco/setup.scrbl
View File

File diff suppressed because it is too large Load Diff

332
collects/scribblings/mzc/zo-parse.scrbl → collects/scribblings/raco/zo-parse.scrbl
View File

@ -1,13 +1,13 @@
#lang scribble/doc
@(require scribble/manual
(for-label scheme/base
scheme/contract
(for-label racket/base
racket/contract
compiler/zo-parse))
@(define-syntax-rule (defstruct+ id fields . rest)
(defstruct id fields #:transparent . rest))
@title{Scheme API for Parsing Bytecode}
@title{API for Parsing Bytecode}
@defmodule[compiler/zo-parse]
@ -15,27 +15,27 @@
Parses a port (typically the result of opening a @filepath{.zo} file)
containing bytecode. Beware that the structure types used to represent the
bytecode are subject to frequent changes across PLT Scheme versons.
bytecode are subject to frequent changes across Racket versons.
The parsed bytecode is returned in a @scheme[compilation-top]
structure. For a compiled module, the @scheme[compilation-top]
structure will contain a @scheme[mod] structure. For a top-level
sequence, it will normally contain a @scheme[seq] or @scheme[splice]
The parsed bytecode is returned in a @racket[compilation-top]
structure. For a compiled module, the @racket[compilation-top]
structure will contain a @racket[mod] structure. For a top-level
sequence, it will normally contain a @racket[seq] or @racket[splice]
structure with a list of top-level declarations and expressions.
The bytecode representation of an expression is closer to an
S-expression than a traditional, flat control string. For example, an
@scheme[if] form is represented by a @scheme[branch] structure that
@racket[if] form is represented by a @racket[branch] structure that
has three fields: a test expression, a ``then'' expression, and an
``else'' expression. Similarly, a function call is represented by an
@scheme[application] structure that has a list of argument
@racket[application] structure that has a list of argument
expressions.
Storage for local variables or intermediate values (such as the
arguments for a function call) is explicitly specified in terms of a
stack. For example, execution of an @scheme[application] structure
stack. For example, execution of an @racket[application] structure
reserves space on the stack for each argument result. Similarly, when
a @scheme[let-one] structure (for a simple @scheme[let]) is executed,
a @racket[let-one] structure (for a simple @racket[let]) is executed,
the value obtained by evaluating the right-hand side expression is
pushed onto the stack, and then the body is evaluated. Local variables
are always accessed as offsets from the current stack position. When a
@ -48,8 +48,8 @@ more compact layout than when they were captured).
When a sub-expression produces a value, then the stack pointer is
restored to its location from before evaluating the
sub-expression. For example, evaluating the right-hand size for a
@scheme[let-one] structure may temporarily push values onto the stack,
but the stack is restored to its pre-@scheme[let-one] position before
@racket[let-one] structure may temporarily push values onto the stack,
but the stack is restored to its pre-@racket[let-one] position before
pushing the resulting value and continuing with the body. In addition,
a tail call resets the stack pointer to the position that follows the
enclosing function's arguments, and then the tail call continues by
@ -64,10 +64,10 @@ variable. Mutable local variables are boxed similarly to global
variables, but individual boxes are referenced from the stack and
closures.
Quoted syntax (in the sense of @scheme[quote-syntax]) is treated like
Quoted syntax (in the sense of @racket[quote-syntax]) is treated like
a global variable, because it must be instantiated for an appropriate
phase. A @scheme[prefix] structure within a @scheme[compilation-top]
or @scheme[mod] structure indicates the list of global variables and
phase. A @racket[prefix] structure within a @racket[compilation-top]
or @racket[mod] structure indicates the list of global variables and
quoted syntax that need to be instantiated (and put into an array on
the stack) before evaluating expressions that might use them.}
@ -78,12 +78,12 @@ the stack) before evaluating expressions that might use them.}
[prefix prefix?]
[code (or/c form? indirect? any/c)])]{
Wraps compiled code. The @scheme[max-let-depth] field indicates the
maximum stack depth that @scheme[code] creates (not counting the
@scheme[prefix] array). The @scheme[prefix] field describes top-level
Wraps compiled code. The @racket[max-let-depth] field indicates the
maximum stack depth that @racket[code] creates (not counting the
@racket[prefix] array). The @racket[prefix] field describes top-level
variables, module-level variables, and quoted syntax-objects accessed
by @scheme[code]. The @scheme[code] field contains executable code; it
is normally a @scheme[form], but a literal value is represented as
by @racket[code]. The @racket[code] field contains executable code; it
is normally a @racket[form], but a literal value is represented as
itself.}
@ -93,36 +93,36 @@ itself.}
Represents a ``prefix'' that is pushed onto the stack to initiate
evaluation. The prefix is an array, where buckets holding the values
for @scheme[toplevels] are first, then a bucket for another array if
@scheme[stxs] is non-empty, then @scheme[num-lifts] extra buckets for
for @racket[toplevels] are first, then a bucket for another array if
@racket[stxs] is non-empty, then @racket[num-lifts] extra buckets for
lifted local procedures.
In @scheme[toplevels], each element is one of the following:
In @racket[toplevels], each element is one of the following:
@itemize[
@item{a @scheme[#f], which indicates a dummy variable that is used to
@item{a @racket[#f], which indicates a dummy variable that is used to
access the enclosing module/namespace at run time;}
@item{a symbol, which is a reference to a variable defined in the
enclosing module;}
@item{a @scheme[global-bucket], which is a top-level variable
@item{a @racket[global-bucket], which is a top-level variable
(appears only outside of modules); or}
@item{a @scheme[module-variable], which indicates a variable imported
@item{a @racket[module-variable], which indicates a variable imported
from another module.}
]
The variable buckets and syntax objects that are recorded in a prefix
are accessed by @scheme[toplevel] and @scheme[topsyntax] expression
are accessed by @racket[toplevel] and @racket[topsyntax] expression
forms.}
@defstruct+[global-bucket ([name symbol?])]{
Represents a top-level variable, and used only in a @scheme[prefix].}
Represents a top-level variable, and used only in a @racket[prefix].}
@defstruct+[module-variable ([modidx module-path-index?]
@ -130,16 +130,16 @@ Represents a top-level variable, and used only in a @scheme[prefix].}
[pos exact-integer?]
[phase (or/c 0 1)])]{
Represents a top-level variable, and used only in a @scheme[prefix].
The @scheme[pos] may record the variable's offset within its module,
or it can be @scheme[-1] if the variable is always located by name.
The @scheme[phase] indicates the phase level of the definition within
Represents a top-level variable, and used only in a @racket[prefix].
The @racket[pos] may record the variable's offset within its module,
or it can be @racket[-1] if the variable is always located by name.
The @racket[phase] indicates the phase level of the definition within
its module.}
@defstruct+[stx ([encoded wrapped?])]{
Wraps a syntax object in a @scheme[prefix].}
Wraps a syntax object in a @racket[prefix].}
@; --------------------------------------------------
@ -148,18 +148,18 @@ Wraps a syntax object in a @scheme[prefix].}
@defstruct+[form ()]{
A supertype for all forms that can appear in compiled code (including
@scheme[expr]s), except for literals that are represented as
themselves and @scheme[indirect] structures to create cycles.}
@racket[expr]s), except for literals that are represented as
themselves and @racket[indirect] structures to create cycles.}
@defstruct+[(def-values form) ([ids (listof toplevel?)]
[rhs (or/c expr? seq? indirect? any/c)])]{
Represents a @scheme[define-values] form. Each element of @scheme[ids]
Represents a @racket[define-values] form. Each element of @racket[ids]
will reference via the prefix either a top-level variable or a local
module variable.
After @scheme[rhs] is evaluated, the stack is restored to its depth
from before evaluating @scheme[rhs].}
After @racket[rhs] is evaluated, the stack is restored to its depth
from before evaluating @racket[rhs].}
@deftogether[(
@defstruct+[(def-syntaxes form) ([ids (listof toplevel?)]
@ -172,40 +172,40 @@ from before evaluating @scheme[rhs].}
[max-let-depth exact-nonnegative-integer?])]
)]{
Represents a @scheme[define-syntaxes] or
@scheme[define-values-for-syntax] form. The @scheme[rhs] expression
has its own @scheme[prefix], which is pushed before evaluating
@scheme[rhs]; the stack is restored after obtaining the result
values. The @scheme[max-let-depth] field indicates the maximum size of
the stack that will be created by @scheme[rhs] (not counting
@scheme[prefix]).}
Represents a @racket[define-syntaxes] or
@racket[define-values-for-syntax] form. The @racket[rhs] expression
has its own @racket[prefix], which is pushed before evaluating
@racket[rhs]; the stack is restored after obtaining the result
values. The @racket[max-let-depth] field indicates the maximum size of
the stack that will be created by @racket[rhs] (not counting
@racket[prefix]).}
@defstruct+[(req form) ([reqs syntax?]
[dummy toplevel?])]{
Represents a top-level @scheme[#%require] form (but not one in a
@scheme[module] form) with a sequence of specifications
@scheme[reqs]. The @scheme[dummy] variable is used to access to the
Represents a top-level @racket[#%require] form (but not one in a
@racket[module] form) with a sequence of specifications
@racket[reqs]. The @racket[dummy] variable is used to access to the
top-level namespace.}
@defstruct+[(seq form) ([forms (listof (or/c form? indirect? any/c))])]{
Represents a @scheme[begin] form, either as an expression or at the
top level (though the latter is more commonly a @scheme[splice] form).
When a @scheme[seq] appears in an expression position, its
@scheme[forms] are expressions.
Represents a @racket[begin] form, either as an expression or at the
top level (though the latter is more commonly a @racket[splice] form).
When a @racket[seq] appears in an expression position, its
@racket[forms] are expressions.
After each form in @scheme[forms] is evaluated, the stack is restored
After each form in @racket[forms] is evaluated, the stack is restored
to its depth from before evaluating the form.}
@defstruct+[(splice form) ([forms (listof (or/c form? indirect? any/c))])]{
Represents a top-level @scheme[begin] form where each evaluation is
Represents a top-level @racket[begin] form where each evaluation is
wrapped with a continuation prompt.
After each form in @scheme[forms] is evaluated, the stack is restored
After each form in @racket[forms] is evaluated, the stack is restored
to its depth from before evaluating the form.}
@ -226,39 +226,39 @@ to its depth from before evaluating the form.}
[lang-info (or/c #f (vector/c module-path? symbol? any/c))]
[internal-context (or/c #f #t stx?)])]{
Represents a @scheme[module] declaration. The @scheme[body] forms use
@scheme[prefix], rather than any prefix in place for the module
declaration itself (and each @scheme[syntax-body] has its own
Represents a @racket[module] declaration. The @racket[body] forms use
@racket[prefix], rather than any prefix in place for the module
declaration itself (and each @racket[syntax-body] has its own
prefix).
The @scheme[provides] and @scheme[requires] lists are each an
The @racket[provides] and @racket[requires] lists are each an
association list from phases to exports or imports. In the case of
@scheme[provides], each phase maps to two lists: one for exported
@racket[provides], each phase maps to two lists: one for exported
variables, and another for exported syntax. In the case of
@scheme[requires], each phase maps to a list of imported module paths.
@racket[requires], each phase maps to a list of imported module paths.
The @scheme[body] field contains the module's run-time code, and
@scheme[syntax-body] contains the module's compile-time code. After
each form in @scheme[body] or @scheme[syntax-body] is evaluated, the
The @racket[body] field contains the module's run-time code, and
@racket[syntax-body] contains the module's compile-time code. After
each form in @racket[body] or @racket[syntax-body] is evaluated, the
stack is restored to its depth from before evaluating the form.
The @scheme[unexported] list contains lists of symbols for unexported
The @racket[unexported] list contains lists of symbols for unexported
definitions that can be accessed through macro expansion. The first
list is phase-0 variables, the second is phase-0 syntax, and the last
is phase-1 variables.
The @scheme[max-let-depth] field indicates the maximum stack depth
created by @scheme[body] forms (not counting the @scheme[prefix]
array). The @scheme[dummy] variable is used to access to the
The @racket[max-let-depth] field indicates the maximum stack depth
created by @racket[body] forms (not counting the @racket[prefix]
array). The @racket[dummy] variable is used to access to the
top-level namespace.
The @scheme[lang-info] value specifies an optional module path that
The @racket[lang-info] value specifies an optional module path that
provides information about the module's implementation language.
The @scheme[internal-module-context] value describes the lexical
The @racket[internal-module-context] value describes the lexical
context of the body of the module. This value is used by
@scheme[module->namespace]. A @scheme[#f] value means that the context
is unavailable or empty. A @scheme[#t] value means that the context is
@racket[module->namespace]. A @racket[#f] value means that the context
is unavailable or empty. A @racket[#t] value means that the context is
computed by re-importing all required modules. A syntax-object value
embeds an arbitrary lexical context.}
@ -270,7 +270,7 @@ embeds an arbitrary lexical context.}
[protected? boolean?]
[insp (or #t #f void?)])]{
Describes an individual provided identifier within a @scheme[mod] instance.}
Describes an individual provided identifier within a @racket[mod] instance.}
@; --------------------------------------------------
@section{Expressions}
@ -279,7 +279,7 @@ Describes an individual provided identifier within a @scheme[mod] instance.}
A supertype for all expression forms that can appear in compiled code,
except for literals that are represented as themselves,
@scheme[indirect] structures to create cycles, and some @scheme[seq]
@racket[indirect] structures to create cycles, and some @racket[seq]
structures (which can appear as an expression as long as it contains
only other things that can be expressions).}
@ -294,41 +294,41 @@ only other things that can be expressions).}
[max-let-depth exact-nonnegative-integer?]
[body (or/c expr? seq? indirect? any/c)])]{
Represents a @scheme[lambda] form. The @scheme[name] field is a name
for debugging purposes. The @scheme[num-params] field indicates the
Represents a @racket[lambda] form. The @racket[name] field is a name
for debugging purposes. The @racket[num-params] field indicates the
number of arguments accepted by the procedure, not counting a rest
argument; the @scheme[rest?] field indicates whether extra arguments
argument; the @racket[rest?] field indicates whether extra arguments
are accepted and collected into a ``rest'' variable. The
@scheme[param-types] list contains @scheme[num-params] symbols
indicating the type of each argumet, either @scheme['val] for a normal
argument, @scheme['ref] for a boxed argument (representing a mutable
local variable), or @scheme['flonum] for a flonum argument. The
@scheme[closure-map] field is a vector of stack positions that are
captured when evaluating the @scheme[lambda] form to create a closure.
The @scheme[closure-types] field provides a corresponding list of
@racket[param-types] list contains @racket[num-params] symbols
indicating the type of each argumet, either @racket['val] for a normal
argument, @racket['ref] for a boxed argument (representing a mutable
local variable), or @racket['flonum] for a flonum argument. The
@racket[closure-map] field is a vector of stack positions that are
captured when evaluating the @racket[lambda] form to create a closure.
The @racket[closure-types] field provides a corresponding list of
types, but no distinction is made between normal values and boxed
values; also, this information is redundant, since it can be inferred by
the bindings referenced though @scheme[closure-map].
the bindings referenced though @racket[closure-map].
When the function is called, the rest-argument list (if any) is pushed
onto the stack, then the normal arguments in reverse order, then the
closure-captured values in reverse order. Thus, when @scheme[body] is
closure-captured values in reverse order. Thus, when @racket[body] is
run, the first value on the stack is the first value captured by the
@scheme[closure-map] array, and so on.
@racket[closure-map] array, and so on.
The @scheme[max-let-depth] field indicates the maximum stack depth
created by @scheme[body] plus the arguments and closure-captured
values pushed onto the stack. The @scheme[body] field is the
The @racket[max-let-depth] field indicates the maximum stack depth
created by @racket[body] plus the arguments and closure-captured
values pushed onto the stack. The @racket[body] field is the
expression for the closure's body.}
@defstruct+[(closure expr) ([code lam?] [gen-id symbol?])]{
A @scheme[lambda] form with an empty closure, which is a procedure
A @racket[lambda] form with an empty closure, which is a procedure
constant. The procedure constant can appear multiple times in the
graph of expressions for bytecode, and the @scheme[code] field can
refer back to the same @scheme[closure] through an @scheme[indirect]
for a recursive constant procedure; the @scheme[gen-id] is different
graph of expressions for bytecode, and the @racket[code] field can
refer back to the same @racket[closure] through an @racket[indirect]
for a recursive constant procedure; the @racket[gen-id] is different
for each such constant.}
@ -340,8 +340,8 @@ An indirection used in expression positions to form cycles.}
@defstruct+[(case-lam expr) ([name (or/c symbol? vector?)]
[clauses (listof lam?)])]{
Represents a @scheme[case-lambda] form as a combination of
@scheme[lambda] forms that are tried (in order) based on the number of
Represents a @racket[case-lambda] form as a combination of
@racket[lambda] forms that are tried (in order) based on the number of
arguments given.}
@ -350,26 +350,26 @@ arguments given.}
[flonum? boolean?]
[unused? boolean?])]{
Pushes an uninitialized slot onto the stack, evaluates @scheme[rhs]
and puts its value into the slot, and then runs @scheme[body]. If
@scheme[flonum?] is @scheme[#t], then @scheme[rhs] must produce a
flonum, and the slot must be accessed by @scheme[localref]s that
expect a flonum. If @scheme[unused?] is @scheme[#t], then the slot
must not be used, and the value of @scheme[rhs] is not actually pushed
onto the stack (but @scheme[rhs] is constrained to produce a single
Pushes an uninitialized slot onto the stack, evaluates @racket[rhs]
and puts its value into the slot, and then runs @racket[body]. If
@racket[flonum?] is @racket[#t], then @racket[rhs] must produce a
flonum, and the slot must be accessed by @racket[localref]s that
expect a flonum. If @racket[unused?] is @racket[#t], then the slot
must not be used, and the value of @racket[rhs] is not actually pushed
onto the stack (but @racket[rhs] is constrained to produce a single
value).
After @scheme[rhs] is evaluated, the stack is restored to its depth
from before evaluating @scheme[rhs]. Note that the new slot is created
before evaluating @scheme[rhs].}
After @racket[rhs] is evaluated, the stack is restored to its depth
from before evaluating @racket[rhs]. Note that the new slot is created
before evaluating @racket[rhs].}
@defstruct+[(let-void expr) ([count exact-nonnegative-integer?]
[boxes? boolean?]
[body (or/c expr? seq? indirect? any/c)])]{
Pushes @scheme[count] uninitialized slots onto the stack and then runs
@scheme[body]. If @scheme[boxes?] is @scheme[#t], then the slots are
Pushes @racket[count] uninitialized slots onto the stack and then runs
@racket[body]. If @racket[boxes?] is @racket[#t], then the slots are
filled with boxes that contain @|undefined-const|.}
@ -379,36 +379,36 @@ filled with boxes that contain @|undefined-const|.}
[rhs (or/c expr? seq? indirect? any/c)]
[body (or/c expr? seq? indirect? any/c)])]{
Runs @scheme[rhs] to obtain @scheme[count] results, and installs them
Runs @racket[rhs] to obtain @racket[count] results, and installs them
into existing slots on the stack in order, skipping the first
@scheme[pos] stack positions. If @scheme[boxes?] is @scheme[#t], then
@racket[pos] stack positions. If @racket[boxes?] is @racket[#t], then
the values are put into existing boxes in the stack slots.
After @scheme[rhs] is evaluated, the stack is restored to its depth
from before evaluating @scheme[rhs].}
After @racket[rhs] is evaluated, the stack is restored to its depth
from before evaluating @racket[rhs].}
@defstruct+[(let-rec expr) ([procs (listof lam?)]
[body (or/c expr? seq? indirect? any/c)])]{
Represents a @scheme[letrec] form with @scheme[lambda] bindings. It
allocates a closure shell for each @scheme[lambda] form in
@scheme[procs], installs each onto the stack in previously
Represents a @racket[letrec] form with @racket[lambda] bindings. It
allocates a closure shell for each @racket[lambda] form in
@racket[procs], installs each onto the stack in previously
allocated slots in reverse order (so that the closure shell for the
last element of @scheme[procs] is installed at stack position
@scheme[0]), fills out each shell's closure (where each closure
last element of @racket[procs] is installed at stack position
@racket[0]), fills out each shell's closure (where each closure
normally references some other just-created closures, which is
possible because the shells have been installed on the stack), and
then evaluates @scheme[body].}
then evaluates @racket[body].}
@defstruct+[(boxenv expr) ([pos exact-nonnegative-integer?]
[body (or/c expr? seq? indirect? any/c)])]{
Skips @scheme[pos] elements of the stack, setting the slot afterward
Skips @racket[pos] elements of the stack, setting the slot afterward
to a new box containing the slot's old value, and then runs
@scheme[body]. This form appears when a @scheme[lambda] argument is
mutated using @scheme[set!] within its body; calling the function
@racket[body]. This form appears when a @racket[lambda] argument is
mutated using @racket[set!] within its body; calling the function
initially pushes the value directly on the stack, and this form boxes
the value so that it can be mutated later.}
@ -420,14 +420,14 @@ the value so that it can be mutated later.}
[flonum? boolean?])]{
Represents a local-variable reference; it accesses the value in the
stack slot after the first @scheme[pos] slots. If @scheme[unbox?] is
@scheme[#t], the stack slot contains a box, and a value is extracted
from the box. If @scheme[clear?] is @scheme[#t], then after the value
stack slot after the first @racket[pos] slots. If @racket[unbox?] is
@racket[#t], the stack slot contains a box, and a value is extracted
from the box. If @racket[clear?] is @racket[#t], then after the value
is obtained, the stack slot is cleared (to avoid retaining a reference
that can prevent reclamation of the value as garbage). If
@scheme[other-clears?] is @scheme[#t], then some later reference to
the same stack slot may clear after reading. If @scheme[flonum?] is
@scheme[#t], the slot holds to a flonum value.}
@racket[other-clears?] is @racket[#t], then some later reference to
the same stack slot may clear after reading. If @racket[flonum?] is
@racket[#t], the slot holds to a flonum value.}
@defstruct+[(toplevel expr) ([depth exact-nonnegative-integer?]
@ -436,15 +436,15 @@ the same stack slot may clear after reading. If @scheme[flonum?] is
[ready? boolean?])]{
Represents a reference to a top-level or imported variable via the
@scheme[prefix] array. The @scheme[depth] field indicates the number
of stack slots to skip to reach the prefix array, and @scheme[pos] is
@racket[prefix] array. The @racket[depth] field indicates the number
of stack slots to skip to reach the prefix array, and @racket[pos] is
the offset into the array.
If @scheme[const?] is @scheme[#t], then the variable definitely will
be defined, and its value stays constant. If @scheme[ready?] is
@scheme[#t], then the variable definitely will be defined (but its
value might change in the future). If @scheme[const?] and
@scheme[ready?] are both @scheme[#f], then a check is needed to
If @racket[const?] is @racket[#t], then the variable definitely will
be defined, and its value stays constant. If @racket[ready?] is
@racket[#t], then the variable definitely will be defined (but its
value might change in the future). If @racket[const?] and
@racket[ready?] are both @racket[#f], then a check is needed to
determine whether the variable is defined.}
@ -453,19 +453,19 @@ determine whether the variable is defined.}
[midpt exact-nonnegative-integer?])]{
Represents a reference to a quoted syntax object via the
@scheme[prefix] array. The @scheme[depth] field indicates the number
of stack slots to skip to reach the prefix array, and @scheme[pos] is
the offset into the array. The @scheme[midpt] value is used internally
@racket[prefix] array. The @racket[depth] field indicates the number
of stack slots to skip to reach the prefix array, and @racket[pos] is
the offset into the array. The @racket[midpt] value is used internally
for lazy calculation of syntax information.}
@defstruct+[(application expr) ([rator (or/c expr? seq? indirect? any/c)]
[rands (listof (or/c expr? seq? indirect? any/c))])]{
Represents a function call. The @scheme[rator] field is the expression
for the function, and @scheme[rands] are the argument
Represents a function call. The @racket[rator] field is the expression
for the function, and @racket[rands] are the argument
expressions. Before any of the expressions are evaluated,
@scheme[(length rands)] uninitialized stack slots are created (to be
@racket[(length rands)] uninitialized stack slots are created (to be
used as temporary space).}
@ -473,51 +473,51 @@ used as temporary space).}
[then (or/c expr? seq? indirect? any/c)]
[else (or/c expr? seq? indirect? any/c)])]{
Represents an @scheme[if] form.
Represents an @racket[if] form.
After @scheme[test] is evaluated, the stack is restored to its depth
from before evaluating @scheme[test].}
After @racket[test] is evaluated, the stack is restored to its depth
from before evaluating @racket[test].}
@defstruct+[(with-cont-mark expr) ([key (or/c expr? seq? indirect? any/c)]
[val (or/c expr? seq? indirect? any/c)]
[body (or/c expr? seq? indirect? any/c)])]{
Represents a @scheme[with-continuation-mark] expression.
Represents a @racket[with-continuation-mark] expression.
After each of @scheme[key] and @scheme[val] is evaluated, the stack is
restored to its depth from before evaluating @scheme[key] or
@scheme[val].}
After each of @racket[key] and @racket[val] is evaluated, the stack is
restored to its depth from before evaluating @racket[key] or
@racket[val].}
@defstruct+[(beg0 expr) ([seq (listof (or/c expr? seq? indirect? any/c))])]{
Represents a @scheme[begin0] expression.
Represents a @racket[begin0] expression.
After each expression in @scheme[seq] is evaluated, the stack is
After each expression in @racket[seq] is evaluated, the stack is
restored to its depth from before evaluating the expression.}
@defstruct+[(varref expr) ([toplevel toplevel?])]{
Represents a @scheme[#%variable-reference] form.}
Represents a @racket[#%variable-reference] form.}
@defstruct+[(assign expr) ([id toplevel?]
[rhs (or/c expr? seq? indirect? any/c)]
[undef-ok? boolean?])]{
Represents a @scheme[set!] expression that assigns to a top-level or
Represents a @racket[set!] expression that assigns to a top-level or
module-level variable. (Assignments to local variables are represented
by @scheme[install-value] expressions.)
by @racket[install-value] expressions.)
After @scheme[rhs] is evaluated, the stack is restored to its depth
from before evaluating @scheme[rhs].}
After @racket[rhs] is evaluated, the stack is restored to its depth
from before evaluating @racket[rhs].}
@defstruct+[(apply-values expr) ([proc (or/c expr? seq? indirect? any/c)]
[args-expr (or/c expr? seq? indirect? any/c)])]{
Represents @scheme[(call-with-values (lambda () args-expr) proc)],
Represents @racket[(call-with-values (lambda () args-expr) proc)],
which is handled specially by the run-time system.}
@ -533,9 +533,9 @@ kernel.}
[wraps (listof wrap?)]
[certs (or/c list? #f)])]{
Represents a syntax object, where @scheme[wraps] contain the lexical
information and @scheme[certs] is certificate information. When the
@scheme[datum] part is itself compound, its pieces are wrapped, too.}
Represents a syntax object, where @racket[wraps] contain the lexical
information and @racket[certs] is certificate information. When the
@racket[datum] part is itself compound, its pieces are wrapped, too.}
@defstruct+[wrap ()]{
@ -571,7 +571,7 @@ Represents a set of module and import bindings.}
[prefix (or/c symbol? #f)])]{
Represents a set of simple imports from one module within a
@scheme[module-rename].}
@racket[module-rename].}
@defstruct+[module-binding ()]{
@ -580,7 +580,7 @@ A supertype for module bindings.}
@defstruct+[(simple-module-binding module-binding) ([path module-path-index?])]{
Represents a single identifier import within
a @scheme[module-rename].}
a @racket[module-rename].}
@defstruct+[(phased-module-binding module-binding) ([path module-path-index?]
[phase exact-integer?]
@ -589,7 +589,7 @@ a @scheme[module-rename].}
[nominal-export-name any/c])]{
Represents a single identifier import within
a @scheme[module-rename].}
a @racket[module-rename].}
@defstruct+[(exported-nominal-module-binding module-binding) ([path module-path-index?]
[export-name any/c]
@ -597,19 +597,19 @@ a @scheme[module-rename].}
[nominal-export-name any/c])]{
Represents a single identifier import within
a @scheme[module-rename].}
a @racket[module-rename].}
@defstruct+[(nominal-module-binding module-binding) ([path module-path-index?]
[nominal-path nominal-path?])]{
Represents a single identifier import within
a @scheme[module-rename].}
a @racket[module-rename].}
@defstruct+[(exported-module-binding module-binding) ([path module-path-index?]
[export-name any/c])]{
Represents a single identifier import within
a @scheme[module-rename].}
a @racket[module-rename].}
@defstruct+[nominal-path ()]{

2
collects/scribblings/reference/startup.scrbl
View File

@ -402,7 +402,7 @@ language specifies run-time configuration by
A @racket['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 @secref[#:doc '(lib "scribblings/mzc/mzc.scrbl") "exe"].
executable; see @secref[#:doc '(lib "scribblings/raco/raco.scrbl") "exe"].
For information on defining a new @hash-lang[] language, see
@racketmodname[syntax/module-reader].

4
collects/scribblings/setup-plt/info.rkt
View File

@ -1,4 +0,0 @@
#lang setup/infotab
(define scribblings '(("setup-plt.scrbl" (multi-page) (tool 50))))

2
collects/test-box-recovery/info.rkt
View File

@ -5,4 +5,4 @@
(define tools (list '("tool.ss")))
(define tool-names (list "Test Box Recovery"))
(define scribblings '(("test-box-recovery.scrbl" () (other))))
(define scribblings '(("test-box-recovery.scrbl" () (legacy))))