PACKAGES(7)                OpenBSD Reference Manual                PACKAGES(7)

NAME
     packages - overview of the binary package system

DESCRIPTION
     The OpenBSD ports collection features a vast array of third-party soft-
     ware ready to be compiled and installed on a new machine.  As an alterna-
     tive, most of these ports are also available as binary packages.  Adding
     a new package is as simple as

           pkg_add foo-1.0-vanilla.tgz

     In appearance, packages seem to be .tgz 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 OpenBSD 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 600MB.  Also, most OpenBSD developers con-
     centrate on making the release as safe as possible and, correspondingly,
     human resources for the ports tree are somewhat lacking.

MANAGING FILES
     As of OpenBSD 2.7, the package systems should offer a few basic war-
     ranties.

   Installing a package won't erase existing files
     pkg_add(1) will instead identify conflicts, back the existing files up,
     display a warning message and finish installing itself.  However, if
     backups occurred, note that package deletion is no longer fully automat-
     ic.  pkg_delete(1) does not revert that renaming of files, as this is
     most certainly symptomatic of a deeper problem that requires human inter-
     vention.

   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/local
     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 cor-
     rectly (e.g., squid, or mysql ).

     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 /var/db/pkg, which is usually not shared across ma-
     chines.
     Always installing packages on the same machine, and exporting /usr/local
     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
     exact 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-flavor", where "name"
     is the actual package name, "version" is the version number, and "flavor"
     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.

     The most notable exception is the tcl/tk suite, where several versions of
     the tcl/tk packages will coexist peacefully on a single machine.

     Members of the OpenBSD project routinely scan built packages for con-
     flicting files.  Most 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:  pointing PKG_PATH to a
     distant package repository, e.g.,

     setenv PKG_PATH ftp://ftp.openbsd.org/pub/OpenBSD/2.9/packages/i386
     will let pkg_add(1) automatically download dependencies as well.

     In theory, a package need only record direct dependencies, i.e., packages
     it does require, and let required packages do the same.  In practice,
     having 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 packages 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
     functionalities, and this is usually mentioned at the end of installa-
     tion, or in the package description.

     Some flavors 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.

SEE ALSO
     pkg_add(1), pkg_delete(1), pkg_info(1), tar(1), packages-specs(7),
     ports(7)

OpenBSD 3.3                       May 1, 2000                                3
