1 Running setup-plt Executable
2 Running setup-plt from Scheme
3 ".plt" Archives
4 Finding Installation Directories
5 "info.ss" File Format
6 Reading "info.ss" Files
7 Paths Relative to "collects"
8 Cross-References for Installed Manuals
Index
On this page:
3.1 Making ".plt" Archives
pack-collections-plt
pack-collections
pack-plt
pack
std-filter
mztar
3.2 Installing a Single ".plt" File
3.2.1 Non-GUI Installer
run-single-installer
3.2.2 GUI Installer
run-installer
on-installer-run
with-installer-window
run-single-installer
3.2.3 GUI Unpacking Signature
setup: plt-installer^
3.2.4 GUI Unpacking Unit
3.3 Unpacking ".plt" Archives
unpack
fold-plt-archive
3.4 Format of ".plt" Archives
Version: 4.0.2

 

3 ".plt" Archives

3.1 Making ".plt" Archives

 (require setup/pack)

Although the mzc executable can be used to create ".plt" files (see mzc: PLT Compilation and Packaging), the setup/pack library provides a more general Scheme API for making ".plt" archives:

(pack-collections-plt

 

 

 

dest

 

 

 

name

 

 

 

collections

 

 

 [

#:replace? replace?

 

 

 

#:at-plt-home? at-home?

 

 

 

#:test-plt-collects? test?

 

 

 

#:extra-setup-collections collection-list

 

 

 

#:file-filter filter-proc])

 

  void?

  dest : path-string?

  name : string?

  collections : (listof (listof path-string?))

  replace? : boolean? = #f

  at-home? : boolean? = #f

  test? : boolean? = #t

  collection-list : (listof path-string?) = null

  filter-proc : (path-string? . -> . boolean?) = std-filter

Creates the ".plt" file specified by the pathname dest, using the name as the name reported to setup-plt as the archive’s description.

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.

(pack-collections

 

dest

 

 

 

 

 

 

name

 

 

 

 

 

 

collections

 

 

 

 

 

 

replace?

 

 

 

 

 

 

extra-setup-collections

 

 

 

 

 

 [

filter

 

 

 

 

 

 

at-plt-home?])

 

 

void?

  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

Old, keywordless variant of pack-collections-plt for backward compatibility.

(pack-plt

 

dest

 

 

 

 

 

 

name

 

 

 

 

 

 

paths

 

 

 

 

 

 [

#:file-filter filter-proc

 

 

 

 

 

 

#:encode? encode?

 

 

 

 

 

 

#:file-mode file-mode-sym

 

 

 

 

 

 

#:unpack-unit unit200-expr

 

 

 

 

 

 

#:collections collection-list

 

 

 

 

 

 

#:plt-relative? plt-relative?

 

 

 

 

 

 

#:at-plt-home? at-plt-home?

 

 

 

 

 

 

#:test-plt-dirs dirs

 

 

 

 

 

 

#:requires mod-and-version-list

 

 

 

 

 

 

#:conflicts mod-list])

 

 

void?

  dest : path-string?

  name : string?

  paths : (listof path-string?)

  filter-proc : (path-string? . -> . boolean?) = std-filter

  encode? : boolean? = #t

  file-mode-sym : symbol? = 'file

  unit200-expr : any/c = #f

  collection-list : (listof path-string?) = null

  plt-relative? : any/c = #f

  at-plt-home? : any/c = #f

  dirs : (or/c (listof path-string?) false/c) = #f

  

mod-and-version-list

 

:

 

(listof (listof path-string?)

        (listof exact-integer?))

 

=

 

null

  mod-list : (listof (listof path-string?)) = null

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. 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 #: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:

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.

(pack

 

dest

 

 

 

 

 

 

name

 

 

 

 

 

 

paths

 

 

 

 

 

 

collections

 

 

 

 

 

 [

filter

 

 

 

 

 

 

encode?

 

 

 

 

 

 

file-mode

 

 

 

 

 

 

unpack-unit

 

 

 

 

 

 

plt-relative?

 

 

 

 

 

 

requires

 

 

 

 

 

 

conflicts

 

 

 

 

 

 

at-plt-home?])

 

 

void?

  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

Old, keywordless variant of pack-plt for backward compatibility.

(std-filter p)  boolean?

  p : path-string?

Returns #t unless p, after stripping its directory path and converting to a byte string, matches one of the following regular expressions: ^CVS$, ^[.]svn$, ^[.]cvsignore, ^compiled$, ^doc, ~$, ^#.*#$, ^[.]#, or [.]plt$.

(mztar path output filter file-mode)  void?

  path : path-string?

  output : output-port?

  filter : (path-string? . -> . boolean?)

  file-mode : (symbols 'file 'file-replace)

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.

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-single-installer wraps it with a GUI interface.

3.2.1 Non-GUI Installer

 (require setup/plt-single-installer)

(run-single-installer file get-dir-proc)  void?

  file : path-string?

  get-dir-proc : (-> (or/c path-string? false/c))

Creates a separate thread and namespace, runs the installer in that thread with the new namespace, and returns when the thread completes or dies. It also creates a custodian (see Custodians) to manage the created thread, sets the exit handler for the thread to shut down the custodian, and explicitly shuts down the custodian when the created thread terminates or dies.

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

 (require setup/plt-installer)

The "setup/plt-installer" library in the setup collection defines procedures for installing a ".plt" archive with a GUI (using the facilities of scheme/gui/base).

(run-installer filename)  void?

  filename : path-string?

Run the installer on the ".plt" file in filename and show the output in a window. This is a composition of with-installer-window and run-single-installer with a get-dir-proc that prompts the user for a directory (turning off the busy cursor while the dialog is active).

(on-installer-run)  (-> any)

(on-installer-run thunk)  void?

  thunk : (-> any)

A thunk that is run after a ".plt" file is installed.

(with-installer-window

 

do-install

 

 

 

 

 

 

cleanup-thunk)

 

 

void?

  

do-install

 

:

 

((or/c (is-a?/c dialog%) (is-a?/c frame%))

 . -> . void?)

  cleanup-thunk : (-> any)

Creates a frame, sets up the current error and output ports, and turns on the busy cursor before calling do-install in a separate thread.

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.

(run-single-installer file get-dir-proc)  void?

  file : path-string?

  get-dir-proc : (-> (or/c path-string? false/c))

The same as the sole export of setup/plt-single-installer, but with a GUI.

3.2.3 GUI Unpacking Signature

 (require setup/plt-installer-sig)

setup:plt-installer^ : signature

Provides two names: run-installer and on-installer-run.

3.2.4 GUI Unpacking Unit

 (require setup/plt-installer-unit)

Imports mred^ and exports setup:plt-installer^.

3.3 Unpacking ".plt" Archives

 (require setup/unpack)

The setup/unpack library provides raw support for unpacking a ".plt" file.

(unpack

 

archive

 

 

 

 

 

 [

main-collects-parent-dir

 

 

 

 

 

 

print-status

 

 

 

 

 

 

get-target-directory

 

 

 

 

 

 

force?

 

 

 

 

 

 

get-target-plt-directory])

 

 

void?

  archive : path-string?

  main-collects-parent-dir : path-string? = (current-directory)

  

print-status

 

:

 

(string? . -> . any)

 

 

 

=

 

(lambda (x) (printf "~a\n" x))

  

get-target-directory

 

:

 

(-> path-string?)

 

 

 

=

 

(lambda () (current-directory))

  force? : any/c = #f

  

get-target-plt-directory

 

:

 

(path-string?

 path-string?

 (listof path-string?)

 . -> . path-string?)

 

 

 

=

 

(lambda (preferred-dir main-dir options)

  preferred-dir)

Unpacks archive.

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.

(fold-plt-archive

 

archive

 

 

 

 

 

 

on-config-fn

 

 

 

 

 

 

on-setup-unit

 

 

 

 

 

 

on-directory

 

 

 

 

 

 

on-file

 

 

 

 

 

 

initial-value)

 

 

any/c

  archive : path-string?

  on-config-fn : (any/c any/c . -> . any/c)

  on-setup-unit : (any/c input-port? any/c . -> . any/c)

  on-directory : (path-string? any/c . -> . any/c)

  on-file : (path-string? input-port? any/c . -> . any/c)

  initial-value : any/c

Traverses the content of archive, which must be a ".plt" archive that is created with the default unpacking unit and configuration expression. The configuration expression is not evaluated, the unpacking unit is not invoked, and not files are unpacked to the filesystem. Instead, the information in the archive is reported back through on-config, on-setup-unit, on-directory, and on-file, each of which can build on an accumulated value that starts with initial-value and whose final value is returned.

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

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: