Index of Section 1 Manual Pages
| Interix / SUA | pkg_add.1 | Interix / SUA |
PKG_ADD(1) System General Commands Manual PKG_ADD(1)
NAME
pkg_add - install and update software package distributions
SYNOPSIS
pkg_add [-DfhILMnQSrRuvVx] [-t template] [-p prefix] [-P basepath]
pkg-name [pkgs...]
DESCRIPTION
The pkg_add command is used to extract packages that have been previously
created with the pkg_create(1) command. Selected packages containing
pre-compiled applications can be found on the /Tools FTP site or on the
official /Tools ToolWorks CD. These packages are provided as a conve-
nience for quickly installing software that would otherwise need to be
ported and built manually.
Package names may be specified as filenames (which normally consist
of the package name itself plus the ``.tgz'', ``.tar.gz'', or
``.tar'' suffix) or an FTP location in the form of an URL. For
example, the following is valid:
pkg_add -v ftp://ftp.interopsystems.com/pkgs/3.5/pax-1.3-bin.tgz
If the given package names are not found in the current working
directory, pkg_add will search for them in each directory named by
the PKG_PATH environment variable. Specifying `-' as a package
name causes pkg_add to read from the standard input.
Alternatively, it is possible to add packages interactively from
within the ftp client. For example, the following works:
$ ftp ftp://ftp.interopsystems.com/pkgs/3.5/
250 CWD command successful
ftp> ls p*
227 Entering Passive Mode (64,235,106,194,6,93).
150 Opening ASCII mode data connection for file list
pango-1.4.0.3-bin.tgz
pax-1.3-bin.tgz
php-4.3.6-bin.tgz
pkg-1.5.2-bin.tgz
pkgconfig-0.15.0.1-bin.tgz
plotutils-2.4.1-bin.tgz
226 Transfer complete.
ftp> get pax-1.3-bin.tgz "|pkg_add -v -"
If you will be doing an installation from an FTP site it is always
recommended that you attempt to install packages using the FTP URL
rather than downloading the package. A package may have dependen-
cies that are most easily found and most up to date by an FTP URL
reference.
pkg_add can also be used to update a package from an older version
to a newer version even when the installed package is depended upon
by other packages. In such instances the depending packages will
have their registered dependencies updated to reflect the installa-
tion of the newer version.
Warning: Since the pkg_add command may execute scripts or programs
contained within a package file, your system may be susceptible to
``trojan horses'' or other subtle attacks from miscreants who cre-
ate dangerous packages. Be sure the specified package(s) are from
trusted sources.
Note: With every package installation that has an FTP URL pkg_add
will check that a /Tools member name and password to "ftp.interop-
systems.com" are stored in the ".netrc" file to ease the installa-
tion of depended upon packages. Refer to the ftp manual page for
more information on the ".netrc" file. The exception to this is if
the URL contains a username and password. At such occations the
".netrc" content will not be used.
The options are as follows:
-D Supress the printing of the install-message for the package
if one exists.
-f Force installation to proceed even if prerequisite packages
are not installed or the requirements script fails.
Although pkg_add will still try to find and auto-install
missing prerequisite packages, a failure to find one will
not be fatal.
-h Display the usage for pkg_add.
-I If an installation script exists for a given package, do
not execute it.
-L Do not take the packaging lock. This option should only be
used in very, very rare instances. Normally a lock is taken
to ensure that packaging commands do not run at the same
time and thus cause problems for each other.
-M Run in MASTER mode. This is a very specialized mode for
running pkg_add and is meant to be run in conjunction with
SLAVE mode. When run in this mode, pkg_add does no work
beyond extracting the package into a temporary staging area
(see the -t option), reading in the packing list, and then
dumping it (prefaced by the current staging area) to the
standard output where it may be filtered by a program such
as sed(1). When used in conjunction with SLAVE mode, it
allows you to make radical changes to the package structure
before acting on its contents.
-n Don't actually install a package, just report the steps
that would be taken if it was.
-p prefix
Set prefix as the directory in which to extract files from
a package. If a package has set its default directory, it
will be overridden by this flag. Note that only the first
@cwd directive will be replaced, since pkg_add has no way
of knowing which directory settings are relative and which
are absolute. It is rare in any case to see more than one
directory transition made, but when such does happen and
you wish to have control over all directory transitions,
then you may then wish to look into the use of MASTER and
SLAVE modes (see the -M and -S options).
-P basepath
Base all utilities to be run from the directory basepath
instead of /bin/ (the default). All utilities to be run are
specified with full paths to well known locations instead
of relying on the PATH environment variable to avoid poten-
tial spoofs.
-Q Quiet messages that will not affect the success of the
installation. This is usually used to quiet (supress) mes-
sages that may appear to the average user to be indicating
a problem when there really is no problem. This does not
conflict with the -v option.
-r Re-install the package when the currently installed version
matches the version available for installation. This can be
useful if you believe that part of the installed package
has been corrupted or erroneously modified. It can also be
useful if you have installed a 32-bit based package on a
64-bit system and now want to change to the 64-bit based
package.
-R Do not record the installation of a package. This means
that you cannot deinstall it later, so only use this option
if you know what you are doing!
-S Run in SLAVE mode. This is a very specialized mode for
running pkg_add and is meant to be run in conjunction with
MASTER mode. When run in this mode, pkg_add expects the
release contents to be already extracted and waiting in the
staging area, the location of which is read as a string
from the standard input. The complete packing list is also
read from stdin, and the contents then acted on as normal.
-t template
Use template as the input to mkdtemp(3) when creating a
``staging area''. By default, this is the string
/var/tmp/instmp.XXXXXX, but it may be necessary to override
it in the situation where space in your /var/tmp directory
is limited. Be sure to leave some number of ``X'' charac-
ters for mkdtemp(3) to fill in with a unique ID.
You can get a performance boost by setting the staging area
template to reside on the same disk partition as target
directories for package file installation; often this is
/usr.
-u An option for communiction between pkg_add and pkg_update.
-v Turn on verbose output.
-V Print the version number and exit.
-x Do not use any Internet connection or path, either
explicit, implicit or cached to get a package, a package
dependency or update list.
By default, when adding packages via FTP, the ftp(1) program oper-
ates in ``passive'' mode. If you wish to use active mode instead,
set the FTPMODE environment variable to "active". If pkg_add con-
sistently fails to fetch a package from a site known to work, it
may be because the site does not support passive mode ftp cor-
rectly. This is very rare since pkg_add will try active mode ftp
if the server refuses a passive mode connection.
Technical details
pkg_add extracts each package's ``packing list'' into a special
staging directory in /tmp (or PKG_TMPDIR if set) and then runs
through the following sequence to fully extract the contents of the
package:
1. A check is made to determine if the package is already
recorded as installed. If it is, installation is terminated.
2. A check is made to determine if the package conflicts (from
@pkgcfl directives, see pkg_create(1)) with an already
recorded as installed package. If it is, installation is ter-
minated.
3. All package dependencies (from @pkgdep directives, see
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.
4. A staging area is created under /tmp, and the package is
extracted into the staging area.
5. If the package contains a require script (see pkg_create(1)),
it is executed with the following arguments:
pkg-name The name of the package being installed
INSTALL Keyword denoting to the script that it is to run
an installation requirements check (the keyword
is useful only to scripts which serve multiple
functions).
If the require script exits with a non-zero status code, the
installation is terminated.
6. If the package contains an install script, it is executed with
the following arguments:
pkg-name The name of the package being installed.
PRE-INSTALL Keyword denoting that the script is to perform
any actions needed before the package is
installed.
If the install script exits with a non-zero status code, the
installation is terminated.
7. The packing list is used as a guide for moving (or copying, as
necessary) files from the staging area into their final loca-
tions.
8. If the package contains an mtreefile file (see pkg_create(1)),
then mtree is invoked as:
mtree -u -f mtreefile -d -e -p prefix
where prefix is either the prefix specified with the -p flag
or, if no -p flag was specified, the name of the first direc-
tory named by a @cwd directive within this package.
9. If an install script exists for the package, it is executed
with the following arguments:
pkg_name The name of the package being installed.
POST-INSTALL Keyword denoting that the script is to perform
any actions needed after the package has been
installed.
10. After installation is complete, a copy of the packing list,
deinstall script, description, and display files are copied
into /var/db/pkg/ for subsequent possible use by
pkg_delete(1). Any package dependencies are recorded in the
other packages' /var/db/pkg//+REQUIRED_BY file (if
the environment variable PKG_DBDIR is set, this overrides the
/var/db/pkg/ path shown above).
11. Finally, the staging area is deleted and the program termi-
nates.
The install and require scripts are called with the environment
variable PKG_PREFIX set to the installation prefix (see the -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 -p flag to
pkg_add.
ENVIRONMENT
PKG_PATH If a given package name cannot be found, the directories
named by PKG_PATH are searched. It should contain a series
of entries separated by colons. Each entry consists of a
directory name. The current directory may be indicated
implicitly by an empty directory name, or explicitly by a
single period (`.'). After PKG_PATH is checked any "hints"
about locations that are stored in the package will be
attempted.
PKG_DBDIR Where to register packages instead of /var/db/pkg.
PKG_TMPDIR Temporary area where packages will be extracted, instead of
/var/tmp.
SEE ALSO
ftp(1), gunzip(1), pkg_create(1), pkg_delete(1), pkg_info(1),
pkg_update(1), tar(1), mkdtemp(3), sysconf(3), mtree(8),
http://www.interopsystems.com/tools/pkg_install.htm
AUTHORS
Jordan Hubbard
Initial work.
John Kohl
NetBSD refinements.
Rodney Ruddock
Interix enhancements and changes.
CAVEATS
Package extraction does need a temporary area that
o is big enough to hold the complete extracted package,
o can hold executable scripts.
pkg_add looks through ${PKG_TMPDIR}, ${TMPDIR}, /var/tmp, /tmp, /usr/tmp
for such an area, in sequence.
If ${TMPDIR} and /var/tmp are mounted noexec, you must set PKG_TMPDIR to
a suitable area, as pkg_add has no way to check for noexec status except
by failing to run installation scripts.
BUGS
Hard links between files in a distribution are only preserved if either
(1) the staging area is on the same file system as the target directory
of all the links to the file, or (2) all the links to the file are brack-
eted by @cwd directives in the contents file, and the link names are
extracted with a single tar(1) command (not split between invocations due
to exec argument-space limitations; this depends on the value returned by
sysconf(_SC_ARG_MAX)).
Sure to be others.
Interix September 11, 2007 Interix