4 Packaging Library Collections
Before creating a ".plt" archive to distribute, consider instead posting your package on PLaneT.
The command-line flags --plt and --collection-plt direct mzc to create an archive for distributing library files to PLT Scheme users. A distribution archive usually has the suffix ".plt", which DrScheme recognizes as an archive to provide automatic unpacking facilities. The setup-plt program also supports ".plt" unpacking.
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 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 --plt or in the form of collection names with --collection-plt.
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 PLT Scheme 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 PLT Scheme 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 mzc’s --replace flag enables replacing for all files in the archive.
A list of collections to be set-up (via Setup PLT) after the archive is unpacked; mzc’s ++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; mzc’s --plt-name flag sets the archive’s name, but a default name is determined automatically for --collection-plt.
A list of required collections (with associated version numbers) and a list of conflicting collections; mzc always names the "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 "info.ss" files of collections for --collection-plt.
Use the --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 setup-plt 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 to mzc, the files and directories will be unpacked relative to the user’s PLT Scheme add-ons directory, instead. Finally, if the --all-users flag is provided to mzc, the files and directories will be unpacked relative to the PLT Scheme installation directory, instead.
Use the --collection-plt 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, 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 "info.ss" file, as described below, to determine the set of required and conflicting collections. Finally, mzc consults the first collection’s "info.ss" file to obtain a default name for the archive. For example, the following command creates a "sirmail.plt" archive for distributing a "sirmail" collection:
mzc --collection-plt sirmail.plt sirmail
When packing collections, mzc checks the following fields of each collection’s "info.ss" file (see "info.ss" 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 it’s "info.ss" 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.ss" file in the "sirmail" collection might contain the following info declaration:
(define name "SirMail") |
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 (not just MzScheme), and that MrEd has the same version as when "sirmail.plt" was created.
4.1 Scheme API for Packaging
Although mzc’s command-line interface is sufficient for most purposes, see the setup/pack library for a more general interface for constructing archives.