WRAP(8)                                                   WRAP(8)

     NAME
          wrap, create, info, inst, wdiff - software package
          preparation

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

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

          wrap/info [ -r root ] file

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

     DESCRIPTION
          These programs are used to manage software packages.

          Packages are identified by a unique name, and should corre-
          spond 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.

          A base package contains all files in the reference tree at
          some time.  Wrap/create creates these by default.

          An update is a package listing only files modified relative
          to some earlier tree.  The time of the prerequisite tree is
          included in the update.  The target tree's time is the time
          of the base package or the time of the last installed
          update.  The update cannot be installed unless the target
          tree is dated at or after the prerequisite time.
          Wrap/create -u creates updates when no prefix is given.

          A partial update is like an update but usually only contains
          a few subtrees.  For example, one might create a partial
          update of the Plan 9 distribution package containing only
          changes to acme. Installing a partial update does not change
          the target tree's time.  Wrap/create -u creates partial
          updates when one or more prefixes are given.

          Wrap/inst installs base packages, updates, and partial
          updates, taking into account version conflicts, prerequi-
          sites, 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 archive
          with installed files.  Wdiff -l merely lists those files
          modified or removed since the package or update was created,
          and can be used on an installed tree instead of a package

     Page 1                       Plan 9             (printed 3/29/24)

     WRAP(8)                                                   WRAP(8)

          file.  When used with an installed tree, only files modified
          or removed since the most recent updates are listed; wdiff
          -p shows changes since the last full package.

          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 writ-
          ten over an installed file only if the installed file is
          from an update older than the one currently under considera-
          tion; 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), contain-
          ing 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 speci-
          fied.  If no proto is specified,
          /sys/lib/sysconfig/proto/allproto is used.

          If create is given the -u flag, it compares the files con-
          tained 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.  If prefixes are specified, create cre-
          ates a partial update.

          The -l flag to create causes it to write a list of the files
          it would have included in an archive, rather than preparing
          the archive itself.

     Page 2                       Plan 9             (printed 3/29/24)

     WRAP(8)                                                   WRAP(8)

          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 distribu-
          tion tree:

               wrap/create -r /plan9dist -d 'Plan 9 — Third Edition' \
                    -p plan9proto plan9 | gzip > plan9.9gz

          Create a base package as well as a full update.  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' \
                    -p plan9proto -t $now plan9 | gzip > plan9.9gz

               wrap/create -ur /plan9dist -t $now oldplan9.9gz |
                    gzip > update.9gz

          Create a partial update containing new VGA software:

               wrap/create -ur /plan9dist plan9.9gz `{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 on a kfs(4) file system.

               disk/kfscmd allow

     Page 3                       Plan 9             (printed 3/29/24)

     WRAP(8)                                                   WRAP(8)

               mount /srv/kfs /n/kfs
               wrap/inst -or /n/kfs vga.9gz
               disk/kfscmd disallow

          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 differ-
          ences and decide which files to overwrite with ones from the
          package; to actually overwrite the files, change wdiff to
          inst -F and send the command again.

          Wrap an installed package quux for redistribution as a stan-
          dalone package:

               wrap/create -d 'Repackaged quux' -r /root \
                    -p /root/wrap/quux/time/proto quux | gzip > newquux.9gz

          To view and then package just your changes:

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

          Note that wrap/wdiff -l does not require the original
          archive: it can use checksums to determine which files have
          changed.  By default (without -l) an archive is required for
          access to the original files.

     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.

     Page 4                       Plan 9             (printed 3/29/24)

     WRAP(8)                                                   WRAP(8)

          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

     SEE ALSO
          diff(1), md5sum (in sum(1)), tar(1), proto(2), archfs(4),
          mkfs(8)

     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 to overwrite
          updated files that are not normally writable.

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

     Page 5                       Plan 9             (printed 3/29/24)