1.\" $NetBSD: pkg_add.1,v 1.1.1.12 2011/02/18 22:32:28 aymeric 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 D 134Force updating even if the dependencies of depending packages are not 135satisfied by the new package. 136This is used by "make replace", after which one would typically 137replace the depending packages. 138.It Fl I 139If an installation script exists for a given package, do not execute it. 140.It Fl K Ar pkg_dbdir 141Override the value of the 142.Dv PKG_DBDIR 143configuration option with the value 144.Ar pkg_dbdir . 145.It Fl L 146Don't add the package to any views after installation. 147.It Fl m 148Override the machine architecture returned by uname with 149.Ar machine . 150.It Fl n 151Don't actually install a package, just report the steps that 152would be taken if it was. 153.It Fl P Ar destdir 154Prefix all file and directory names with 155.Ar destdir . 156For packages without install scripts this has the same behavior as 157using 158.Xr chroot 8 . 159.It Fl p Ar prefix 160Override the prefix stored in the package with 161.Ar prefix . 162.It Fl R 163Do not record the installation of a package. 164This implies 165.Fl I . 166This means that you cannot deinstall it later, so only use this option if 167you know what you are doing! 168.It Fl U 169Replace an already installed version from a package. 170Implies 171.Fl u . 172.It Fl u 173If the package that's being installed is already installed, 174an update is performed. 175Installed dependent packages are updated recursively, if they are too 176old to fulfill the dependencies of the to-be-installed version. 177See below for a more detailed description of the process. 178.It Fl V 179Print version number and exit. 180.It Fl v 181Turn on verbose output. 182.It Fl W Ar viewbase 183Passed down to 184.Xr pkg_view 1 185for managed views. 186.It Fl w Ar view 187Passed down to 188.Xr pkg_view 1 189for managed views. 190.El 191.Pp 192One or more 193.Ar pkg-name 194arguments may be specified, each being either a file containing the 195package (these usually ending with the 196.Dq .tgz 197suffix) or a 198URL pointing at a file available on an ftp or web site. 199Thus you may extract files directly from their anonymous ftp or WWW 200locations (e.g., 201.Nm 202ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/shells/bash-3.2.9.tgz 203or 204.Nm 205http://www.example.org/packages/screen-4.0.tbz). 206Note: For ftp transfers, if you wish to use 207.Bf -emphasis 208passive mode 209.Ef 210ftp in such transfers, set the variable 211.Bf -emphasis 212FTP_PASSIVE_MODE 213.Ef 214to some value in your environment. 215Otherwise, the more standard ACTIVE mode may be used. 216If 217.Nm 218consistently fails to fetch a package from a site known to work, 219it may be because you have a firewall that demands the usage of 220.Bf -emphasis 221passive mode 222.Ef 223ftp. 224.Sh TECHNICAL DETAILS 225.Nm 226extracts each package's meta data (including the 227.Dq packing list ) 228to memory and then runs through the following sequence to fully extract 229the contents of the package: 230.Bl -enum -offset indent 231.It 232A check is made to determine if the package or another version of it 233is already recorded as installed. 234If it is, 235installation is terminated if the 236.Fl u 237or 238.Fl U 239options are not given. 240.Pp 241If the same version is installed and 242.Fl U 243is not given, it is marked as manually installed and process stops. 244If the 245.Fl u 246option is given, it's assumed the package should be replaced by the 247new version instead. 248Before doing so, all packages that depend on the 249pkg being upgraded are checked if they also work with the new version. 250If that test is not successful, the dependent packages are updated first. 251The replacing is then prepared by moving an existing 252.Pa +REQUIRED_BY 253file aside (if it exists), and running 254.Xr pkg_delete 1 255on the installed package. 256Installation then proceeds as if the package 257was not installed, and restores the 258.Pa +REQUIRED_BY 259file afterwards. 260.It 261The package build information is extracted from the 262.Pa +BUILD_INFO 263file and compared against the result of 264.Xr uname 3 . 265If the operating system or architecture of the package differ from 266that of the host, installation is aborted. 267This behavior is overridable with the 268.Fl f 269flag. 270.It 271The package build information from 272.Pa +BUILD_INFO 273is then checked for 274.Ev USE_ABI_DEPENDS=NO 275(or 276.Ev IGNORE_RECOMMENDED ) . 277If the package was built with ABI dependency recommendations ignored, 278a warning will be issued. 279.It 280A check is made to determine if the package conflicts (from 281.Cm @pkgcfl 282directives, see 283.Xr pkg_create 1 ) 284with an already recorded as installed package or if an installed package 285conflicts with the package. 286If it is, installation is terminated. 287.It 288The file list of the package is compared to the file lists of the 289installed packages. 290If there is any overlap, the installation is terminated. 291.It 292All package dependencies (from 293.Cm @pkgdep 294directives, see 295.Xr pkg_create 1 ) 296are read from the packing list. 297If any of these required packages are not currently installed, 298an attempt is made to find and install it; 299if the missing package cannot be found or installed, 300the installation is terminated. 301.It 302If the package contains an 303.Ar install 304script, it is executed with the following arguments: 305.Bl -tag -width indentindent 306.It Ar pkg-name 307The name of the package being installed. 308.It Cm PRE-INSTALL 309Keyword denoting that the script is to perform any actions needed before 310the package is installed. 311.El 312.Pp 313If the 314.Ar install 315script exits with a non-zero status code, the installation is terminated. 316.It 317The files from the file list are extracted to the chosen prefix. 318.It 319If an 320.Ar install 321script exists for the package, it is executed with the following arguments: 322.Bl -tag -width indentindent 323.It Ar pkg_name 324The name of the package being installed. 325.It Cm POST-INSTALL 326Keyword denoting that the script is to perform any actions needed 327after the package has been installed. 328.El 329.It 330After installation is complete, a copy of the packing list, 331.Ar deinstall 332script, description, and display files are copied into 333.Pa \*[Lt]PKG_DBDIR\*[Gt]/\*[Lt]pkg-name\*[Gt] 334for subsequent possible use by 335.Xr pkg_delete 1 . 336Any package dependencies are recorded in the other packages' 337.Pa +REQUIRED_BY 338file. 339.It 340If the package is a depoted package, then add it to the registered 341by calling 342.Xr pkg_view 1 343accordingly. 344.It 345Finally, if we were upgrading a package, any 346.Pa +REQUIRED_BY 347file that was moved aside before upgrading was started is now moved 348back into place. 349.El 350.Pp 351The 352.Ar install 353script is called with the environment variable 354.Ev PKG_PREFIX 355set to the installation prefix (see the 356.Fl p 357option above). 358This allows a package author to write a script 359that reliably performs some action on the directory where the package 360is installed, even if the user might change it with the 361.Fl p 362flag to 363.Cm pkg_add . 364The scripts are also called with the 365.Ev PKG_METADATA_DIR 366environment variable set to the location of the 367.Pa +* 368meta-data files, and with the 369.Ev PKG_REFCOUNT_DBDIR 370environment variable set to the location of the package reference counts 371database directory. 372If the 373.Fl P 374flag was given to 375.Nm , 376.Ev PKG_DESTDIR 377will be set to 378.Ar destdir . 379Additionally, 380.Ev PKG_METADATA_DIR 381and 382.Ev PKG_REFCOUNT_DBDIR 383are prefixed with 384.Ar destdir . 385.Sh ENVIRONMENT 386See 387.Xr pkg_install.conf 5 388for options, that can also be specified using the environment. 389Packages using views are also affected by the environment variables 390documented for 391.Xr pkg_view 1 . 392.Sh EXAMPLES 393In all cases, 394.Nm 395will try to install binary packages listed in dependencies list. 396.Pp 397You can specify a compiled binary package explicitly on the command line. 398.Bd -literal 399# pkg_add /usr/pkgsrc/packages/All/tcsh-6.14.00.tgz 400.Ed 401.Pp 402If you omit the version number, 403.Nm 404will install the latest version available. 405With 406.Fl v , 407.Nm 408emits more messages to terminal. 409.Bd -literal 410# pkg_add -v /usr/pkgsrc/packages/All/unzip 411.Ed 412.Pp 413You can grab a compiled binary package from remote location by specifying 414a URL. 415The base URL can also be provided by the configuration variable, 416.Dv PKG_PATH . 417.Bd -literal 418# pkg_add -v ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All/firefox-2.0.0.4.tgz 419 420# export PKG_PATH=ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All 421# pkg_add -v firefox 422.Ed 423.Sh SEE ALSO 424.Xr pkg_admin 1 , 425.Xr pkg_create 1 , 426.Xr pkg_delete 1 , 427.Xr pkg_info 1 , 428.Xr pkg_install.conf 5 , 429.Xr pkgsrc 7 430.Sh AUTHORS 431.Bl -tag -width indent -compact 432.It "Jordan Hubbard" 433Initial work and ongoing development. 434.It "John Kohl" 435.Nx 436refinements. 437.It "Hubert Feyrer" 438.Nx 439wildcard dependency processing, pkgdb, upgrading, etc. 440.It Thomas Klausner 441HTTP support. 442.It Joerg Sonnenberger 443Rewrote most of the code base to work without external commands. 444.El 445.Sh BUGS 446Package upgrading needs a lot more work to be really universal. 447.Pp 448Sure to be others. 449