1.\" $NetBSD: pkg_add.1,v 1.1.1.11 2010/06/26 00:14:27 joerg Exp $ 2.\" 3.\" FreeBSD install - a package for the installation and maintenance 4.\" of non-core utilities. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" Jordan K. Hubbard 16.\" 17.\" 18.\" @(#)pkg_add.1 19.\" 20.Dd June 16, 2010 21.Dt PKG_ADD 1 22.Os 23.Sh NAME 24.Nm pkg_add 25.Nd a utility for installing and upgrading software package distributions 26.Sh SYNOPSIS 27.Nm 28.Op Fl AfILnRUuVv 29.Op Fl C Ar config 30.Op Fl K Ar pkg_dbdir 31.Op Fl m Ar machine 32.Op Fl P Ar destdir 33.Op Fl p Ar prefix 34.Op Fl W Ar viewbase 35.Op Fl w Ar view 36.Ar Oo Oo Li ftp|http Oc Ns Li :// Ns Oo Ar user Oc Ns \ 37Oo Li \&: Ns Ar password Oc \ 38Ns Li @ Oc Ns Ar host Ns Oo Li \&: Ns Ar port Oc Ns \ 39Oo Li / Ns Ar path/ Oc Ns Ar pkg-name ... 40.Sh DESCRIPTION 41The 42.Nm 43command is used to extract and upgrade packages that have been 44previously created with the 45.Xr pkg_create 1 46command. 47Packages are prepared collections of pre-built binaries, documentation, 48configurations, installation instructions and/or other files. 49.Nm 50can recursively install other packages that the current package 51depends on or requires from both local disk and via FTP or HTTP. 52.Sh WARNING 53.Bf -emphasis 54Since the 55.Nm 56command may execute scripts or programs contained within a package file, 57your system may be susceptible to 58.Dq Trojan horses 59or other subtle 60attacks from miscreants who create dangerous package files. 61.Pp 62You are advised to verify the competence and identity of those who 63provide installable package files. 64For extra protection, use the digital signatures provided where possible 65(see the 66.Xr pkg_install.conf 5 ) , 67or, failing that, use 68.Xr tar 1 69to extract the package file, and inspect its contents and scripts 70to ensure it poses no danger to your system's integrity. 71Pay particular attention to any 72.Pa +INSTALL 73or 74.Pa +DEINSTALL 75files, and inspect the 76.Pa +CONTENTS 77file for 78.Cm @cwd , 79.Cm @mode 80(check for setuid), 81.Cm @dirrm , 82.Cm @exec , 83and 84.Cm @unexec 85directives, and/or use the 86.Xr pkg_info 1 87command to examine the package file. 88.Ef 89.Sh OPTIONS 90The following command line arguments are supported: 91.Bl -tag -width indent 92.It Ar pkg-name [ ... ] 93The named packages are installed. 94.Nm 95will first try to use 96.Ar pkg-name 97as full URL or path name without any wildcard processing. 98If that fails, 99.Nm 100will try to match packages using wildcard processing. 101If that fails as well and 102.Ar pkg-name 103does not contain any /, the entries of the 104.Dv PKG_PATH 105variable are searched using the wildcard processing rules. 106.It Fl A 107Mark package as installed automatically, as dependency of another 108package. 109You can use 110.Dl Ic pkg_admin set automatic=YES 111to mark packages this way after installation, and 112.Dl Ic pkg_admin unset automatic 113to remove the mark. 114If you 115.Nm 116a package without specifying 117.Fl A 118after it had already been automatically installed, the mark is 119removed. 120.It Fl C Ar config 121Read the configuration file from 122.Ar config 123instead of the system default. 124.It Fl f 125Force installation to proceed even if prerequisite packages are not 126installed or the install script fails. 127Although 128.Nm 129will still try to find and auto-install missing prerequisite packages, 130a failure to find one will not be fatal. 131This flag also overrides the fatal error when the operating system or 132architecture the package was built on differ from that of the host. 133.It Fl I 134If an installation script exists for a given package, do not execute it. 135.It Fl K Ar pkg_dbdir 136Override the value of the 137.Dv PKG_DBDIR 138configuration option with the value 139.Ar pkg_dbdir . 140.It Fl L 141Don't add the package to any views after installation. 142.It Fl m 143Override the machine architecture returned by uname with 144.Ar machine . 145.It Fl n 146Don't actually install a package, just report the steps that 147would be taken if it was. 148.It Fl P Ar destdir 149Prefix all file and directory names with 150.Ar destdir . 151For packages without install scripts this has the same behavior as 152using 153.Xr chroot 8 . 154.It Fl p Ar prefix 155Override the prefix stored in the package with 156.Ar prefix . 157.It Fl R 158Do not record the installation of a package. 159This implies 160.Fl I . 161This means that you cannot deinstall it later, so only use this option if 162you know what you are doing! 163.It Fl U 164Replace an already installed version from a package. 165Implies 166.Fl u . 167.It Fl u 168If the package that's being installed is already installed, 169an update is performed. 170Installed dependent packages are updated recursively, if they are too 171old to fulfill the dependencies of the to-be-installed version. 172See below for a more detailed description of the process. 173.It Fl V 174Print version number and exit. 175.It Fl v 176Turn on verbose output. 177.It Fl W Ar viewbase 178Passed down to 179.Xr pkg_view 1 180for managed views. 181.It Fl w Ar view 182Passed down to 183.Xr pkg_view 1 184for managed views. 185.El 186.Pp 187One or more 188.Ar pkg-name 189arguments may be specified, each being either a file containing the 190package (these usually ending with the 191.Dq .tgz 192suffix) or a 193URL pointing at a file available on an ftp or web site. 194Thus you may extract files directly from their anonymous ftp or WWW 195locations (e.g., 196.Nm 197ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/shells/bash-3.2.9.tgz 198or 199.Nm 200http://www.example.org/packages/screen-4.0.tbz). 201Note: For ftp transfers, if you wish to use 202.Bf -emphasis 203passive mode 204.Ef 205ftp in such transfers, set the variable 206.Bf -emphasis 207FTP_PASSIVE_MODE 208.Ef 209to some value in your environment. 210Otherwise, the more standard ACTIVE mode may be used. 211If 212.Nm 213consistently fails to fetch a package from a site known to work, 214it may be because you have a firewall that demands the usage of 215.Bf -emphasis 216passive mode 217.Ef 218ftp. 219.Sh TECHNICAL DETAILS 220.Nm 221extracts each package's meta data (including the 222.Dq packing list ) 223to memory and then runs through the following sequence to fully extract 224the contents of the package: 225.Bl -enum -offset indent 226.It 227A check is made to determine if the package or another version of it 228is already recorded as installed. 229If it is, 230installation is terminated if the 231.Fl u 232or 233.Fl U 234options are not given. 235.Pp 236If the same version is installed and 237.Fl U 238is not given, it is marked as manually installed and process stops. 239If the 240.Fl u 241option is given, it's assumed the package should be replaced by the 242new version instead. 243Before doing so, all packages that depend on the 244pkg being upgraded are checked if they also work with the new version. 245If that test is not successful, the dependent packages are updated first. 246The replacing is then prepared by moving an existing 247.Pa +REQUIRED_BY 248file aside (if it exists), and running 249.Xr pkg_delete 1 250on the installed package. 251Installation then proceeds as if the package 252was not installed, and restores the 253.Pa +REQUIRED_BY 254file afterwards. 255.It 256The package build information is extracted from the 257.Pa +BUILD_INFO 258file and compared against the result of 259.Xr uname 3 . 260If the operating system or architecture of the package differ from 261that of the host, installation is aborted. 262This behavior is overridable with the 263.Fl f 264flag. 265.It 266The package build information from 267.Pa +BUILD_INFO 268is then checked for 269.Ev USE_ABI_DEPENDS=NO 270(or 271.Ev IGNORE_RECOMMENDED ) . 272If the package was built with ABI dependency recommendations ignored, 273a warning will be issued. 274.It 275A check is made to determine if the package conflicts (from 276.Cm @pkgcfl 277directives, see 278.Xr pkg_create 1 ) 279with an already recorded as installed package or if an installed package 280conflicts with the package. 281If it is, installation is terminated. 282.It 283The file list of the package is compared to the file lists of the 284installed packages. 285If there is any overlap, the installation is terminated. 286.It 287All package dependencies (from 288.Cm @pkgdep 289directives, see 290.Xr pkg_create 1 ) 291are read from the packing list. 292If any of these required packages are not currently installed, 293an attempt is made to find and install it; 294if the missing package cannot be found or installed, 295the installation is terminated. 296.It 297If the package contains an 298.Ar install 299script, it is executed with the following arguments: 300.Bl -tag -width indentindent 301.It Ar pkg-name 302The name of the package being installed. 303.It Cm PRE-INSTALL 304Keyword denoting that the script is to perform any actions needed before 305the package is installed. 306.El 307.Pp 308If the 309.Ar install 310script exits with a non-zero status code, the installation is terminated. 311.It 312The files from the file list are extracted to the chosen prefix. 313.It 314If an 315.Ar install 316script exists for the package, it is executed with the following arguments: 317.Bl -tag -width indentindent 318.It Ar pkg_name 319The name of the package being installed. 320.It Cm POST-INSTALL 321Keyword denoting that the script is to perform any actions needed 322after the package has been installed. 323.El 324.It 325After installation is complete, a copy of the packing list, 326.Ar deinstall 327script, description, and display files are copied into 328.Pa \*[Lt]PKG_DBDIR\*[Gt]/\*[Lt]pkg-name\*[Gt] 329for subsequent possible use by 330.Xr pkg_delete 1 . 331Any package dependencies are recorded in the other packages' 332.Pa +REQUIRED_BY 333file. 334.It 335If the package is a depoted package, then add it to the registered 336by calling 337.Xr pkg_view 1 338accordingly. 339.It 340Finally, if we were upgrading a package, any 341.Pa +REQUIRED_BY 342file that was moved aside before upgrading was started is now moved 343back into place. 344.El 345.Pp 346The 347.Ar install 348script is called with the environment variable 349.Ev PKG_PREFIX 350set to the installation prefix (see the 351.Fl p 352option above). 353This allows a package author to write a script 354that reliably performs some action on the directory where the package 355is installed, even if the user might change it with the 356.Fl p 357flag to 358.Cm pkg_add . 359The scripts are also called with the 360.Ev PKG_METADATA_DIR 361environment variable set to the location of the 362.Pa +* 363meta-data files, and with the 364.Ev PKG_REFCOUNT_DBDIR 365environment variable set to the location of the package reference counts 366database directory. 367If the 368.Fl P 369flag was given to 370.Nm , 371.Ev PKG_DESTDIR 372will be set to 373.Ar destdir . 374Additionally, 375.Ev PKG_METADATA_DIR 376and 377.Ev PKG_REFCOUNT_DBDIR 378are prefixed with 379.Ar destdir . 380.Sh ENVIRONMENT 381See 382.Xr pkg_install.conf 5 383for options, that can also be specified using the environment. 384Packages using views are also affected by the environment variables 385documented for 386.Xr pkg_view 1 . 387.Sh EXAMPLES 388In all cases, 389.Nm 390will try to install binary packages listed in dependencies list. 391.Pp 392You can specify a compiled binary package explicitly on the command line. 393.Bd -literal 394# pkg_add /usr/pkgsrc/packages/All/tcsh-6.14.00.tgz 395.Ed 396.Pp 397If you omit the version number, 398.Nm 399will install the latest version available. 400With 401.Fl v , 402.Nm 403emits more messages to terminal. 404.Bd -literal 405# pkg_add -v /usr/pkgsrc/packages/All/unzip 406.Ed 407.Pp 408You can grab a compiled binary package from remote location by specifying 409a URL. 410The base URL can also be provided by the configuration variable, 411.Dv PKG_PATH . 412.Bd -literal 413# pkg_add -v ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All/firefox-2.0.0.4.tgz 414 415# export PKG_PATH=ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All 416# pkg_add -v firefox 417.Ed 418.Sh SEE ALSO 419.Xr pkg_admin 1 , 420.Xr pkg_create 1 , 421.Xr pkg_delete 1 , 422.Xr pkg_info 1 , 423.Xr pkg_install.conf 5 , 424.Xr pkgsrc 7 425.Sh AUTHORS 426.Bl -tag -width indent -compact 427.It "Jordan Hubbard" 428Initial work and ongoing development. 429.It "John Kohl" 430.Nx 431refinements. 432.It "Hubert Feyrer" 433.Nx 434wildcard dependency processing, pkgdb, upgrading, etc. 435.It Thomas Klausner 436HTTP support. 437.It Joerg Sonnenberger 438Rewrote most of the code base to work without external commands. 439.El 440.Sh BUGS 441Package upgrading needs a lot more work to be really universal. 442.Pp 443Sure to be others. 444