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

more mzc scribblings; scribbled HTML layout tweaks

Browse Source 
svn: r8335
This commit is contained in:
Matthew Flatt 2008-01-15 14:20:49 +00:00
parent 8b16cee613
commit e3af8a5a52
6 changed files with 284 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
collects/scribble/html-render.ss
View File

@ -277,7 +277,8 @@
flows)))
(table-flowss table))))])
(apply append (map flow-element-targets (flow-paragraphs (part-flow d)))))
(map flatten (part-parts d)))))])
(map flatten (part-parts d)))))]
[any-parts? (ormap part? ps)])
(if (null? ps)
null
`((div ((class "tocsub"))
@ -303,7 +304,9 @@
(format "#~a" (anchor-name (tag-key (target-element-tag p) ri)))))
(class ,(if (part? p)
"tocsubseclink"
"tocsublink")))
(if any-parts?
"tocsubnonseclink"
"tocsublink"))))
,@(if (part? p)
(render-content (or (part-title-content p) '("???")) d ri)
(render-content (element-content p) d ri)))))))))

8
collects/scribble/scribble.css
View File

@ -137,7 +137,8 @@ font-weight: bold;
.tocsub {
text-align: left;
background-color: #DCF5F5;
margin-top: 0.5em;
background-color: #F5F5F5;
}
.tocviewtitle {
@ -182,6 +183,11 @@ font-weight: bold;
text-decoration: none;
}
.tocsubnonseclink {
text-decoration: none;
padding-left: 0.5em;
}
.tocsubtitle {
font-size: 80%;
font-style: italic;

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

@ -1,5 +1,136 @@
#lang scribble/doc
@(require scribble/manual
"common.ss")
"common.ss"
(for-label scheme/runtime-path))
@title[#:tag "exe"]{Creating and Packaging Stand-Alone Executables}
@title[#:tag "exe"]{Creating and Distributing Stand-Alone Executables}
Whether bytecode or native code, the compiled code produced by @|mzc|
relies on MzScheme (or MrEd) to provide run-time support to the
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.
@section{Stand-Alone Executables from Scheme Code}
The command-line flag @DFlag{exe} directs @|mzc| to embed a
module, from source or byte code, into a copy of the MzScheme
executable. (Under Unix, the embedding executable is actually a copy
of a wrapper executable.) The created executable invokes the embedded
module on startup. The @DFlag{gui-exe} flag is similar, but it
copies the MrEd executable. If the embedded module refers to other
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 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 MzScheme, MrEd, or DrScheme. However, the
executable depends on MzScheme and/or MrEd 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 the
next section.
@; ----------------------------------------------------------------------
@section[#: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 geetings 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.

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

@ -51,3 +51,5 @@ one of the following command-line flags:
@include-section["plt.scrbl"]
@include-section["ext.scrbl"]
@include-section["zo.scrbl"]
@index-section[]

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

@ -1,5 +1,140 @@
#lang scribble/doc
@(require scribble/manual
"common.ss")
"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/reference/reference.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:
@schemeblock[
(module info 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.
Although @|mzc|'s command-line interface is sufficient for most
purposes, the @schememodname[setup/pack] library provides a more
general interface for constructing archives.

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

@ -2,7 +2,7 @@
@(require scribble/manual
"common.ss")
@title[#:tag "zo"]{Compiling to Bytecode}
@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 described in @secref["make"].