449 lines
12 KiB
Groff
449 lines
12 KiB
Groff
.\" $NetBSD: pkg_add.1,v 1.1.1.12 2011/02/18 22:32:28 aymeric Exp $
|
|
.\"
|
|
.\" FreeBSD install - a package for the installation and maintenance
|
|
.\" of non-core utilities.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" Jordan K. Hubbard
|
|
.\"
|
|
.\"
|
|
.\" @(#)pkg_add.1
|
|
.\"
|
|
.Dd June 16, 2010
|
|
.Dt PKG_ADD 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pkg_add
|
|
.Nd a utility for installing and upgrading software package distributions
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl AfILnRUuVv
|
|
.Op Fl C Ar config
|
|
.Op Fl K Ar pkg_dbdir
|
|
.Op Fl m Ar machine
|
|
.Op Fl P Ar destdir
|
|
.Op Fl p Ar prefix
|
|
.Op Fl W Ar viewbase
|
|
.Op Fl w Ar view
|
|
.Ar Oo Oo Li ftp|http Oc Ns Li :// Ns Oo Ar user Oc Ns \
|
|
Oo Li \&: Ns Ar password Oc \
|
|
Ns Li @ Oc Ns Ar host Ns Oo Li \&: Ns Ar port Oc Ns \
|
|
Oo Li / Ns Ar path/ Oc Ns Ar pkg-name ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
command is used to extract and upgrade packages that have been
|
|
previously created with the
|
|
.Xr pkg_create 1
|
|
command.
|
|
Packages are prepared collections of pre-built binaries, documentation,
|
|
configurations, installation instructions and/or other files.
|
|
.Nm
|
|
can recursively install other packages that the current package
|
|
depends on or requires from both local disk and via FTP or HTTP.
|
|
.Sh WARNING
|
|
.Bf -emphasis
|
|
Since the
|
|
.Nm
|
|
command may execute scripts or programs contained within a package file,
|
|
your system may be susceptible to
|
|
.Dq Trojan horses
|
|
or other subtle
|
|
attacks from miscreants who create dangerous package files.
|
|
.Pp
|
|
You are advised to verify the competence and identity of those who
|
|
provide installable package files.
|
|
For extra protection, use the digital signatures provided where possible
|
|
(see the
|
|
.Xr pkg_install.conf 5 ) ,
|
|
or, failing that, use
|
|
.Xr tar 1
|
|
to extract the package file, and inspect its contents and scripts
|
|
to ensure it poses no danger to your system's integrity.
|
|
Pay particular attention to any
|
|
.Pa +INSTALL
|
|
or
|
|
.Pa +DEINSTALL
|
|
files, and inspect the
|
|
.Pa +CONTENTS
|
|
file for
|
|
.Cm @cwd ,
|
|
.Cm @mode
|
|
(check for setuid),
|
|
.Cm @dirrm ,
|
|
.Cm @exec ,
|
|
and
|
|
.Cm @unexec
|
|
directives, and/or use the
|
|
.Xr pkg_info 1
|
|
command to examine the package file.
|
|
.Ef
|
|
.Sh OPTIONS
|
|
The following command line arguments are supported:
|
|
.Bl -tag -width indent
|
|
.It Ar pkg-name [ ... ]
|
|
The named packages are installed.
|
|
.Nm
|
|
will first try to use
|
|
.Ar pkg-name
|
|
as full URL or path name without any wildcard processing.
|
|
If that fails,
|
|
.Nm
|
|
will try to match packages using wildcard processing.
|
|
If that fails as well and
|
|
.Ar pkg-name
|
|
does not contain any /, the entries of the
|
|
.Dv PKG_PATH
|
|
variable are searched using the wildcard processing rules.
|
|
.It Fl A
|
|
Mark package as installed automatically, as dependency of another
|
|
package.
|
|
You can use
|
|
.Dl Ic pkg_admin set automatic=YES
|
|
to mark packages this way after installation, and
|
|
.Dl Ic pkg_admin unset automatic
|
|
to remove the mark.
|
|
If you
|
|
.Nm
|
|
a package without specifying
|
|
.Fl A
|
|
after it had already been automatically installed, the mark is
|
|
removed.
|
|
.It Fl C Ar config
|
|
Read the configuration file from
|
|
.Ar config
|
|
instead of the system default.
|
|
.It Fl f
|
|
Force installation to proceed even if prerequisite packages are not
|
|
installed or the install script fails.
|
|
Although
|
|
.Nm
|
|
will still try to find and auto-install missing prerequisite packages,
|
|
a failure to find one will not be fatal.
|
|
This flag also overrides the fatal error when the operating system or
|
|
architecture the package was built on differ from that of the host.
|
|
.It Fl D
|
|
Force updating even if the dependencies of depending packages are not
|
|
satisfied by the new package.
|
|
This is used by "make replace", after which one would typically
|
|
replace the depending packages.
|
|
.It Fl I
|
|
If an installation script exists for a given package, do not execute it.
|
|
.It Fl K Ar pkg_dbdir
|
|
Override the value of the
|
|
.Dv PKG_DBDIR
|
|
configuration option with the value
|
|
.Ar pkg_dbdir .
|
|
.It Fl L
|
|
Don't add the package to any views after installation.
|
|
.It Fl m
|
|
Override the machine architecture returned by uname with
|
|
.Ar machine .
|
|
.It Fl n
|
|
Don't actually install a package, just report the steps that
|
|
would be taken if it was.
|
|
.It Fl P Ar destdir
|
|
Prefix all file and directory names with
|
|
.Ar destdir .
|
|
For packages without install scripts this has the same behavior as
|
|
using
|
|
.Xr chroot 8 .
|
|
.It Fl p Ar prefix
|
|
Override the prefix stored in the package with
|
|
.Ar prefix .
|
|
.It Fl R
|
|
Do not record the installation of a package.
|
|
This implies
|
|
.Fl I .
|
|
This means that you cannot deinstall it later, so only use this option if
|
|
you know what you are doing!
|
|
.It Fl U
|
|
Replace an already installed version from a package.
|
|
Implies
|
|
.Fl u .
|
|
.It Fl u
|
|
If the package that's being installed is already installed,
|
|
an update is performed.
|
|
Installed dependent packages are updated recursively, if they are too
|
|
old to fulfill the dependencies of the to-be-installed version.
|
|
See below for a more detailed description of the process.
|
|
.It Fl V
|
|
Print version number and exit.
|
|
.It Fl v
|
|
Turn on verbose output.
|
|
.It Fl W Ar viewbase
|
|
Passed down to
|
|
.Xr pkg_view 1
|
|
for managed views.
|
|
.It Fl w Ar view
|
|
Passed down to
|
|
.Xr pkg_view 1
|
|
for managed views.
|
|
.El
|
|
.Pp
|
|
One or more
|
|
.Ar pkg-name
|
|
arguments may be specified, each being either a file containing the
|
|
package (these usually ending with the
|
|
.Dq .tgz
|
|
suffix) or a
|
|
URL pointing at a file available on an ftp or web site.
|
|
Thus you may extract files directly from their anonymous ftp or WWW
|
|
locations (e.g.,
|
|
.Nm
|
|
ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/shells/bash-3.2.9.tgz
|
|
or
|
|
.Nm
|
|
http://www.example.org/packages/screen-4.0.tbz).
|
|
Note: For ftp transfers, if you wish to use
|
|
.Bf -emphasis
|
|
passive mode
|
|
.Ef
|
|
ftp in such transfers, set the variable
|
|
.Bf -emphasis
|
|
FTP_PASSIVE_MODE
|
|
.Ef
|
|
to some value in your environment.
|
|
Otherwise, the more standard ACTIVE mode may be used.
|
|
If
|
|
.Nm
|
|
consistently fails to fetch a package from a site known to work,
|
|
it may be because you have a firewall that demands the usage of
|
|
.Bf -emphasis
|
|
passive mode
|
|
.Ef
|
|
ftp.
|
|
.Sh TECHNICAL DETAILS
|
|
.Nm
|
|
extracts each package's meta data (including the
|
|
.Dq packing list )
|
|
to memory and then runs through the following sequence to fully extract
|
|
the contents of the package:
|
|
.Bl -enum -offset indent
|
|
.It
|
|
A check is made to determine if the package or another version of it
|
|
is already recorded as installed.
|
|
If it is,
|
|
installation is terminated if the
|
|
.Fl u
|
|
or
|
|
.Fl U
|
|
options are not given.
|
|
.Pp
|
|
If the same version is installed and
|
|
.Fl U
|
|
is not given, it is marked as manually installed and process stops.
|
|
If the
|
|
.Fl u
|
|
option is given, it's assumed the package should be replaced by the
|
|
new version instead.
|
|
Before doing so, all packages that depend on the
|
|
pkg being upgraded are checked if they also work with the new version.
|
|
If that test is not successful, the dependent packages are updated first.
|
|
The replacing is then prepared by moving an existing
|
|
.Pa +REQUIRED_BY
|
|
file aside (if it exists), and running
|
|
.Xr pkg_delete 1
|
|
on the installed package.
|
|
Installation then proceeds as if the package
|
|
was not installed, and restores the
|
|
.Pa +REQUIRED_BY
|
|
file afterwards.
|
|
.It
|
|
The package build information is extracted from the
|
|
.Pa +BUILD_INFO
|
|
file and compared against the result of
|
|
.Xr uname 3 .
|
|
If the operating system or architecture of the package differ from
|
|
that of the host, installation is aborted.
|
|
This behavior is overridable with the
|
|
.Fl f
|
|
flag.
|
|
.It
|
|
The package build information from
|
|
.Pa +BUILD_INFO
|
|
is then checked for
|
|
.Ev USE_ABI_DEPENDS=NO
|
|
(or
|
|
.Ev IGNORE_RECOMMENDED ) .
|
|
If the package was built with ABI dependency recommendations ignored,
|
|
a warning will be issued.
|
|
.It
|
|
A check is made to determine if the package conflicts (from
|
|
.Cm @pkgcfl
|
|
directives, see
|
|
.Xr pkg_create 1 )
|
|
with an already recorded as installed package or if an installed package
|
|
conflicts with the package.
|
|
If it is, installation is terminated.
|
|
.It
|
|
The file list of the package is compared to the file lists of the
|
|
installed packages.
|
|
If there is any overlap, the installation is terminated.
|
|
.It
|
|
All package dependencies (from
|
|
.Cm @pkgdep
|
|
directives, see
|
|
.Xr pkg_create 1 )
|
|
are read from the packing list.
|
|
If any of these required packages are not currently installed,
|
|
an attempt is made to find and install it;
|
|
if the missing package cannot be found or installed,
|
|
the installation is terminated.
|
|
.It
|
|
If the package contains an
|
|
.Ar install
|
|
script, it is executed with the following arguments:
|
|
.Bl -tag -width indentindent
|
|
.It Ar pkg-name
|
|
The name of the package being installed.
|
|
.It Cm PRE-INSTALL
|
|
Keyword denoting that the script is to perform any actions needed before
|
|
the package is installed.
|
|
.El
|
|
.Pp
|
|
If the
|
|
.Ar install
|
|
script exits with a non-zero status code, the installation is terminated.
|
|
.It
|
|
The files from the file list are extracted to the chosen prefix.
|
|
.It
|
|
If an
|
|
.Ar install
|
|
script exists for the package, it is executed with the following arguments:
|
|
.Bl -tag -width indentindent
|
|
.It Ar pkg_name
|
|
The name of the package being installed.
|
|
.It Cm POST-INSTALL
|
|
Keyword denoting that the script is to perform any actions needed
|
|
after the package has been installed.
|
|
.El
|
|
.It
|
|
After installation is complete, a copy of the packing list,
|
|
.Ar deinstall
|
|
script, description, and display files are copied into
|
|
.Pa \*[Lt]PKG_DBDIR\*[Gt]/\*[Lt]pkg-name\*[Gt]
|
|
for subsequent possible use by
|
|
.Xr pkg_delete 1 .
|
|
Any package dependencies are recorded in the other packages'
|
|
.Pa +REQUIRED_BY
|
|
file.
|
|
.It
|
|
If the package is a depoted package, then add it to the registered
|
|
by calling
|
|
.Xr pkg_view 1
|
|
accordingly.
|
|
.It
|
|
Finally, if we were upgrading a package, any
|
|
.Pa +REQUIRED_BY
|
|
file that was moved aside before upgrading was started is now moved
|
|
back into place.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ar install
|
|
script is called with the environment variable
|
|
.Ev PKG_PREFIX
|
|
set to the installation prefix (see the
|
|
.Fl p
|
|
option above).
|
|
This allows a package author to write a script
|
|
that reliably performs some action on the directory where the package
|
|
is installed, even if the user might change it with the
|
|
.Fl p
|
|
flag to
|
|
.Cm pkg_add .
|
|
The scripts are also called with the
|
|
.Ev PKG_METADATA_DIR
|
|
environment variable set to the location of the
|
|
.Pa +*
|
|
meta-data files, and with the
|
|
.Ev PKG_REFCOUNT_DBDIR
|
|
environment variable set to the location of the package reference counts
|
|
database directory.
|
|
If the
|
|
.Fl P
|
|
flag was given to
|
|
.Nm ,
|
|
.Ev PKG_DESTDIR
|
|
will be set to
|
|
.Ar destdir .
|
|
Additionally,
|
|
.Ev PKG_METADATA_DIR
|
|
and
|
|
.Ev PKG_REFCOUNT_DBDIR
|
|
are prefixed with
|
|
.Ar destdir .
|
|
.Sh ENVIRONMENT
|
|
See
|
|
.Xr pkg_install.conf 5
|
|
for options, that can also be specified using the environment.
|
|
Packages using views are also affected by the environment variables
|
|
documented for
|
|
.Xr pkg_view 1 .
|
|
.Sh EXAMPLES
|
|
In all cases,
|
|
.Nm
|
|
will try to install binary packages listed in dependencies list.
|
|
.Pp
|
|
You can specify a compiled binary package explicitly on the command line.
|
|
.Bd -literal
|
|
# pkg_add /usr/pkgsrc/packages/All/tcsh-6.14.00.tgz
|
|
.Ed
|
|
.Pp
|
|
If you omit the version number,
|
|
.Nm
|
|
will install the latest version available.
|
|
With
|
|
.Fl v ,
|
|
.Nm
|
|
emits more messages to terminal.
|
|
.Bd -literal
|
|
# pkg_add -v /usr/pkgsrc/packages/All/unzip
|
|
.Ed
|
|
.Pp
|
|
You can grab a compiled binary package from remote location by specifying
|
|
a URL.
|
|
The base URL can also be provided by the configuration variable,
|
|
.Dv PKG_PATH .
|
|
.Bd -literal
|
|
# pkg_add -v ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All/firefox-2.0.0.4.tgz
|
|
|
|
# export PKG_PATH=ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All
|
|
# pkg_add -v firefox
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr pkg_admin 1 ,
|
|
.Xr pkg_create 1 ,
|
|
.Xr pkg_delete 1 ,
|
|
.Xr pkg_info 1 ,
|
|
.Xr pkg_install.conf 5 ,
|
|
.Xr pkgsrc 7
|
|
.Sh AUTHORS
|
|
.Bl -tag -width indent -compact
|
|
.It "Jordan Hubbard"
|
|
Initial work and ongoing development.
|
|
.It "John Kohl"
|
|
.Nx
|
|
refinements.
|
|
.It "Hubert Feyrer"
|
|
.Nx
|
|
wildcard dependency processing, pkgdb, upgrading, etc.
|
|
.It Thomas Klausner
|
|
HTTP support.
|
|
.It Joerg Sonnenberger
|
|
Rewrote most of the code base to work without external commands.
|
|
.El
|
|
.Sh BUGS
|
|
Package upgrading needs a lot more work to be really universal.
|
|
.Pp
|
|
Sure to be others.
|