From e3af8a5a5254d35bdcc706916bbeb79e72ac3ecf Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Tue, 15 Jan 2008 14:20:49 +0000 Subject: [PATCH] more mzc scribblings; scribbled HTML layout tweaks svn: r8335 --- collects/scribble/html-render.ss | 7 +- collects/scribble/scribble.css | 8 +- collects/scribblings/mzc/exe.scrbl | 135 +++++++++++++++++++++++++++- collects/scribblings/mzc/mzc.scrbl | 2 + collects/scribblings/mzc/plt.scrbl | 137 ++++++++++++++++++++++++++++- collects/scribblings/mzc/zo.scrbl | 2 +- 6 files changed, 284 insertions(+), 7 deletions(-) diff --git a/collects/scribble/html-render.ss b/collects/scribble/html-render.ss index 8de6dccba0..2af395e062 100644 --- a/collects/scribble/html-render.ss +++ b/collects/scribble/html-render.ss @@ -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))))))))) diff --git a/collects/scribble/scribble.css b/collects/scribble/scribble.css index 55e2b024eb..31805e7c87 100644 --- a/collects/scribble/scribble.css +++ b/collects/scribble/scribble.css @@ -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; diff --git a/collects/scribblings/mzc/exe.scrbl b/collects/scribblings/mzc/exe.scrbl index 2d5c16bde6..095b141ed2 100644 --- a/collects/scribblings/mzc/exe.scrbl +++ b/collects/scribblings/mzc/exe.scrbl @@ -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. diff --git a/collects/scribblings/mzc/mzc.scrbl b/collects/scribblings/mzc/mzc.scrbl index 3880a40f93..3e7422f6ad 100644 --- a/collects/scribblings/mzc/mzc.scrbl +++ b/collects/scribblings/mzc/mzc.scrbl @@ -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[] diff --git a/collects/scribblings/mzc/plt.scrbl b/collects/scribblings/mzc/plt.scrbl index 4ed848c836..5bb84fe0f0 100644 --- a/collects/scribblings/mzc/plt.scrbl +++ b/collects/scribblings/mzc/plt.scrbl @@ -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. diff --git a/collects/scribblings/mzc/zo.scrbl b/collects/scribblings/mzc/zo.scrbl index f82baf0a95..1bfb430cc2 100644 --- a/collects/scribblings/mzc/zo.scrbl +++ b/collects/scribblings/mzc/zo.scrbl @@ -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"].