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