|pkg5| basic operations
We provide a brief summary of the client operations and their invocation
via |pkg1|, the command line client. Use of PackageManager and
other graphical clients is covered by the Image Packaging System User's
Guide for |OS_Name|, or by user documentation of the software
component utilizing image packaging.
Since an image may include hundreds of installed packages, and publisher
repositories may contains hundreds or thousands more available packages,
we note that the list subcommand has a number of options for filtering
these sets of packages into specific groups. To see the set of packages
currently installed in an image, the plain subcommand is used:
/usr/bin/pkg list
With the -u option, list will restrict its output to those
installed packages for which upgrade--newer versions--are available.
This option is a convenient way to detect if newer software has been
released by one or more of the publishers you've subscribed to.
With the -a option, list will list all known packages for the
subscribed publishers.
To install a package, we first need to know the name of the package. Package names are part of a larger set of named entites, called fault-managed resources, and referred to using Fault-Managed Resource Identifiers (FMRIs). A package FMRI contains the name of the package's publisher, a common label for the package, and a version specifier. For instance, a valid package FMRI for the Image Packaging System is:
pkg://opensolaris.org/package/[email protected]
which identifies this instance of package/pkg as the package version
published by opensolaris.org for Build 137 of the development
version of the operating system.
|pkg1| has an abbreviation expansion algorithm so that shorter strings than the full FMRI can be used to match package names for installation.
Once we know the FMRI, installation uses the install subcommand to
|pkg1|:
$ pfexec pkg install package/pkg
|pkg1| will calculate a valid version of package/pkg to install
within the image, and then display progress as it retrieves and executes
the actions that make up that version of the package.
Removal is the opposite of installation, so package removal is done via
the uninstall subcommand to |pkg1|. As an example, to remove the
HTML Tidy library:
$ pfexec pkg uninstall text/tidy
Image packaging supports both local and remote search. Local search is confined to the packages installed within the image, while remote search queries repositories associated with the active list of publishers. The search facility is versatile, and can be used to query metadata, dependencies, and contents for the union of the sets of packages the publishers each offer.
Basic search is available via the search subcommand, with the -l
option to keep the search local to the present image:
$ pkg search -l bash INDEX ACTION VALUE PACKAGE basename dir etc/bash pkg:/shell/[email protected] basename dir usr/share/bash pkg:/shell/[email protected] basename file usr/bin/bash pkg:/shell/[email protected] pkg.fmri set opensolaris.org/shell/bash pkg:/shell/[email protected]
By default, the search subcommand searches remote repositories. In
this mode, it is useful for searching for specific filenames, such as
the name of an executable or an include file:
$ pkg search xpath.h INDEX ACTION VALUE PACKAGE basename file usr/include/libxml2/libxml/xpath.h pkg:/library/[email protected]
Depot servers may also be queried from a web browser, by setting the location to that of the running depot. A browser user interface is provided for search results.
XXX More one search -p, specifically. Maybe also complex queries. Definitely a longer explanation of search here or in the SAG.
Image packaging allows the retrieval and installation of software
package from a variety of publishers, each of whom may offer different,
interesting components. To add an additional publisher, use the
set-publisher subcommand:
/usr/bin/pkg set-publisher ....
In some cases, a publisher's servers may be unavailable. Although
|pkg1| attempts to minimize the impact of downtime or unreachable
repositories, it can be simpler to
disable a publisher for the duration of the outage. set-publisher
makes it easy to disable a publisher:
/usr/bin/pkg set-publisher --disable ....
Over time, a publisher may no longer offer software interesting for your
system. |pkg1| performance is generally not affected by additional
publisher entries, but it is good policy to trim unused configuration
from one's system. To remove a publisher, use pkg unset-publisher:
/usr/bin/pkg unset-publisher ....
XXX .p5i file based publisher addition.
Although generally not needed for typical operations, when testing newly
created packages, it may be convenient to create a temporary image that
can be deleted after testing has been completed. To create an image,
use the image-create subcommand. An initial publisher must be
specified:
/usr/bin/pkg image-create ....
To delete an image, simply remove the directory containing the image.
On a typical |OS_Name| installation, the system image starts at the root
of the filesystem ('/'), with the packaging metadata stored in
/var/pkg.
|pkg1| attempts to determine which image to operate upon automatically,
by scanning its invocation directory. We can identify the target image
via the -R image_directory option to any |pkg1| invocation.