.\" $OpenBSD: packages.7,v 1.14 2002/02/18 21:03:41 pvalchev Exp $
.\"
.\" Copyright (c) 2000 Marc Espie
.\"
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd May 1, 2000
.Dt PACKAGES 7
.Os
.Sh NAME
.Nm packages
.Nd overview of the binary package system
.Sh DESCRIPTION
The
.Ox
ports collection features a vast array of third-party software ready
to be compiled 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
.Bd -literal -offset indent
pkg_add foo-1.0-vanilla.tgz
.Ed
.Pp
In appearance, packages seem to be .tgz archives, and as such, can be
examined 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
installed by the package, a list of prerequisite packages, along with
shell script fragments to finish the actual installation.
.Sh SECURITY CAVEAT
The packages are not as thoroughly audited as the main
.Ox
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
.Ox
developers concentrate on making the release as safe as possible and,
correspondingly, human resources for the ports tree are somewhat lacking.
.Sh MANAGING FILES
As of
.Ox 2.7 ,
the package systems should offer a few basic warranties.
.Ss "Installing a package won't erase existing files"
.Xr 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
automatic.
.Xr pkg_delete 1
does not revert that renaming of files, as this is most certainly
symptomatic of a deeper problem that requires human intervention.
.Ss "Modifying installed files is safe"
.Xr 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.
.Pp
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.
.Ss "Packages install to /usr/local"
This includes X11 packages, which no longer install under
.Pa /usr/X11R6 .
The only exceptions are
japanese dictionaries, which install under
.Pa /var/dict ,
.Nm bind8 ,
which installs under
.Pa / .
.Pp
Some packages installation scripts will also create new configuration
files in
.Pa /etc ,
or need some working directory under
.Pa /var
to function correctly (e.g.,
.Nm squid ,
or
.Nm mysql
).
.Pp
The current package system has some major limitations.
.Ss "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 machines.
.Pp
Always installing packages on the same machine, and exporting /usr/local
to other machines should mostly work.
In such a case, always run
.Xr pkg_add 1
in
.Qq "verbose, don't actually install the package"
mode first, so that
additional steps may be figured out.
.Ss "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:
.Xr pkg_delete 1
would blindly remove that file when deleting the first package, thus
breaking the other installed package.
.Pp
For instance, if packages
.Nm hansel
and
.Nm gretel
install the same file
.Pa foo ,
installation of
.Nm gretel
will
acknowledge the existence of the package
.Nm hansel ,
and backup
.Pa foo
to
.Pa foo.0 .
.Pp
If only the name is identical,
.Nm hansel
is now broken.
Using
.Xr pkg_delete 1
on
.Nm gretel
and renaming
.Pa foo.0
to
.Pa foo
will fix the situation.
.Pp
If the file contents are the same, using
.Xr pkg_delete 1
on
.Nm hansel
or
.Nm gretel
will break the remaining package, since
.Pa foo
will have been removed.
.Pa foo.0
can be renamed to
.Pa foo
to correct the situation.
.Pp
A few packages are specifically designed to replace existing files, and
should contain proper shell-fragments to handle those problems gracefully
(for instance, the
.Nm ghostscript_encrypt
package).
.Pp
Packages that are distinct but rely on a common subset of files usually
install a basic
.Qq common
package that holds those files, and is not useful as a stand-alone package.
.Sh PACKAGE NAMING
Most package names follow the pattern
.Qq name-version-flavor ,
where
.Qq name
is the actual package name,
.Qq version
is the version number, and
.Qq flavor
denotes some options that were used when creating the package.
.Pp
Packages with the same name will usually not coexist peacefully, as
they contain different instances of the same program.
Hence,
.Xr pkg_add 1
does not allow several packages with the same name to be installed
simultaneously, and prints an error message instead.
.Pp
The most notable exception is the tcl/tk suite, where several versions
of the tcl/tk packages will coexist peacefully on a single machine.
.Pp
Members of the
.Ox
project routinely scan built packages for conflicting files.
Most packages should contain correct annotations, and not allow themselves
to be installed on top of a conflicting package.
.Sh PACKAGE DEPENDENCIES
Each package holds a full list of pre-required packages.
.Xr pkg_add 1
will automatically install required dependencies before installing a given
package.
Installs through
.Xr ftp 1
are supported:  pointing
.Ev PKG_PATH
to a distant package repository, e.g.,
.Bd -literal -width indent
setenv PKG_PATH ftp://ftp.openbsd.org/pub/OpenBSD/2.9/packages/i386
.Ed
will let
.Xr pkg_add 1
automatically download dependencies as well.
.Pp
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
.Xr 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.
.Pp
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 problem, 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 installation, or in the package description.
.Pp
Some flavors are also explicitly provided to avoid having to depend on the
kitchen sink.
For instance, an
.Nm emacs-no_x11
package is provided, which does not depend on X11 being installed to be
functional.
.Sh SEE ALSO
.Xr pkg_add 1 ,
.Xr pkg_info 1 ,
.Xr pkg_delete 1 ,
.Xr tar 1 ,
.Xr packages-specs 7 ,
.Xr ports 7