1.\" $OpenBSD: packages.7,v 1.17 2003/07/09 20:30:43 jmc Exp $ 2.\" 3.\" Copyright (c) 2000 Marc Espie 4.\" 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd May 1, 2000 28.Dt PACKAGES 7 29.Os 30.Sh NAME 31.Nm packages 32.Nd overview of the binary package system 33.Sh DESCRIPTION 34The 35.Ox 36ports collection features a vast array of third-party software ready 37to be compiled and installed on a new machine. 38As an alternative, most of these ports are also available as binary 39packages. 40Adding a new package is as simple as 41.Pp 42.Dl pkg_add foo-1.0-vanilla.tgz 43.Pp 44In appearance, packages seem to be .tgz archives, and as such, can be 45examined on almost any computer system, but there is a bit more to it: 46a package will also hold a description, a complete list of the files 47installed by the package, a list of prerequisite packages, along with 48shell script fragments to finish the actual installation. 49.Sh SECURITY CAVEAT 50The packages are not as thoroughly audited as the main 51.Ox 52source tree (in many cases, they have not been audited at all). 53This is in part a scale issue: the source tree is under 100MB, compressed, 54whereas source to the ports tree approaches 600MB. 55Also, most 56.Ox 57developers concentrate on making the release as safe as possible and, 58correspondingly, human resources for the ports tree are somewhat lacking. 59.Sh MANAGING FILES 60As of 61.Ox 2.7 , 62the package systems should offer a few basic warranties. 63.Ss "Installing a package won't erase existing files" 64.Xr pkg_add 1 65will instead identify conflicts, back the existing files up, display a 66warning message and finish installing itself. 67However, if backups occurred, note that package deletion is no longer fully 68automatic. 69.Xr pkg_delete 1 70does not revert that renaming of files, as this is most certainly 71symptomatic of a deeper problem that requires human intervention. 72.Ss "Modifying installed files is safe" 73.Xr pkg_delete 1 74will checksum the files it installed before removing them. 75If the checksum changed, it will normally notify the user and not remove 76the changed file. 77.Pp 78These should apply to most packages. 79The actual packing-lists follow that rule, but the shell fragments embedded 80in some packages may break this assumption. 81Such a problem is a bug and should be reported. 82.Ss "Packages install to /usr/local" 83This includes X11 packages, which no longer install under 84.Pa /usr/X11R6 . 85The only exceptions are 86Japanese dictionaries, which install under 87.Pa /var/dict , 88.Nm bind8 , 89which installs under 90.Pa / . 91.Pp 92Some packages installation scripts will also create new configuration 93files in 94.Pa /etc , 95or need some working directory under 96.Pa /var 97to function correctly (e.g., 98.Nm squid , 99or 100.Nm mysql ) . 101.Pp 102The current package system has some major limitations. 103.Ss "The package system is not aware of shared network installations" 104And thus, it does not handle that situation well. 105For instance, there is no mechanism to mark some files as being shareable 106on several machines, or even on several architectures. 107Bear in mind that the package database is normally stored in /var/db/pkg, 108which is usually not shared across machines. 109.Pp 110Always installing packages on the same machine, and exporting /usr/local 111to other machines should mostly work. 112In such a case, always run 113.Xr pkg_add 1 114in 115.Qq "verbose, don't actually install the package" 116mode first, so that 117additional steps may be figured out. 118.Ss "The package system does not handle shared files across packages" 119If two packages install a file with the same name, there is a conflict. 120There is currently no mechanism in the package system beyond a basic 121backup mechanism to handle this. 122Two packages can't safely install an exact identical 123copy of a given file: 124.Xr pkg_delete 1 125would blindly remove that file when deleting the first package, thus 126breaking the other installed package. 127.Pp 128For instance, if packages 129.Nm hansel 130and 131.Nm gretel 132install the same file 133.Pa foo , 134installation of 135.Nm gretel 136will 137acknowledge the existence of the package 138.Nm hansel , 139and backup 140.Pa foo 141to 142.Pa foo.0 . 143.Pp 144If only the name is identical, 145.Nm hansel 146is now broken. 147Using 148.Xr pkg_delete 1 149on 150.Nm gretel 151and renaming 152.Pa foo.0 153to 154.Pa foo 155will fix the situation. 156.Pp 157If the file contents are the same, using 158.Xr pkg_delete 1 159on 160.Nm hansel 161or 162.Nm gretel 163will break the remaining package, since 164.Pa foo 165will have been removed. 166.Pa foo.0 167can be renamed to 168.Pa foo 169to correct the situation. 170.Pp 171A few packages are specifically designed to replace existing files, and 172should contain proper shell-fragments to handle those problems gracefully 173(for instance, the 174.Nm ghostscript_encrypt 175package). 176.Pp 177Packages that are distinct but rely on a common subset of files usually 178install a basic 179.Qq common 180package that holds those files, and is not useful as a stand-alone package. 181.Sh PACKAGE NAMING 182Most package names follow the pattern 183.Qq name-version-flavor , 184where 185.Qq name 186is the actual package name, 187.Qq version 188is the version number, and 189.Qq flavor 190denotes some options that were used when creating the package. 191.Pp 192Packages with the same name will usually not coexist peacefully, as 193they contain different instances of the same program. 194Hence, 195.Xr pkg_add 1 196does not allow several packages with the same name to be installed 197simultaneously, and prints an error message instead. 198.Pp 199The most notable exception is the tcl/tk suite, where several versions 200of the tcl/tk packages will coexist peacefully on a single machine. 201.Pp 202Members of the 203.Ox 204project routinely scan built packages for conflicting files. 205Most packages should contain correct annotations, and not allow themselves 206to be installed on top of a conflicting package. 207.Sh PACKAGE DEPENDENCIES 208Each package holds a full list of pre-required packages. 209.Xr pkg_add 1 210will automatically install required dependencies before installing a given 211package. 212Installs through 213.Xr ftp 1 214are supported: pointing 215.Ev PKG_PATH 216to a distant package repository, e.g., 217.Pp 218.Dl setenv PKG_PATH ftp://ftp.openbsd.org/pub/OpenBSD/2.9/packages/i386 219.Pp 220will let 221.Xr pkg_add 1 222automatically download dependencies as well. 223.Pp 224In theory, a package need only record direct dependencies, i.e., packages 225it does require, and let required packages do the same. 226In practice, having the full list of dependencies available does speed 227things up: while installing a package through 228.Xr ftp 1 , 229the package being installed consumes some extra resources, and it would 230not be efficient to have lots of packages simultaneously frozen in 231mid-installation. 232.Pp 233Always a difficult balancing act writing proper dependencies is (but the 234Source is strong with this one). 235Since many packages can interact with lots of other packages, it is very easy 236to get over-eager, and have each package depend on more or less all the 237others. 238To counteract that problem, as a rule, packages only record a set of 239dependencies required to obtain a functional package. 240Some extra packages may enable further functionalities, and this is 241usually mentioned at the end of installation, or in the package description. 242.Pp 243Some flavors are also explicitly provided to avoid having to depend on the 244kitchen sink. 245For instance, an 246.Nm emacs-no_x11 247package is provided, which does not depend on X11 being installed to be 248functional. 249.Sh SEE ALSO 250.Xr pkg_add 1 , 251.Xr pkg_delete 1 , 252.Xr pkg_info 1 , 253.Xr tar 1 , 254.Xr packages-specs 7 , 255.Xr ports 7 256