WRAP(8)

NAME

wrap, create, info, inst, wdiff − software package preparation

SYNOPSIS

wrap/create [ -uUv ] [ -d desc ] [ -p proto ] [ -r root ] [ -t time ] name [ prefix... ]

wrap/inst [ -ovxF ] [ -r root ] file [ prefix... ]

wrap/info [ -r root ] file

wrap/wdiff [ -bl ] [ -r root ] file [ prefix... ]

DESCRIPTION

These programs are used to manage software packages.

Packages are identified by a unique name, and should correspond to some reference tree. For example, the base Plan 9 installation package is named plan9 and corresponds to the root of the Plan 9 distribution file server at Bell Labs. Successive versions are distinguished by a date stored as seconds since January 1, 1970. There are three kinds of archive:

A package is an archive of the entire reference tree. Create writes these by default.

An update to a particular package contains only files from the reference tree that differ from those in the package, and is usually restricted to chosen subtrees. For example, one might create an update of the Plan 9 distribution package containing only changes to acme. Updates can only be in reference to packages, not other updates. An update can only be installed if the package it is updating is already installed. Create writes these when given the -u flag.

An update package is a hybrid of the two: it is an update in that it contains only files changed since some earlier package. At the same time, once installed it functions as a full package for the purposes of satisfying the prerequisites of later updates. Create writes these when given the -U flag.

Wrap/inst installs packages and updates, taking into account version conflicts, prerequisite packages, and the possibility of local modifications. Wrap/info prints information about a package or update, and wrap/wdiff runs diff to compare files in a package or update with installed files; wdiff -l merely lists those files modified or removed since the package or update was created.

To decide whether a given update contains files fresher than those currently installed on the system, it is not enough to compare the update’s date with the date of the most recent update to the same package: updates may only involve parts of a package, so updates can only be partially ordered. As an example, if you have a full Plan 9 distribution package and two updates, one to acme and one to aux/vga, it is not correct to require one to be installed before the other, or to prohibit one from being installed once the other has been. To handle such cases, date comparisons must made on a per-file basis rather than a per-update basis.

To do this, create includes in each package and update a list /wrap/name/time/md5sum of the contained files along with their MD5 checksums. A file in an update will be written over an installed file only if the installed file is from an update older than the one currently under consideration; otherwise a warning will be printed. If the currently installed file does not have the expected checksum, that usually indicates the presence of local modifications. In such cases, the file is not overwritten and a warning is printed. This behavior can be overriden, as described below.

Create writes to standard output a package with name name and time stamp time (by default, the current time), containing the files named by proto (see proto(2)). In addition to the named files, a package may contain a one-line file describing its contents; the file contains desc, when specified. If no proto is specified, /sys/lib/sysconfig/proto/allproto is used.

If create is given the -u flag, it compares the files contained in the named package (which may be a file or the name of a package installed in the root; see below) with those currently in the file system, and writes an update archive that only contains modified files. If no proto is given, it uses the proto used to make the archive being updated. If any prefix es are specified, the update is restricted to just those changes that concern files having names with any of the prefix es as a prefix. Without the -u flag, prefixes are not allowed. If create is given the -U flag, it creates an update package.

Inst unpacks a package or update created by create. It extracts from the package or update the files with names starting with prefixes (default all files) and installs them in the tree rooted at root (default /). Inst attempts to set the modes on the extracted files to those in the archive. If the -o flag is given, install will attempt to set the owner and group as well; this is only possible if the allow command has been typed at the file server (see fs(8) or kfscmd(8)). The -x flag causes inst to print what actions it would do to install the package, but not actually perform them. As described above, inst performs a number of checks to avoid overwriting new files with old ones; these checks are disabled by the -F flag.

EXAMPLES

Create a package consisting of the entire Plan 9 distribution tree:

wrap/create -r /plan9dist -d ’Plan 9 — Third Edition’ \
-p /sys/lib/sysconfig/proto/allproto plan9 | gzip > plan9.9gz

Create a package as well as an update package. Note that we need to use the -t flag to make sure both have the same timestamp.

now=‘{date -n}
wrap/create -r /plan9dist -d ’Plan 9 — Third Edition’ -t $now \
-p /sys/lib/sysconfig/proto/allproto plan9 | gzip > plan9.9gz
wrap/create -Ur /plan9dist -t $now old.9gz | gzip > updatepkg.9gz

Create an update containing new VGA software:

wrap/create -ur /plan9dist ‘{cat /tmp/vgafiles} | gzip >vga.9gz

where /tmp/vgafiles is a text file containing:

/386/bin/aux/vga
/lib/vgadb
/sys/src/cmd/aux/vga
/sys/src/9/pc/devvga.c
/sys/src/9/pc/vga

Note that since the strings are just prefixes, the last line will match files such as /sys/src/9/pc/vgamach64xx.c and /sys/src/9/pc/vga.h.

Install the VGA update:

wrap/inst vga.9gz

Suppose that the update contains a new /386/bin/aux/vga and /lib/vgadb but those files have been changed since they were installed. Install will produce the following messages:

skipping /386/bin/aux/vga
skipping /lib/vgadb: locally updated
wrap/wdiff vga.9gz \
/386/bin/aux/vga \
/lib/vgadb

The printed command can be executed to inspect the differences and decide which files to overwrite with ones from the package; to actually overwrite the files, change wdiff to update -F and send the command again.

Wrap an installed package quux for redistribution as a standalone package:

wrap/create -r /root -a ’Repackaged quux’ quux \
/wrap/quux/time/proto | gzip > newquux.9gz

To view and then package just your changes:

wrap/wdiff -r /root quux.9gz
wrap/create -u -r /root quux >quuxpatch.9gz

FILES

Installed package information is maintained via a small tree rooted at dst/wrap. For each package and update, there is a directory name/time that contains the following files:

desc The description for the package, if any.

md5sum
A sorted list of all files in the package, along with their MD5 checksums.

package
An empty file, if this is a package.

proto
The proto file used to create this package.

remove
For an update, the list of obsolete files that should be removed.

update
If this is an update, contains the decimal date of the package being updated.

done The installation of the package completed successfully.

Update packages contain both package and update files. A package is itself an (optionally gzipped) mkfs-style archive that contains /wrap/name and /wrap/name/time as the only directories under /wrap. The entries must be the first ones in the archive to allow for quick access in compressed archives.

SOURCE

/sys/src/cmd/wrap

BUGS

Because inst sets the modes on the created files, permission checking must be turned off on the file server in order to create files in unwritable directories or overwrite updated files that are not normally writable.

In the absence of the -l flag (which can use the MD5 checksums alone) wrap/wdiff must uncompress the entire archive to pass it to archfs(4).

The terminology can be confusing.

Plan 9 — July 29, 2000

Museum

Related Articles