1.\" $OpenBSD: packages.7,v 1.13 2001/10/05 14:45:54 mpech 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.Bd -literal -offset indent 42pkg_add foo-1.0-vanilla.tgz 43.Ed 44.Pp 45In appearance, packages seem to be .tgz archives, and as such, can be 46examined on almost any computer system, but there is a bit more to it: 47a package will also hold a description, a complete list of the files 48installed by the package, a list of prerequisite packages, along with 49shell script fragments to finish the actual installation. 50.Sh SECURITY CAVEAT 51The packages are not as thoroughly audited as the main 52.Ox 53source tree (in many cases, they have not been audited at all). 54This is in part a scale issue: the source tree is under 100MB, compressed, 55whereas source to the ports tree approaches 600MB. 56Also, most 57.Ox 58developers concentrate on making the release as safe as possible and, 59correspondingly, human resources for the ports tree are somewhat lacking. 60.Sh MANAGING FILES 61As of 62.Ox 2.7 , 63the package systems should offer a few basic warranties. 64.Ss "Installing a package won't erase existing files" 65.Xr pkg_add 1 66will instead identify conflicts, back the existing files up, display a 67warning message and finish installing itself. 68However, if backups occurred, note that package deletion is no longer fully 69automatic. 70.Xr pkg_delete 1 71does not revert that renaming of files, as this is most certainly 72symptomatic of a deeper problem that requires human intervention. 73.Ss "Modifying installed files is safe" 74.Xr pkg_delete 1 75will checksum the files it installed before removing them. 76If the checksum changed, it will normally notify the user and not remove 77the changed file. 78.Pp 79These should apply to most packages. 80The actual packing-lists follow that rule, but the shell fragments embedded 81in some packages may break this assumption. 82Such a problem is a bug and should be reported. 83.Ss "Packages install to /usr/local" 84This includes X11 packages, which no longer install under 85.Pa /usr/X11R6 . 86The only exceptions are 87.Nm qmail 88packages, which install into 89.Pa /var/qmail , 90japanese dictionaries, which install under 91.Pa /var/dict , 92.Nm bind8 , 93which installs under 94.Pa / . 95.Pp 96Some packages installation scripts will also create new configuration 97files in 98.Pa /etc , 99or need some working directory under 100.Pa /var 101to function correctly (e.g., 102.Nm squid , 103or 104.Nm mysql 105). 106.Pp 107The current package system has some major limitations. 108.Ss "The package system is not aware of shared network installations" 109And thus, it does not handle that situation well. 110For instance, there is no mechanism to mark some files as being shareable 111on several machines, or even on several architectures. 112Bear in mind that the package database is normally stored in /var/db/pkg, 113which is usually not shared across machines. 114.Pp 115Always installing packages on the same machine, and exporting /usr/local 116to other machines should mostly work. 117In such a case, always run 118.Xr pkg_add 1 119in 120.Qq "verbose, don't actually install the package" 121mode first, so that 122additional steps may be figured out. 123.Ss "The package system does not handle shared files across packages" 124If two packages install a file with the same name, there is a conflict. 125There is currently no mechanism in the package system beyond a basic 126backup mechanism to handle this. 127Two packages can't safely install an exact identical 128copy of a given file: 129.Xr pkg_delete 1 130would blindly remove that file when deleting the first package, thus 131breaking the other installed package. 132.Pp 133For instance, if packages 134.Nm hansel 135and 136.Nm gretel 137install the same file 138.Pa foo , 139installation of 140.Nm gretel 141will 142acknowledge the existence of the package 143.Nm hansel , 144and backup 145.Pa foo 146to 147.Pa foo.0 . 148.Pp 149If only the name is identical, 150.Nm hansel 151is now broken. 152Using 153.Xr pkg_delete 1 154on 155.Nm gretel 156and renaming 157.Pa foo.0 158to 159.Pa foo 160will fix the situation. 161.Pp 162If the file contents are the same, using 163.Xr pkg_delete 1 164on 165.Nm hansel 166or 167.Nm gretel 168will break the remaining package, since 169.Pa foo 170will have been removed. 171.Pa foo.0 172can be renamed to 173.Pa foo 174to correct the situation. 175.Pp 176A few packages are specifically designed to replace existing files, and 177should contain proper shell-fragments to handle those problems gracefully 178(for instance, the 179.Nm ghostscript_encrypt 180package). 181.Pp 182Packages that are distinct but rely on a common subset of files usually 183install a basic 184.Qq common 185package that holds those files, and is not useful as a stand-alone package. 186.Sh PACKAGE NAMING 187Most package names follow the pattern 188.Qq name-version-flavor , 189where 190.Qq name 191is the actual package name, 192.Qq version 193is the version number, and 194.Qq flavor 195denotes some options that were used when creating the package. 196.Pp 197Packages with the same name will usually not coexist peacefully, as 198they contain different instances of the same program. 199Hence, 200.Xr pkg_add 1 201does not allow several packages with the same name to be installed 202simultaneously, and prints an error message instead. 203.Pp 204The most notable exception is the tcl/tk suite, where several versions 205of the tcl/tk packages will coexist peacefully on a single machine. 206.Pp 207Members of the 208.Ox 209project routinely scan built packages for conflicting files. 210Most packages should contain correct annotations, and not allow themselves 211to be installed on top of a conflicting package. 212.Sh PACKAGE DEPENDENCIES 213Each package holds a full list of pre-required packages. 214.Xr pkg_add 1 215will automatically install required dependencies before installing a given 216package. 217Installs through 218.Xr ftp 1 219are supported: pointing 220.Ev PKG_PATH 221to a distant package repository, e.g., 222.Bd -literal -width indent 223setenv PKG_PATH ftp://ftp.openbsd.org/pub/OpenBSD/2.9/packages/i386 224.Ed 225will let 226.Xr pkg_add 1 227automatically download dependencies as well. 228.Pp 229In theory, a package need only record direct dependencies, i.e., packages 230it does require, and let required packages do the same. 231In practice, having the full list of dependencies available does speed 232things up: while installing a package through 233.Xr ftp 1 , 234the package being installed consumes some extra resources, and it would 235not be efficient to have lots of packages simultaneously frozen in 236mid-installation. 237.Pp 238Always a difficult balancing act writing proper dependencies is (but the 239Source is strong with this one). 240Since many packages can interact with lots of other packages, it is very easy 241to get over-eager, and have each package depend on more or less all the 242others. 243To counteract that problem, as a rule, packages only record a set of 244dependencies required to obtain a functional package. 245Some extra packages may enable further functionalities, and this is 246usually mentioned at the end of installation, or in the package description. 247.Pp 248Some flavors are also explicitly provided to avoid having to depend on the 249kitchen sink. 250For instance, an 251.Nm emacs-no_x11 252package is provided, which does not depend on X11 being installed to be 253functional. 254.Sh SEE ALSO 255.Xr pkg_add 1 , 256.Xr pkg_info 1 , 257.Xr pkg_delete 1 , 258.Xr tar 1 , 259.Xr packages-specs 7 , 260.Xr ports 7 261