PKGINST(1M-SysV) RISC/os Reference Manual PKGINST(1M-SysV)
NAME
pkginst - MIPS software packaging/installation system
DESCRIPTION
This manual page is the top-level description of the MIPS
software packaging and installation tools. It is suggested
that you start here if you are new to the system and need to
understand them.
These tools provide a systematic and automated means of
packaging MIPS software. They can be thought of as being
composed of two major subsystems, one for packaging, and one
for installation.
The packaging system was designed first to meet the needs of
MIPS, but they are provided as part of the RISC/os source
release and could be used by MIPS OEMS as well. Also, cer-
tain of the tools, which have proven to be generally useful
for ongoing systems administration chores, are provided in
the RISC/os binary release.
The packaging subsystem is used on a ``packaging host''
machine, to prepare software released by developers to
software QA for release to Manufacturing and internally
within MIPS. Both the creation of tapes and the serving of
packages for installation via the network are supported.
The installation subsystem is used on a target machine onto
which a software package is to be installed. The installa-
tion subsystem provides several important services, such as
support for update installs including automatic detection
and preservation of locally modified files, and automatic
space accounting. Automatic space accounting ensures that
there will be enough free disk space to install the software
before starting to install files from the package.
The system supports the division of a software package into
independently installable subpackages, allowing for optional
subpackages to be installed at the user's discretion. This
also provides for the re-installation of a particular sub-
package should any of its files have been lost since it was
originally installed.
The system is implemented with a set of Bourne shell scripts
and C programs. Some of the executables are used only during
packaging (for example, the pkg_boms script), some only dur-
ing installation (such as inst_presv), and still others for
both (for example, comply).
A data structure called the packaging information tree
directs the actions of the tools as packaging and installa-
tion are performed. This data structure is a small
Printed 1/15/91 Page 1
PKGINST(1M-SysV) RISC/os Reference Manual PKGINST(1M-SysV)
directory tree containing several data files and archives
unique to the package. Most of the work in packaging a
release consists of setting up this tree.
During installation of a package, its packaging information
tree is also used to hold various log and data files gen-
erated during the installation process (example:
...pkgname/lib/comply.out).
Finally, skeletal packaging information trees, a subset of
the files they contain during the installation process, are
usually kept on the system for record keeping purposes. This
skeletal tree keeps such files as the BOM files and preserve
logs from the installation.
Since the installation tools rely on them for directions,
certain parts of the packaging information trees are carried
to the target system as part of the installation process.
PACKAGES AND SUBPACKAGES. AND...
The packaging system provides a means to group sets of
related files within a package into subpackages. Every
software package contains at least one subpackage. Certain
subpackages may occur in more than one package. For example,
the base compiler system (C compiler front-end and common
back-end components) comprises a subpackage present in both
the RISC/os operating system packages, but which is also
available in a separate package containing only the base
compiler system.
Subpackages can therefore be viewed as modules which may be
recombined to create new packages.
Another level of packaging hierarchy exists, called sub-
subpackages. This level of hierarchy is not visible to
users. As might be guessed, it allows for subdivision of
subpackages into related groups of files. It is intended as
an aid to the integration of subpackages which contain logi-
cal groupings of files to be provided by different software
developers. The only real reflection of the existence of
sub-subpackages is that the bom files for a subpackage can
be split into multiple files to be supplied by each
developer when the software is released to software QA for
integration.
$Pkgroot AND $Pkg
All of the packaging and installation tools rely on two
environment variables to direct them to the rest of the
information they need in order to work. The first, $Pkgroot,
identifies the build tree containing the software to be
packaged (on the packaging side), or the tree into which
software is to be installed (on the installation side).
Page 2 Printed 1/15/91
PKGINST(1M-SysV) RISC/os Reference Manual PKGINST(1M-SysV)
The second, $Pkg, identifies the top of the packaging infor-
mation tree to be used for packaging or installation.
It is common for several packages to be packaged under a
single build tree; for example, consider a build tree,
/user/mips43/build, under which complete RISC/os, C com-
piler, Pascal compiler, and f77 compiler packages have been
built. In all cases, $Pkgroot would be set to
``/user/mips43/build'', and $Pkg would be switched to the
packaging information tree for the particular software to be
packaged. The packaging information trees would typically
be found in /user/mips43/usr/pkg/lib.
The tools are written in such a manner that there is no sen-
sitivity to the directory from which they are started, nor
do they inherit or rely on any components of the user's PATH
variable.
FILES
This section describes the files used by the packaging and
installation tools. A solid understanding of this structure
is very important to understanding the overall
packaging/installation system.
1. Files outside of the packaging
$Pkgroot/etc/installlog
Is the installation log; this file only exists on tar-
get systems. Since $Pkgroot is usually ``/'' during an
installation, this is usually /etc/installlog. This
file is used to keep track of the installations that
have been performed on a particular host. Within the
installation system, it is used to help determine
whether extant files were installed from a previous
installation of a MIPS software package. In the future,
it may also serve to automate the checking of software
prerequisites. For more details on the format of this
file, see installlog(4).
2. Files in the packaging tree:
The following tree structures are employed by the
packaging/installation tools. They occur both on host sys-
tems where packaging is to take place, and on target systems
where installation is to take place. Various parts of these
trees may be used only on the host side, only on the target
side, or on both sides. Which parts are used where is
explained below.
.../pkg/
This is the top of the packaging tree. (This should
not be confused with packaging information trees, which
may or may not be kept as subdirectories within this
packaging tree). These trees occur:
Printed 1/15/91 Page 3
PKGINST(1M-SysV) RISC/os Reference Manual PKGINST(1M-SysV)
- On target systems: /usr/pkg;
- On the miniroot: /pkgname;
- On systems where packaging takes place, in the build
tree:
$Pkgroot/usr/pkg;
- On systems where packaging takes place: /usr/pkg.
.../pkg/lib/
This subtree usually contains the packaging information
trees for various packages.
.../pkg/bin/
This is the directory for global versions of executable
packaging and installation tools. When a release is
packaged, the installation tools to be put in the instd
archive or the miniroot are searched for first in
$Pkg/bin, then in $Pkgroot/usr/pkg/bin, and finally in
/usr/pkg/bin.
.../pkg/src/
Source directory for the packaging system tools.
3. The packaging information trees:
.../pkg/lib/pkgname/
This is the root of the packaging information tree for
a particular package. The pkgname component can be any
name, but must be unique among all releases/versions.
(This allows the skeletal packaging information trees
which are left on a target system subsequent to instal-
lation to coexist without naming conflicts). One con-
vention that can ensure this is to use the 02- level
part number for the package, including the rev level.
Symbolic links can be established to provide a more
mnemonically friendly alias for the current version.
.../pkg/lib/pkgname/lib/
This subdirectory in the packaging information tree
holds various files used in the course of packaging and
installation, as explained below.
.../pkg/lib/pkgname/lib/miniroot
This file, created during packaging of RISC/os releases
by the pkg_miniroot tool, is the miniroot filesystem
for the package. It exists only on the host (packaging)
system, i.e., it is not present in the packaging infor-
mation tree on a target system where installation is to
take place.
.../pkg/lib/pkgname/lib/tapevol
This is the bootable tape header file (sash and for-
mat), created during packaging of RISC/os releases by
the pkg_tapevol tool. Just like the miniroot, this file
Page 4 Printed 1/15/91
PKGINST(1M-SysV) RISC/os Reference Manual PKGINST(1M-SysV)
is only present on the host (packaging) side.
.../pkg/lib/pkgname/lib/instd
This file is a tar archive of the packaging information
tree for use on the target (installation) side. This
file is present only on the host (packaging) side. Not
all files present in the packaging information tree on
the host (packaging) side are contained in this
archive. For example, .../lib/miniroot is not packaged
into this archive. Only those files required for an
installation are packaged into instd.
.../pkg/lib/pkgname/lib/subpkgname.preserves
These files, if present, are the preserve lists for the
subpackages in the package. These files are present on
both the host (packaging) and target (installation)
sides. They are used as part of the input to the
preserve program during installation, to control the
preservation of local files during update installs.
.../pkg/lib/pkgname/lib/subpkgname.findmods
These files are the output files from running the find-
mods program during update installs. They occur only on
the target (installation) side, and only when findmods
is enabled for update installations.
.../pkg/lib/pkgname/boms/
This directory contains the split bom files, merged bom
files, and size files for the sub- and sub-subpackages
within the package.
.../pkg/lib/pkgname/boms/bomname
This is the merged bom for a subpackage. bomname is an
arbitrary name. This component will be transported to
a packaging information tree on the target system (via
the instd archive) for use during installation and as
part of the documentation of the package.
.../pkg/lib/pkgname/boms/bomname.sizes
This is the size information file, created by
pkg_sizes, corresponding to the bom file bomname.
These files are used during installations to determine
whether there is enough space present on the target
system to install the package.
.../pkg/lib/pkgname/boms/splitbomname
These are the split bom files for a subpackage. These
files are not transported to the target system; The
hierarchy of split bom files is an aid for the develop-
ment of subpackages as a set of sub-subpackages, typi-
cally each provided by a different software developer.
These files are merged into complete bom files during
Printed 1/15/91 Page 5
PKGINST(1M-SysV) RISC/os Reference Manual PKGINST(1M-SysV)
packaging by the pkg_boms tool.
.../pkg/lib/pkgname/conv/
This directory contains conversion scripts to be
applied when a new revision of a package is installed
as an update. The scripts should be named
subpkgname.name, where subpkgname is one of the sub-
package names for the package, and name is a mnemoni-
cally meaningful name selected by the developer. Usu-
ally this name will be selected according to what
conversion the script performs.
For example, consider a package with a subpackage
called ``root'', which contains a file called
``/etc/fstab''. The name for a conversion script to
convert this file might be ``.../conv/root.fstab''.
These scripts, if present, are executed after a package
or subpackage has been installed as an update. Only
those scripts for selected subpackages are executed.
Conversion scripts are executed in the following order:
scripts for subpackages are executed in the order the
subpackages are listed in the pkginfo file; within sub-
packages, scripts are executed in the lexical order of
the .name part of their filenames.
Conversion scripts should set the PATH environment
variable to ``/bin:/usr/bin:/etc'', and depend only on
the commands present on the miniroot filesystem.
(Please see the miniroot.ls file for an operating sys-
tem package or the pkg_miniroot scripts to determine
what commands are present on the miniroot filesystem.)
Conversion scripts should not depend on the fact that
the file to be converted hasn't yet been converted,
i.e., the conversion of a file which has already been
converted should be a no-op, leaving the file
unchanged.
.../pkg/lib/pkgname/bin/*
This directory contains executables which are used dur-
ing the packaging or installation of the package. Cer-
tain of the executables are used only on the host
(packaging) side; others are used only on the target
(installation) side. Some exist on both sides. In gen-
eral, the packaging and installation tools set their
PATH variables such that $Pkg/bin is always searched
first; next, $Pkgroot/usr/pkg/bin is searched, and
finally /usr/pkg/bin.
This allows a good deal of flexibility. Since $Pkg/bin
is searched first, override versions of particular
Page 6 Printed 1/15/91
PKGINST(1M-SysV) RISC/os Reference Manual PKGINST(1M-SysV)
executables may be placed here as required by a partic-
ular package. On the packaging side, if the package
includes these packaging tools, then the versions in
$Pkgroot/usr/pkg/bin (i.e., the tools from the release)
will be used. If the package does not include these
tools, then the tools present in /usr/pkg/bin will be
used.
On the installation side, every package ships with a
complete set of executables in $Pkg/bin; on the packag-
ing side, only overrides of the defaults in
$Pkgroot/usr/pkg/bin or /usr/pkg/bin are present.
.../pkg/lib/pkgname/bin/{inst_env,pkg_env}
These files are sourced by all top-level
packaging/installation scripts, setting up various
environment variables directing the actions of the
tools when a package is packaged or installed. Many
defaults are set in these files. As with other of the
executables, these files are searched for first here,
then in $Pkgroot/usr/pkg/bin and finally in
/usr/pkg/bin.
.../pkg/lib/pkgname/pkginfo
This is the master packaging information file for the
package. It is the input file for the pkginfo program,
which is used in turn by other tools extract informa-
tion used to direct their actions when packaging or
installing the package. See pkginfo(4) for a detailed
description of the contents of this file.
SEE ALSO
pkg(1M), inst(1M), pkginfo(1M).
pkginfo(4), pkgtape(4) in the Programmer's Reference Manual.
Printed 1/15/91 Page 7