#
Chapter 6
Creating Distribution Archives

The command-line flags `--plt` and `--collection-plt` direct `mzc` to create an archive for distributing files to PLT users. A distribution archive usually has the suffix `.plt`, which Help Desk and DrScheme recognize as archives 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 add-ons directory (which is user-specific), the PLT 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 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 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 Help Desk or 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 PLT 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 installation directory, instead.

Use the `--collection-plt` flag to pack one or more collections; sub-collections can be designated by using a forward slash (``/'') as a path separator on all platforms. In this mode, `mzc` automatically uses paths relative to the PLT 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 section 7):

- `requires` -- a list of the form `(`list` (`list` coll-path vers) `···`)` where each `coll-path` 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-path `···`)` where each `coll-path` 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:

    (module info (lib "infotab.ss" "setup")
      (define name "SirMail")
      (define mred-launcher-libraries (list "sirmail.ss"))
      (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 (not just MzScheme), and that MrEd has the same version as when `sirmail.plt` was created.

Although `mzc`'s command-line interface is sufficient for most purposes, the `pack.ss` library of the `setup` collection provides a general interface for constructing archives.