290 lines
12 KiB
Plaintext
290 lines
12 KiB
Plaintext
|
|
_Setup PLT_ or _setup-plt_: Collection Setup and Unpacking
|
|
==========================================================
|
|
|
|
The Setup PLT executable (bin/setup-plt for Unix) performs two
|
|
services:
|
|
|
|
* Compiling and setting up all collections: When Setup PLT is run
|
|
without any arguments, it finds all of the current collections
|
|
(using the PLTHOME and PLTCOLLECTS environment variable)
|
|
and compiles all collections with an info.ss library that
|
|
indicates how the collection is compiled (see the
|
|
--collection-zos flag for mzc).
|
|
|
|
The --clean (or -c) flag to Setup PLT causes it to delete
|
|
all existing .zo and extension files, thus ensuring a clean
|
|
build from the source files. (Exactly which files are deleted
|
|
is controlled by the info.ss file. See below for more info.)
|
|
|
|
The -l flag takes one or more collection names and restricts
|
|
Setup PLT's action to those collections.
|
|
|
|
In addition to compilation, a collection's info.ss library
|
|
can specify executables to be installed in the plt directory
|
|
(plt/bin under Unix) or other installation actions.
|
|
|
|
* Unpacking _.plt_ files: A .plt file is a platform-indepedent
|
|
distribution archive for MzScheme- and MrEd-based software.
|
|
When one or more file names are provided as the command line
|
|
arguments to Setup PLT, the files contained in the .plt
|
|
archive are unpacked (according to specifications embedded in
|
|
the .plt file; see below) and only the collections specified
|
|
by the plt file are compiled and setup (they are setup as if
|
|
the "-c" or "--clean" flag had been passed to setup plt)
|
|
|
|
Compiling and Setting Up Collections
|
|
------------------------------------
|
|
|
|
Setup PLT attempts to compile and set up any collection that:
|
|
|
|
* has an info.ss library;
|
|
|
|
* is a top-level collection (not a sub-collection; top-level
|
|
collections can specify subcollections to be compiled and
|
|
set up with the `compile-subcollections' info.ss field);
|
|
and
|
|
|
|
* has the 'name info.ss field.
|
|
|
|
Collections meeting this criteria are compiled using the
|
|
`compile-collection-zos' procedure described above. If the -e or
|
|
--extension flag is specified, then the collections are also compiled
|
|
using the `compile-collection-extension' procedure described above.
|
|
|
|
Additional info.ss fields trigger additional setup actions:
|
|
|
|
> 'mzscheme-launcher-names - a list of executable names to be
|
|
installed in plt (or plt/bin) to run MzScheme programs implemented
|
|
by the collection. A parallel list of library names must be
|
|
provided by `mzscheme-launcher-libraries'. For each name, a
|
|
launching executable is set up using the launcher collection's
|
|
`install-mzscheme-program-launcher'. If the executable already
|
|
exists, no action is taken.
|
|
|
|
> 'mzscheme-launcher-libraries - a list of library names in
|
|
parallel to `mzscheme-launcher-names'.
|
|
|
|
> 'mred-launcher-names - a list of executable names to be installed
|
|
in plt (or plt/bin) to run MrEd programs implemented by the
|
|
collection. A parallel list of library names must be provided by
|
|
`mred-launcher-libraries'. For each name, a launching executable is
|
|
set up using the launcher collection's
|
|
`install-mred-program-launcher'. If the executable already exists,
|
|
no action is taken.
|
|
|
|
> 'mred-launcher-libraries - a list of library names in
|
|
parallel to `mred-launcher-names'.
|
|
|
|
> 'install-collection - a procedure that accepts a directory path
|
|
argument (the path to the collection) and performs
|
|
collection-specific installation work. This procedure should avoid
|
|
unnecessary work in the case that it is called multiple times for
|
|
the same installation.
|
|
|
|
> 'clean - a list of pathnames to be deleted when the --clean or
|
|
-c flag is passed to setup-plt. The pathnames must be relative to
|
|
the collection. If the any path names a directory, each of the
|
|
files in the directory are deleted but none of the subdirectories of that
|
|
directory are checked. If the path names a file,
|
|
the file is deleted. The default, if this flag is not specified, is
|
|
to delete all files in the compiled subdirectory.
|
|
and all of the files in the architecture-specific subdirectory of
|
|
the compiled directory, for the architecture that setup-plt
|
|
is running under.
|
|
|
|
|
|
Unpacking .plt Distribution Archives
|
|
------------------------------------
|
|
|
|
The extension ".plt" is not required for a distribution archive; this
|
|
convention merely helps users identify the purpose of a distribution
|
|
file.
|
|
|
|
The raw format of a distribution file is described below. This format
|
|
is uncompressed and sensitive to communication modes (text
|
|
vs. binary), so the distribution format is derived from the raw format
|
|
by first compressing the file using gzip, then encoding the gzipped
|
|
file with the MIME base64 standard (which relies only the characters
|
|
A-Z, a-z, 0-9, +, /, and =; all other characters are ignored when
|
|
a base64-encoded file is decoded).
|
|
|
|
The raw format is
|
|
|
|
* "PLT" are the first three characters.
|
|
|
|
* An info.ss-like procedure that takes a symbol and a failure thunk
|
|
and returns information about archive for recognized symbols. The
|
|
two required info fields are:
|
|
|
|
+ 'name - a human-readable string describing the archive's
|
|
contents. This name is used only for printing messages to the
|
|
user during unpacking.
|
|
|
|
+ 'unpacker - a symbol indicating the expected unpacking
|
|
environment. Currently, the only allowed value is 'mzscheme.
|
|
|
|
The procedure is extracted from the archive using MzScheme's
|
|
`read' and `eval' procedures.
|
|
|
|
* An unsigned unit that drives the unpacking process. The unit accepts two
|
|
imports: a path string for the plt directory and an `unmztar'
|
|
procedure. The remainder of the unpacking process consists of invoking
|
|
ths unit. It is expected that the unit will call `unmztar' procedure to
|
|
unpack directories and files that are defined in the input archive afer
|
|
this unit. The result of invoking the unit must be a list of collection
|
|
paths (where each collection path is a list of strings); once the
|
|
archive is unpacked, Setup PLT will compile and setup the specified
|
|
collections, as if it was invoked with the "-c" option, so the
|
|
"compiled" directories will be deleted.
|
|
|
|
The `unmztar' procedure takes one argument: a filter
|
|
procedure. The filter procedure is called for each directory and
|
|
file to be unpacked. It is called with three arguments:
|
|
|
|
+ 'dir, 'file, 'file-replace - indicates whether the item to be
|
|
unpacked is a directory, a file, or a file to be replaced;
|
|
|
|
+ a relative path string - the pathname of the directory or file
|
|
to be unpacked, relative to the plt directory; and
|
|
|
|
+ a path string for the plt directory.
|
|
|
|
If the filter procedure returns #f for a directory or file, the
|
|
directory or file is not unpacked. If the filter procedure returns
|
|
#t and the directory or file for 'dir or 'file already exists, it
|
|
is not created. (The file for 'file-replace need not exist
|
|
already.)
|
|
|
|
When a directory is unpacked, intermediate directies are created
|
|
as necessary to create the specified directory. When a file is
|
|
unpacked, the directory must already exist.
|
|
|
|
The unit is extracted from the archive using MzScheme's `read'
|
|
and `eval' procedures.
|
|
|
|
Assuming that the unpacking unit calls the `unmztar' procedure, the
|
|
archive should continue with unpackables. Unpackables are extracted
|
|
until the end-of-file is found (as indicated by an `=' in the
|
|
base64-encoded input archive).
|
|
|
|
An unpackable is one of the following:
|
|
|
|
* The symbol 'dir followed by a list. The `build-path' procedure
|
|
will be applied to the list to obtain a relative path for the
|
|
directory (and the relatie path is combined with the plt directory
|
|
path to ge a complete path).
|
|
|
|
The 'dir symbol and list are extracted from the archive using
|
|
MzScheme's `read' (and the result is *not* `eval'uated).
|
|
|
|
* The symbol 'file, a list, a number, an asterisk, and the file
|
|
data. The list specifies the file's relative path, just as for
|
|
directories. The number indicates the size of the file to be
|
|
unpacked in bytes. The asterisk indicates the start of the file
|
|
data; the next n bytes are written to the file, where n is the
|
|
specified size of the file.
|
|
|
|
The symbol, list, and number are all extracted from the archive
|
|
using MzScheme's `read' (and the result is *not* `eval'uated).
|
|
After the number is read, input characters are discarded until
|
|
an asterisk is found. The file data must follow this asterisk
|
|
immediately.
|
|
|
|
* The symbol 'file-replace is treated like 'file, but if the file
|
|
exists on disk already, the file in the archive replaces the file
|
|
on disk.
|
|
|
|
Making .plt archives
|
|
--------------------
|
|
|
|
The setup collection's pack.ss library provides functions to help
|
|
make .plt archives, especially under Unix:
|
|
|
|
> (pack dest name paths collections [filter encode? file-mode]) -
|
|
Creates the .plt file specified by the pathname `dest', using the
|
|
string `name' as the name reported to Setup PLT as the archive's
|
|
description, and `collections' as the list of colection paths
|
|
returned by the unpacking unit. The `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 `filter' procedure is called with the relative path of each
|
|
candidate for packing. If it returns #f for some path, then that
|
|
file or directory is omitted from the archive. If it returns 'file
|
|
or 'file-replace for a file, the file is packed with that mode,
|
|
rather than the default mode. The default `filter' is `std-filter'
|
|
(defined below).
|
|
|
|
If `encode?' is #f, then the output archive is in raw form, and
|
|
still must be gzipped and mime-encoded. If `encode?' is #t, then
|
|
gzip and mmencode must be in the shell's path for executables.
|
|
the default value is #t.
|
|
|
|
The `file-mode' argument must be 'file or 'file-replace, indicating
|
|
the default mode for a file in the archive. The default value is
|
|
'file.
|
|
|
|
> (std-filter p) - returns #t unless `p' matches one of the following
|
|
regular expressions: "CVS$", "compiled$", "~$", or "^#.*#$".
|
|
|
|
> (mztar path output filter file-mode) - called by `pack' to write one
|
|
directory/file `path' to the output port `output' using the filter
|
|
procedure `filter' (see `pack' for a description of `filter'). The
|
|
`file-mode' argument specifies the default mode for packing a file,
|
|
either 'file or 'file-replace.
|
|
|
|
Setup PLT as a Unit
|
|
-------------------
|
|
|
|
The _setupr.ss_ library in the setup collection contains a signed
|
|
unit that imports
|
|
|
|
setup-option^ - described below
|
|
mzlib:file^
|
|
compiler^ - from sig.ss in the compiler collection
|
|
compiler:option^ - from sig.ss in the compiler collection
|
|
launcher-maker^ - from launchers.ss in the `launcher' collection
|
|
|
|
Invoking this unit starts the setup process. The _setupsig.ss_ library
|
|
defines the
|
|
> setup-option^
|
|
signature, which is implemented by the unit in _setup-optionr.ss_. It
|
|
defines the following parameters that control the setup process:
|
|
|
|
> verbose - #t => prints message from `make' to stderr [default: #f]
|
|
> make-verbose - #t => verbose `make' [default: #f]
|
|
> compiler-verbose - #t => verbose `compiler' [default: #f]
|
|
> clean - #t => delete .zo and .so/.dll files in the specified collections
|
|
[default: #f]
|
|
> make-zo - #t => compile .zo files [default #t]
|
|
> make-so - #t => compile .so/.dll files [default: #f]
|
|
> make-launchers - #t => make collection info.ss-specified launchers
|
|
[default: #t]
|
|
> call-install - #t => call collection info.ss-specified setup code
|
|
[default: #t]
|
|
> specific-collections - a list of collections to set up; the empty
|
|
list means set-up all collections if the archives
|
|
list is also empty [default: null]
|
|
> archives - a list of .plt archives to unpack; any collections specified
|
|
by the archives are set-up in addition to the collections
|
|
listed in specific-collections [default: null]
|
|
|
|
Thus, to unpack a single .plt archive "x.plt", set the `archives'
|
|
parameter to (list "x.plt") and leave `specific-collections' as null.
|
|
|
|
Link the options and setup units so that your option-setting code is
|
|
initialized between them, e.g.:
|
|
|
|
(compound-unit/sig
|
|
...
|
|
(link ...
|
|
[OPTIONS : setup-option^
|
|
((require-library "setup-optionr.ss" "setup"))]
|
|
[MY-CODE : ()
|
|
((require-library "init-options.ss") OPTIONS)]
|
|
[SETUP : ()
|
|
((require-library "setupr.ss" "setup")
|
|
OPTIONS ...)])
|
|
...)
|