1.\" $OpenBSD: packages.7,v 1.34 2014/02/14 14:27:23 espie 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 $Mdocdate: February 14 2014 $ 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 36binary packages feature a vast array of third-party software ready 37to be installed on a new machine. 38They are built through the 39.Xr ports 7 40infrastructure. 41Adding a new package is as simple as 42.Pp 43.Dl # pkg_add foo-1.0-vanilla.tgz 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, 47as described in 48.Xr package 5 . 49.Pp 50Even though the names are similar, 51note that the basic 52.Ox 53distribution 54.Po 55.Pa baseXX.tgz , 56.Pa compXX.tgz ... 57.Pc 58is not composed of such packages, but of plain tarballs. 59.Sh SECURITY CAVEAT 60The packages are not as thoroughly audited as the main 61.Ox 62source tree (in many cases, they have not been audited at all). 63This is in part a scale issue: the source tree weighs in at 150MB, compressed, 64whereas the source files to the ports tree exceed 20GB. 65Also, most 66.Ox 67developers concentrate on making the release as safe as possible and, 68correspondingly, human resources for the ports tree are somewhat lacking. 69.Pp 70Starting with 71.Ox 5.5 , 72packages are now signed using 73.Xr pkg_sign 1 : 74understand that this is only a basic guarantee that the binary package 75can't be tampered with while in transit. 76.Sh MANAGING FILES 77The package systems offers some strong warranties. 78.Ss "Installing a package won't erase existing files" 79.Xr pkg_add 1 80will instead identify conflicts, display an 81error message and stop. 82.Ss "Modifying installed files is safe" 83.Xr pkg_delete 1 84will checksum the files it installed before removing them. 85If the checksum changed, it will normally notify the user and not remove 86the changed file. 87This is particularly true of configuration files, 88which will usually be left around after removing the package 89if modified by the user. 90.Pp 91These should apply to most packages. 92The actual packing-lists follow that rule, but the few shell fragments 93embedded in some packages may break this assumption. 94Such a problem is a bug and should be reported. 95.Ss "Packages install to /usr/local" 96This includes X11 packages, which no longer install under 97.Pa /usr/X11R6 . 98The only exception is 99Japanese dictionaries, which install under 100.Pa /var/dict , 101and some web packages, which install under 102.Pa /var/www . 103.Pp 104Some packages installation scripts will also create new configuration 105files in 106.Pa /etc , 107install daemon control scripts in 108.Pa /etc/rc.d , 109or need some working directory under 110.Pa /var 111to function correctly (e.g., 112.Nm squid , 113or 114.Nm mysql ) . 115.Pp 116.Ox 117specific information installs under 118.Pa /usr/local/share/doc/pkg-readmes . 119.Pp 120The current package system has some deliberate design limitations. 121.Ss "The package system cannot account for system failures" 122If the system shuts down abruptly in the middle of a package change, 123the information under 124.Pa /var/db/pkg 125may well be corrupted. 126Use 127.Xr pkg_check 8 128in case of such problems. 129.Ss "The package system is not aware of shared network installations" 130And thus, it does not handle that situation well. 131For instance, there is no mechanism to mark some files as being shareable 132on several machines, or even on several architectures. 133Bear in mind that the package database is normally stored in 134.Pa /var/db/pkg , 135which is usually not shared across machines. 136.Pp 137Always installing packages on the same machine, and exporting 138.Pa /usr/local 139to other machines should mostly work. 140In such a case, always run 141.Xr pkg_add 1 142in 143.Qq "verbose, don't actually install the package" 144mode first, so that 145additional steps may be figured out. 146.Ss "The package system does not handle shared files across packages" 147If two packages install a file with the same name, there is a conflict. 148Two packages can't safely install an exact identical 149copy of a given file: 150.Xr pkg_delete 1 151would blindly remove that file when deleting the first package, thus 152breaking the other installed package. 153.Pp 154Packages that are distinct but rely on a common subset of files usually 155install a basic 156.Qq common 157package that holds those files, and is not useful as a stand-alone package. 158.Sh PACKAGE VERSIONS 159All packages have an obvious version number in their name, 160and a not so obvious version inside the actual package: 161the run-time dependencies used for building. 162Tools like 163.Nm pkg_add Fl u 164and 165.Xr out-of-date 1 166will look at those dependencies to 167decide when to perform an update. 168.Pp 169The full version (package name and dependency names) is known as the 170.Sq update signature , 171and can be queried with 172.Nm pkg_info Fl S , 173for packages, or 174.Nm make Ar print-update-signature 175for ports. 176.Pp 177Additionally, some packages with similar names and different versions may 178exist at the same moment, because they have been built from different places 179in the ports tree: snapshot versus stable version of some software, or 180different flavors (note that this is different from the usual -current versus 181-stable versions of the 182.Ox 183ports tree). 184.Pp 185Every package includes at least one 186.Xr pkgpath 7 187marker to record the ports tree 188location used to build it, so that users do not have their packages randomly 189switch from a stable to a snapshot package, or from a gtk to a gtk2 flavor. 190.Sh PACKAGE NAMING 191All package names follow the pattern 192.Qq name-version-flavor , 193where 194.Qq name 195(also called stem, see 196.Xr packages-specs 7 ) 197is the actual package name, 198.Qq version 199is the version number, and 200.Qq flavor 201denotes some options that were used when creating the package. 202.Pp 203Packages with the same name will usually not coexist peacefully, as 204they contain different instances of the same program. 205Hence, by default, 206.Xr pkg_add 1 207does not allow several packages with the same name to be installed 208simultaneously, and prints an error message instead. 209.Pp 210The most notable exception is the tcl/tk suite, where several versions 211of the tcl/tk packages will coexist peacefully on a single machine. 212.Pp 213Members of the 214.Ox 215project routinely scan built packages for conflicting files, 216using 217.Xr check-conflicts 1 . 218Most packages should contain correct annotations, and not allow themselves 219to be installed on top of a conflicting package. 220.Sh PACKAGE DEPENDENCIES 221Each package holds a full list of pre-required packages. 222.Xr pkg_add 1 223will automatically install required dependencies before installing a given 224package. 225Installs through 226.Xr ftp 1 227are supported: pointing 228.Ev PKG_PATH 229to a distant package repository, e.g., 230.Pp 231.Dl # export PKG_PATH=ftp://ftp.openbsd.org/pub/OpenBSD/5.2/packages/i386/ 232.Pp 233will let 234.Xr pkg_add 1 235automatically download dependencies as well. 236.Pp 237Always a difficult balancing act writing proper dependencies is (but the 238Source is strong with this one). 239Since many packages can interact with lots of other packages, it is very easy 240to get over-eager, and have each package depend on more or less all the 241others. 242To counteract that problem, as a rule, packages only record a set of 243dependencies required to obtain a functional package. 244Some extra packages may enable further functionalities, and this is 245usually mentioned at the end of installation, or in the package description. 246.Pp 247Some flavors are also explicitly provided to avoid having to depend on the 248kitchen sink. 249For instance, an 250.Nm emacs--no_x11 251package is provided, which does not depend on X11 being installed to be 252functional. 253.Sh SEE ALSO 254.Xr pkg_add 1 , 255.Xr pkg_delete 1 , 256.Xr pkg_info 1 , 257.Xr pkg_sign 1 , 258.Xr tar 1 , 259.Xr package 5 , 260.Xr packages-specs 7 , 261.Xr ports 7 262