3 ".plt" Archives

3.1 Making ".plt" Archives

The archive contains the collections listed in collections, which should be a list of collection paths; each collection path is, in turn, a list of relative-path strings.

If the #:replace? argument is #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 #:at-plt-home? argument is #t, then the archived collections will be installed into the PLT installation directory instead of the user’s directory if the main "collects" directory is writable by the user. If the #:test-plt-collects? argument is #f (the default is #t) and the #:at-plt-home? argument is #t, then installation fails if the main "collects" directory is not writable.

The optional #: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 #:file-filter argument is the same as for pack-plt.

The #:file-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 is std-filter.

If the #:encode? argument is #f, then the output archive is in raw form, and still must be gzipped and mime-encoded (in that order). 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 is 'file.

The #:unpack-unit argument is usually #f. Otherwise, it must be an S-expression for a mzlib/unit200-style unit that performs the work of unpacking; see Format of ".plt" Archives more information about the unit. If the #:unpack-unit argument is #f, an appropriate unpacking unit is generated.

The #:collections argument is a list of collection paths to be compiled after the archive is unpacked. The default is the null.

If the #:plt-relative? argument is true (the default is #f), the archive’s files and directories are to be unpacked relative to the user’s add-ons directory or the PLT installation directories, depending on whether the #:at-plt-home? argument is true and whether directories specified by #:test-plt-dirs are writable by the user.

If the #:at-plt-home? argument is true (the default is #f), then #:plt-relative? must be true, and the archive is unpacked relative to the PLT installation directory. In that case, a relative path that starts with "collects" is mapped to the installation’s main "collects" directory, and so on, for the following the initial directory names:

• "collects"

• "doc"

• "lib"

• "include"

If #:test-plt-dirs is a list, then #:at-plt-home? must be #t. In that case, when the archive is unpacked, if any of the relative directories in the #: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 #:requires argument should have the shape (list (list coll-path version) ...) where each coll-path is a non-empty list of relative-path strings, and each 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 version. A collection’s version is indicated by the version field of its "info.ss" file.

The #:conflicts argument should have the shape (list coll-path ...) where each coll-path is a non-empty list of relative-path strings. The indicated collections must not be installed at unpacking time.

3.2 Installing a Single ".plt" File

The setup/plt-single-installer module provides a function for installing a single ".plt" file, and setup/plt-installer wraps it with a GUI interface.

3.2.1 Non-GUI Installer

(require setup/plt-single-installer)

The get-dir-proc procedure is called if the installer needs a target directory for installation, and a #f result means that the user canceled the installation. Typically, get-dir-proc is current-directory.

3.2.2 GUI Installer

Returns before the installation process is complete; cleanup-thunk is called on a queued callback to the eventspace active when with-installer-window is invoked.

3.2.3 GUI Unpacking Signature

3.2.4 GUI Unpacking Unit

3.3 Unpacking ".plt" Archives

The main-collects-parent-dir argument is passed along to get-target-plt-directory.

The print-status argument is used to report unpacking progress.

The get-target-directory argument is used to get the destination directory for unpacking an archive whose content is relative to an arbitrary directory.

If force? is true, then version and required-collection mismatches (comparing information in the archive to the current installation) are ignored.

The get-target-plt-directory function is called to select a target for installation for an archive whose is relative to the installation. The function should normally return one if its first two arguments; the third argument merely contains the first two, but has only one element if the first two are the same. If the archive does not request installation for all uses, then the first two arguments will be different, and the former will be a user-specific location, while the second will refer to the main installation.

The on-config-fn function is called once with an S-expression that represents a function to implement configuration information. The second argument to on-config is initial-value, and the function’s result is passes on as the last argument to on-setup-unit.

The on-setup-unit function is called with the S-expression representation of the installation unit, an input port that points to the rest of the file, and the accumulated value. This input port is the same port that will be used in the rest of processing, so if on-setup-unit consumes any data from the port, then that data will not be consumed by the remaining functions. (This means that on-setup-unit can leave processing in an inconsistent state, which is not checked by anything, and therefore could cause an error.) The result of on-setup-unit becomes the new accumulated value.

For each directory that would be created by the archive when unpacking normally, on-directory is called with the directory path and the accumulated value up to that point, and its result is the new accumulated value.

For each file that would be created by the archive when unpacking normally, on-file is called with the file path, an input port containing the contents of the file, and the accumulated value up to that point; its result is the new accumulated value. The input port can be used or ignored, and parsing of the rest of the file continues the same either way. After on-file returns control, however, the input port is drained of its content.

3.4 Format of ".plt" Archives

The extension ".plt" is not required for a distribution archive, but the ".plt"-extension convention 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.

• A procedure that takes a symbol and a failure thunk and returns information about archive for recognized symbols and calls the failure thunk for unrecognized symbols. The information symbols 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.

  • 'requires – collections required to be installed before unpacking the archive, which associated versions; see the documentation of pack for details.

  • 'conflicts – collections required not to be installed before unpacking the archive.

  • 'plt-relative? – a boolean; if true, then the archive’s content should be unpacked relative to the plt add-ons directory.

  • 'plt-home-relative? – a boolean; if true and if 'plt-relative? is true, then the archive’s content should be unpacked relative to the PLT Scheme installation.

  • 'test-plt-dirs – #f or a list of path strings; in the latter case, a true value of 'plt-home-relative? is cancelled if any of the directories in the list (relative to the PLT Scheme installation) is unwritable by the user.

  The procedure is extracted from the archive using the read and eval procedures in a fresh namespace.

• An old-style, unsigned unit using (lib mzlib/unit200) that drives the unpacking process. The unit accepts two imports: a path string for the parent of the main "collects" directory and an unmztar procedure. The remainder of the unpacking process consists of invoking this unit. It is expected that the unit will call unmztar procedure to unpack directories and files that are defined in the input archive after 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.

  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 unpack directory, and

  • a path string for the unpack directory (which can vary for a PLT-relative install when elements of the archive start with "collects", "lib", etc.).

  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 directories 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 read and eval.

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 relative path is combined with the target directory path to get a complete path).

  The 'dir symbol and list are extracted from the archive using read (and the result is not evaluated).

• 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 read (and the result is not evaluated). 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.