1.\" $NetBSD: pkg_add.1,v 1.4 2021/04/10 19:49:59 nia 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 March 8, 2021 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 AfhInRUuVv 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.Ar Oo Oo Li ftp|http Oc Ns Li :// Ns Oo Ar user Oc Ns \ 35Oo Li \&: Ns Ar password Oc \ 36Ns Li @ Oc Ns Ar host Ns Oo Li \&: Ns Ar port Oc Ns \ 37Oo Li / Ns Ar path/ Oc Ns Ar pkg-name ... 38.Sh DESCRIPTION 39The 40.Nm 41command is used to extract and upgrade packages that have been 42previously created with the 43.Xr pkg_create 1 44command. 45Packages are prepared collections of pre-built binaries, documentation, 46configurations, installation instructions and/or other files. 47.Nm 48can recursively install other packages that the current package 49depends on or requires from both local disk and via FTP or HTTP. 50.Sh WARNING 51.Bf -emphasis 52Since the 53.Nm 54command may execute scripts or programs contained within a package file, 55your system may be susceptible to 56.Dq Trojan horses 57or other subtle 58attacks from miscreants who create dangerous package files. 59.Pp 60You are advised to verify the competence and identity of those who 61provide installable package files. 62For extra protection, use the digital signatures provided where possible 63(see the 64.Xr pkg_install.conf 5 ) , 65or, failing that, use 66.Xr tar 1 67to extract the package file, and inspect its contents and scripts 68to ensure it poses no danger to your system's integrity. 69Pay particular attention to any 70.Pa +INSTALL 71or 72.Pa +DEINSTALL 73files, and inspect the 74.Pa +CONTENTS 75file for 76.Cm @cwd , 77.Cm @mode 78(check for setuid), 79.Cm @dirrm , 80.Cm @exec , 81and 82.Cm @unexec 83directives, and/or use the 84.Xr pkg_info 1 85command to examine the package file. 86.Ef 87.Sh OPTIONS 88The following command line arguments are supported: 89.Bl -tag -width indent 90.It Ar pkg-name [ ... ] 91The named packages are installed. 92.Nm 93will first try to use 94.Ar pkg-name 95as full URL or path name without any wildcard processing. 96If that fails, 97.Nm 98will try to match packages using wildcard processing. 99If that fails as well and 100.Ar pkg-name 101does not contain any /, the entries of the 102.Dv PKG_PATH 103variable are searched using the wildcard processing rules. 104.It Fl A 105Mark package as installed automatically, as dependency of another 106package. 107You can use 108.Dl Ic pkg_admin set automatic=YES 109to mark packages this way after installation, and 110.Dl Ic pkg_admin unset automatic 111to remove the mark. 112If you 113.Nm 114a package without specifying 115.Fl A 116after it had already been automatically installed, the mark is 117removed. 118.It Fl C Ar config 119Read the configuration file from 120.Ar config 121instead of the system default. 122.It Fl D 123Force updating even if the dependencies of depending packages are not 124satisfied by the new package. 125This is used by "make replace", after which one would typically 126replace the depending packages. 127.It Fl f 128Force installation to proceed even if prerequisite packages are not 129installed or the install script fails. 130Although 131.Nm 132will still try to find and auto-install missing prerequisite packages, 133a failure to find one will not be fatal. 134This flag also overrides the fatal error when the operating system or 135architecture the package was built on differ from that of the host. 136.It Fl h 137Display help and exit. 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 m 146Override the machine architecture returned by uname with 147.Ar machine . 148.It Fl n 149Don't actually install a package, just report the steps that 150would be taken if it was. 151.It Fl P Ar destdir 152Prefix all file and directory names with 153.Ar destdir . 154For packages without install scripts this has the same behavior as 155using 156.Xr chroot 8 . 157.It Fl p Ar prefix 158Override the prefix stored in the package with 159.Ar prefix . 160.It Fl R 161Do not record the installation of a package. 162This implies 163.Fl I . 164This means that you cannot deinstall it later, so only use this option if 165you know what you are doing! 166.It Fl U 167Replace an already installed version from a package. 168Implies 169.Fl u . 170.It Fl u 171If the package that's being installed is already installed, 172an update is performed. 173Installed dependent packages are updated recursively, if they are too 174old to fulfill the dependencies of the to-be-installed version. 175See below for a more detailed description of the process. 176.It Fl V 177Print version number and exit. 178.It Fl v 179Turn on verbose output. 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 192http://cdn.NetBSD.org/pub/pkgsrc/packages/NetBSD/x86_64/9.0/All/bash-5.0.18.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 330Finally, if we were upgrading a package, any 331.Pa +REQUIRED_BY 332file that was moved aside before upgrading was started is now moved 333back into place. 334.El 335.Pp 336The 337.Ar install 338script is called with the environment variable 339.Ev PKG_PREFIX 340set to the installation prefix (see the 341.Fl p 342option above). 343This allows a package author to write a script 344that reliably performs some action on the directory where the package 345is installed, even if the user might change it with the 346.Fl p 347flag to 348.Cm pkg_add . 349The scripts are also called with the 350.Ev PKG_METADATA_DIR 351environment variable set to the location of the 352.Pa +* 353meta-data files, and with the 354.Ev PKG_REFCOUNT_DBDIR 355environment variable set to the location of the package reference counts 356database directory. 357If the 358.Fl P 359flag was given to 360.Nm , 361.Ev PKG_DESTDIR 362will be set to 363.Ar destdir . 364Additionally, 365.Ev PKG_METADATA_DIR 366and 367.Ev PKG_REFCOUNT_DBDIR 368are prefixed with 369.Ar destdir . 370.Sh ENVIRONMENT 371See 372.Xr pkg_install.conf 5 373for options, that can also be specified using the environment. 374.Sh EXAMPLES 375In all cases, 376.Nm 377will try to install binary packages listed in dependencies list. 378.Pp 379You can grab a compiled binary package from remote location by specifying 380a URL: 381.Bd -literal 382# pkg_add http://cdn.NetBSD.org/pub/pkgsrc/packages/NetBSD/x86_64/9.0/All/firefox-84.0.tgz 383.Ed 384.Pp 385The base URL can also be provided by the configuration variable, 386.Dv PKG_PATH : 387.Bd -literal 388# export PKG_PATH=http://cdn.NetBSD.org/pub/pkgsrc/packages/NetBSD/x86_64/9.0/All 389# pkg_add firefox 390.Ed 391.Pp 392You can also specify a compiled binary package by filesystem path: 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.Sh SEE ALSO 408.Xr pkg_admin 1 , 409.Xr pkg_create 1 , 410.Xr pkg_delete 1 , 411.Xr pkg_info 1 , 412.Xr pkg_install.conf 5 , 413.Xr pkgsrc 7 414.Sh AUTHORS 415.Bl -tag -width indent -compact 416.It "Jordan Hubbard" 417Initial work and ongoing development. 418.It "John Kohl" 419.Nx 420refinements. 421.It "Hubert Feyrer" 422.Nx 423wildcard dependency processing, pkgdb, upgrading, etc. 424.It Thomas Klausner 425HTTP support. 426.It Joerg Sonnenberger 427Rewrote most of the code base to work without external commands. 428.El 429.Sh BUGS 430Package upgrading needs a lot more work to be really universal. 431.Pp 432Sure to be others. 433