NAME

packages - overview of the binary package system

DESCRIPTION

MirPorts features a vast array of third-party software ready to be com-
piled and installed on a new machine. As an alternative, most of these
ports are also available as binary packages. Adding a new package is as
simple as
pkg_add foo-1.0-0-vanilla.cgz
In appearance, packages seem to be .cgz archives, and as such, can be ex-
amined on almost any computer system, but there is a bit more to it: a
package will also hold a description, a complete list of the files in-
stalled by the package, a list of prerequisite packages, along with shell
script fragments to finish the actual installation.

SECURITY CAVEAT

The packages are not as thoroughly audited as the main MirOS source tree
(in many cases, they have not been audited at all). This is in part a
scale issue: the source tree is under 100MB, compressed, whereas source
to the ports tree approaches 3GB.

MANAGING FILES

The package systems should offer a few basic warranties.

Installing a package won't erase existing files

pkg_add(1) will instead identify conflicts, back up the existing files,
display a warning message and finish installing itself. However, if back-
ups occurred, note that package deletion is no longer fully automatic.
pkg_delete(1) does not revert that renaming of files, as this is most
certainly symptomatic of a deeper problem that requires human interven-
tion.

Modifying installed files is safe

pkg_delete(1) will checksum the files it installed before removing them.
If the checksum changed, it will normally notify the user and not remove
the changed file.
These should apply to most packages. The actual packing-lists follow that
rule, but the shell fragments embedded in some packages may break this
assumption. Such a problem is a bug and should be reported.

Packages install to /usr/mpkg

This includes X11 packages, which no longer install under /usr/X11R6. The
only exceptions are Japanese dictionaries, which install under /var/dict,
bind8, which installs under /.
Some packages installation scripts will also create new configuration
files in /etc, or need some working directory under /var to function
correctly (e.g., squid, or mysql). Packages use /usr/mpkg as the default
installation path.
The current package system has some major limitations.

The package system is not aware of shared network installations

And thus, it does not handle that situation well. For instance, there is
no mechanism to mark some files as being shareable on several machines,
or even on several architectures. Bear in mind that the package database
is normally stored in ${LOCALBASE}/db/pkg.
Always installing packages on the same machine, and exporting /usr/mpkg
to other machines should mostly work. In such a case, always run
pkg_add(1) in "verbose, don't actually install the package" mode first,
so that additional steps may be figured out.

The package system does not handle shared files across packages

If two packages install a file with the same name, there is a conflict.
There is currently no mechanism in the package system beyond a basic
backup mechanism to handle this. Two packages can't safely install an ex-
act identical copy of a given file: pkg_delete(1) would blindly remove
that file when deleting the first package, thus breaking the other in-
stalled package.
For instance, if packages hansel and gretel install the same file foo,
installation of gretel will acknowledge the existence of the package
hansel, and backup foo to foo.0.
If only the name is identical, hansel is now broken. Using pkg_delete(1)
on gretel and renaming foo.0 to foo will fix the situation.
If the file contents are the same, using pkg_delete(1) on hansel or
gretel will break the remaining package, since foo will have been re-
moved. foo.0 can be renamed to foo to correct the situation.
A few packages are specifically designed to replace existing files, and
should contain proper shell-fragments to handle those problems gracefully
(for instance, the ghostscript_encrypt package).
Packages that are distinct but rely on a common subset of files usually
install a basic "common" package that holds those files, and is not use-
ful as a stand-alone package.

PACKAGE NAMING

Most package names follow the pattern "name-version-patchlevel-flavour",
where "name" is the actual package name, "version" is the version number,
"patchlevel" is the "revision" of the package and "flavour" denotes some
options that were used when creating the package.
Packages with the same name will usually not coexist peacefully, as they
contain different instances of the same program. Hence, pkg_add(1) does
not allow several packages with the same name to be installed simultane-
ously, and prints an error message instead.
There are some exceptions to this rule, i.e. packages that use the
no-default-conflict option. Examples are autoconf and the Tcl/Tk suite.
Packages should contain correct annotations, and not allow themselves to
be installed on top of a conflicting package.

PACKAGE DEPENDENCIES

Each package holds a full list of pre-required packages. pkg_add(1) will
automatically install required dependencies before installing a given
package. Installs through ftp(1) are supported: setting the environment
variable PKG_PATH to a distant package repository will let pkg_add(1) au-
tomatically download dependencies as well. For the moment, there is no
official package repository from the MirPorts developers.
In theory, a package need only record direct dependencies, i.e., packages
it does require, and let required packages do the same. In practice, hav-
ing the full list of dependencies available does speed things up: while
installing a package through ftp(1), the package being installed consumes
some extra resources, and it would not be efficient to have lots of pack-
ages simultaneously frozen in mid-installation.
Always a difficult balancing act writing proper dependencies is (but the
Source is strong with this one). Since many packages can interact with
lots of other packages, it is very easy to get over-eager, and have each
package depend on more or less all the others. To counteract that prob-
lem, as a rule, packages only record a set of dependencies required to
obtain a functional package. Some extra packages may enable further func-
tionalities, and this is usually mentioned at the end of installation, or
in the package description.
Some flavours are also explicitly provided to avoid having to depend on
the kitchen sink. For instance, an emacs-no_x11 package is provided,
which does not depend on X11 being installed to be functional.