10 raco pack: Packing Library Collections

The raco pack command creates an archive of files and directories. Formerly, such archives were used directly to distribute library files to Racket users, but the package manager (see Package Management in Racket) is now the preferred mechanism for distribution.

A packed archive usually has the suffix ".plt". The raco pkg command recognizes a ".plt" archive for installation as a package. The raco setup command (see raco setup: Installation Management) also supports ".plt" unpacking and installation when using the -A flag, but such installations do not benefit from the more general management facilities of raco pkg, while the raco unpack command (see raco unpack: Unpacking Library Collections) unpacks an archive locally without attempting to install it. DrRacket recognizes the ".plt" and currently treats such an archive in the same way as raco setup -A.

An archive contains the following elements:

• A set of files and directories to be unpacked, and flags indicating whether they are to be unpacked relative to the Racket add-ons directory (which is user-specific), the Racket installation directory, or a user-selected directory.

  The files and directories for an archive are provided on the command line to raco pack, either directly or in the form of collection names when the --collect flag is used.

  The --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 Racket installation directory when unpacking. The --collection-plt flag implies --at-plt. The --all-users flag overrides --at-plt, and it indicates that the files and directories should be unpacked relative to the Racket installation directory, always.

• 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 the --replace flag enables replacing for all files in the archive.

• A list of collections to be set-up (via raco setup) after the archive is unpacked; the ++setup flag adds a collection name to the archive’s list, but each collection for --collection-plt is added automatically.

• A name for the archive, which is reported to the user by the unpacking interface; the --plt-name flag sets the archive’s name, but a default name is determined automatically when using --collect.

• A list of required collections (with associated version numbers) and a list of conflicting collections; the raco pack command always names the "racket" collection in the required list (using the collection’s pack-time version), raco pack 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 raco pack extracts other requirements and conflicts from the "info.rkt" files of collections when using --collect.

Specify individual directories and files for the archive when not using --collect. Each file and directory must be specified with a relative path. By default, if the archive is unpacked with DrRacket, the user will be prompted for a target directory, and if raco setup is used to unpack the archive, the files and directories will be unpacked relative to the current directory. If the --at-plt flag is provided, the files and directories will be unpacked relative to the user’s Racket add-ons directory, instead. Finally, if the --all-users flag is provided, the files and directories will be unpacked relative to the Racket installation directory, instead.

Use the --collect flag to pack one or more collections; sub-collections can be designated by using a / as a path separator on all platforms. In this mode, raco pack automatically uses paths relative to the Racket installation or add-ons directory for the archived files, and the collections will be set-up after unpacking. In addition, raco pack consults each collection’s "info.rkt" file, as described below, to determine the set of required and conflicting collections. Finally, raco pack consults the first collection’s "info.rkt" file to obtain a default name for the archive. For example, the following command creates a "sirmail.plt" archive for distributing a "sirmail" collection:

  raco pack --collect sirmail.plt sirmail

When packing collections, raco pack checks the following fields of each collection’s "info.rkt" file (see "info.rkt" File Format):

• requires — A list of the form (list (list coll vers) ...) where each coll is a non-empty list of relative-path strings, and each 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 vers.

  A collection’s version is indicated by a version field in its "info.rkt" file, and the default version is the empty list. The version sequence generalized major and minor version numbers. For example, version '(2 5 4 7) of a collection can be used when any of '(), '(2), '(2 5), '(2 5 4), or '(2 5 4 7) is required.

• conflicts — A list of the form (list coll ...) where each coll is a non-empty list of relative-path strings. The indicated collections must not be installed at unpacking time.

For example, the "info.rkt" file in the "sirmail" collection might contain the following info declaration:

#lang info

(define name "SirMail")

(define mred-launcher-libraries (list "sirmail.rkt"))

(define mred-launcher-names (list "SirMail"))

(define requires (list (list "mred")))

Then, the "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, and that "mred" has the same version as when "sirmail.plt" was created.

10.1 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.

• An S-expression matching

  (lambda (request failure)

  (case request

  [(name) name]

  [(unpacker) (quote mzscheme)]

  [(requires) (quote requires)]

  [(conflicts) (quote conflicts)]

  [(plt-relative?) plt-relative?]

  [(plt-home-relative?) plt-home-relative?]

  [(test-plt-dirs) test-dirs]

  [else (failure)]))

  where the name, requires, etc., meta-variables stand for S-expressions as follows:

  • name — a human-readable string describing the archive’s contents. This name is used only for printing messages to the user during unpacking.

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

  • conflicts — a list of 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 Racket installation.

  • test-plt-dirs — #f or a 'paths where paths is 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 Racket installation) is unwritable by the user.

  The S-expression is extracted from the archive using read (and the result is not evaluated).

• An S-expression matching

  (unit (import main-collects-parent-dir mzuntar)

  (export)

  (mzuntar void)

  (quote collections))

  where collections is a list of collection paths (where each collection path is a list of strings); once the archive is unpacked, raco setup will compile and setup the specified collections.

  The S-expression is extracted from the archive using read (and the result is not evaluated).

The archive continues 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 S-expression. 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.

10.2 API for Packing

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 Racket 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 the S-expression that describes unpacking; see Format of ".plt" Archives more information about the unit. If the #:unpack-unit argument is #f, an appropriate S-expression 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 Racket 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 Racket 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.rkt" 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.