Application Packaging Developer's Guide

Chapter 4 Verifying and Transferring a Package

This chapter describes how to verify your package's integrity and transfer it to a distribution medium, such as floppy disk or a CD-ROM.

This is a list of the overview information in this chapter:

Verifying and Transferring a Package (Task Map)

The table below describes the steps you should follow in order to verify your package's integrity and transfer it to a distribution medium.

Table 4–1 Verifying and Transferring a Package Task Map

Task 

Description 

Instructions 

1. Build Your Package 

Build your package on disk. 

Chapter 2, Building a Package

2. Install Your Package 

Test your package by installing it and making sure that it installs without errors. 

How to Install a Package on a Standalone System or Server

3. Verify Your Package's Integrity 

Use the pkgchk command to verify the integrity of your package. 

How to Verify the Integrity of a Package

4. Obtain Other Package Information 

Optional. Use the pkginfo and pkgparam commands to perform package-specific verification.

Displaying Additional Information About Installed Packages

5. Remove the Installed Package 

Use the pkgrm command to remove your installed package from the system.

How to Remove a Package

6. Transfer Your Package to a Distribution Medium 

Use the pkgtrans command to transfer your package (in package format) to a distribution medium.

How to Transfer a Package to a Distribution Medium

Installing Software Packages

Software packages are installed using the pkgadd command. This command transfers the contents of a software package from the distribution medium or directory and installs it onto a system.

This section provides basic installation instructions for installing your package in order to verify that it installs correctly.

The Installation Software Database

Information for all packages installed on a system is kept in the installation software database. There is an entry for every object in a package, with information such as the component name, where it resides, and its type. An entry contains a record of the package to which a component belongs; other packages that might reference the component; and information such as path name, where the component resides and the component type. Entries are added and removed automatically by the pkgadd and pkgrm commands. You can view the information in the database by using the pkgchk and the pkginfo commands.

Two types of information are associated with each package component. The attribute information describes the component itself. For example, the component's access permissions, owner ID, and group ID are attribute information. The content information describes the contents of the component, such as file size and time of last modification.

The installation software database keeps track of the package status. A package can be either fully installed (it has successfully completed the installation process), or partially installed (it did not successfully complete the installation process).

When a package is partially installed, portions of a package may have been installed before installation was terminated; thus, part of the package is installed, and recorded in the database, and part is not. When you reinstall the package, you are prompted to start at the point where installation stopped because the pkgadd command can access the database and detect which portions have already been installed. You can also remove the portions that have been installed, based on the information in the installation software database using the pkgrm command.

Interacting With the pkgadd Command

If the pkgadd command encounters a problem, it first checks the installation administration file for instructions. (See admin(4) for more information.) If no instructions exist, or if the relevant parameter in the administration file is set to ask, the pkgadd displays a message describing the problem and prompts for a reply. The prompt is usually Do you want to continue with this installation?. You should respond with yes, no, or quit.

If you have specified more than one package, no stops installation of the package being installed but pkgadd continues with installation of the other packages. quit indicates that pkgadd should stop installation of all packages.

Installing Packages on Standalone Systems or Servers in a Homogeneous Environment

This section describes how to install packages on a standalone or a server system in a homogeneous environment.

ProcedureHow to Install a Package on a Standalone System or Server

  1. Build your package.

    See Building a Package, if needed.

  2. Log in to the system as superuser.

  3. Add the software package to the system.


    # pkgadd -d device-name [pkg-abbrev...]

    -d device-name

    Specifies the location of the package. Note that device-name can be a full directory path name or the identifiers for a tape, floppy disk, or removable disk.

    pkg-abbrev

    Is the name of one or more packages (separated by spaces) to be added. If omitted, pkgadd installs all available packages.


Example 4–1 Installing Packages on Standalones and Servers

To install a software package named pkgA from a tape device named /dev/rmt/0, you would enter the following command:


# pkgadd -d /dev/rmt/0 pkgA

You can also install multiple packages at the same time, as long as you separate package names with a space, as follows:


# pkgadd -d /dev/rmt/0 pkgA pkgB pkgC

If you do not name the device on which the package resides, the command checks the default spool directory (/var/spool/pkg). If the package is not there, the installation fails.


See Also

If you are ready to go to the next task, see How to Verify the Integrity of a Package.

Verifying the Integrity of a Package

The pkgchk command enables you to check the integrity of packages, whether they are installed on a system or in package format (ready to be installed with the pkgadd command). It confirms package structure or the installed files and directories, or displays information about package objects. The pkgchk command can list or check the following:

For more information about this command, refer to pkgchk(1M).

The pkgchk command performs two kinds of checks. It checks file attributes (the permissions and ownership of a file and major/minor numbers for block or character special devices) and the file contents (the size, checksum, and modification date). By default, the command checks both the file attributes and the file contents.

The pkgchk command also compares the file attributes and contents of the installed package against the installation software database. The entries concerning a package may have been changed since the time of installation; for example, another package may have changed a package component. The database reflects that change.

ProcedureHow to Verify the Integrity of a Package

  1. Install your package.

    See How to Install a Package on a Standalone System or Server, if needed.

  2. Verify the integrity of your package.


    # pkgchk  [-v] [-R root-path] [pkg-abbrev...]

    -v

    Lists files as they are processed. 

    -R root-path

    Specifies the location of the client system's root file system. 

    pkg-abbrev

    Is the name of one or more packages (separated by spaces) to be checked. If omitted, pkgchk checks all available packages.


Example 4–2 Verifying the Integrity of a Package

This example shows the command you should use to verify the integrity of an installed package.


$ pkgchk pkg-abbrev
$

If there are errors, the pkgchk command prints them. Otherwise, it does not print anything and returns an exit code of 0. If you do not supply a package abbreviation, then it will check all of the packages on the system.

Alternately, you could use the -v option, which will print a list of files in the package if there are no errors. For example:


$ pkgchk -v SUNWcadap
/opt/SUNWcadap
/opt/SUNWcadap/demo
/opt/SUNWcadap/demo/file1
/opt/SUNWcadap/lib
/opt/SUNWcadap/lib/file2
/opt/SUNWcadap/man
/opt/SUNWcadap/man/man1
/opt/SUNWcadap/man/man1/file3.1
/opt/SUNWcadap/man/man1/file4.1
/opt/SUNWcadap/man/windex
/opt/SUNWcadap/srcfiles
/opt/SUNWcadap/srcfiles/file5
/opt/SUNWcadap/srcfiles/file6
$

If you need to verify a package that is installed on a client system's root file system, use this command:


$ pkgchk -v -R root-path pkg-abbrev

See Also

If you are ready to go to the next task, see How to Obtain Information With the pkginfo Command.

Displaying Additional Information About Installed Packages

You can use two other commands to display information about installed packages:

The pkgparam Command

The pkgparam command enables you to display the values associated with the parameters you specified on the command line. The values are retrieved from either the pkginfo file for a specific package, or from the file you name. One parameter value is shown per line. You can display the values only or the parameters and their values.

ProcedureHow to Obtain Information With the pkgparam Command

  1. Install your package.

    See How to Install a Package on a Standalone System or Server, if needed.

  2. Display additional information about your package.


    # pkgparam [-v] pkg-abbrev [param...]

    -v

    Displays the name of the parameter and its value. 

    pkg-abbrev

    Is the name of a specific package. 

    param

    Specifies one or more parameters whose value is displayed. 


Example 4–3 Obtaining Information With the pkgparam Command

For example, to display values only, use this command.


$ pkgparam SUNWcadap
none
/opt
US/Mountain
/sbin:/usr/sbin:/usr/bin:/usr/sadm/install/bin
/usr/sadm/sysadm
SUNWcadap
Chip designers need CAD application software to design abc
chips.  Runs only on xyz hardware and is installed in the usr
partition.
system
release 1.0
SPARC
venus990706083849
SUNWcadap
/var/sadm/pkg/SUNWcadap/save
Jul 7 1999 09:58
$

To display parameters and their values, use the following command.


$ pkgparam -v SUNWcadap
pkgparam -v SUNWcadap
CLASSES='none'
BASEDIR='/opt'
TZ='US/Mountain'
PATH='/sbin:/usr/sbin:/usr/bin:/usr/sadm/install/bin'
OAMBASE='/usr/sadm/sysadm'
PKG='SUNWcadap'
NAME='Chip designers need CAD application software to design abc chips.  
Runs only on xyz hardware and is installed in the usr partition.'
CATEGORY='system'
VERSION='release 1.0'
ARCH='SPARC'
PSTAMP='venus990706083849'
PKGINST='SUNWcadap'
PKGSAV='/var/sadm/pkg/SUNWcadap/save'
INSTDATE='Jul 7 1999 09:58'
$

Or, if you want to display the value of a specific parameter, use this format:


$ pkgparam SUNWcadap BASEDIR
/opt
$

For more information, refer to pkgparam(1).


See Also

If you are ready to go to the next task, see How to Remove a Package.

The pkginfo Command

You can display information about installed packages with the pkginfo command. This command has several options that enable you to customize both the format and the contents of the display.

You can request information about any number of package instances.

The Default pkginfo Display

When the pkginfo command is executed without options, it displays the category, package instance, and package name of all packages that have been completely installed on your system. The display is organized by categories as shown in the following example.


$ pkginfo
.
.
.
system      SUNWinst       Install Software
system      SUNWipc        Interprocess Communications
system      SUNWisolc      XSH4 conversion for ISO Latin character sets
application SUNWkcspf      KCMS Optional Profiles
application SUNWkcspg      KCMS Programmers Environment
application SUNWkcsrt      KCMS Runtime Environment
.
.
.
$

Customizing the Format of the pkginfo Display

You can get a pkginfo display in any of three formats: short, extracted, and long.

The short format is the default. It shows only the category, package abbreviation, and full package name, as shown in The Default pkginfo Display.

The extracted format shows the package abbreviation, package name, package architecture (if available), and package version (if available). Use the -x option to request the extracted format as shown in the next example.


$ pkginfo -x
.
.
.
SUNWipc         Interprocess Communications
                (sparc) 11.8.0,REV=1999.08.20.12.37
SUNWisolc       XSH4 conversion for ISO Latin character sets
                (sparc) 1.0,REV=1999.07.10.10.10
SUNWkcspf       KCMS Optional Profiles
                (sparc) 1.1.2,REV=1.5
SUNWkcspg       KCMS Programmers Environment
                (sparc) 1.1.2,REV=1.5
.
.
.
$

Using the -l option produces a display in the long format showing all of the available information about a package, as in the following example.


$ pkginfo -l SUNWcadap
   PKGINST:  SUNWcadap
      NAME:  Chip designers need CAD application software to
design abc chips.  Runs only on xyz hardware and is installed
in the usr partition.
  CATEGORY:  system
      ARCH:  SPARC
   VERSION:  release 1.0
   BASEDIR:  /opt
    PSTAMP:  system980706083849
  INSTDATE:  Jul 7 1999 09:58
    STATUS:  completely installed
     FILES:     13 installed pathnames
                 6 directories
                 3 executables
              3121 blocks used (approx)
$

Parameter Descriptions for the pkginfo Long Format

The table below describes the package parameters that can be displayed for each package. A parameter and its value are displayed only when the parameter has a value assigned to it.

Table 4–2 Package Parameters

Parameter 

Description 

ARCH

The architecture supported by this package. 

BASEDIR

The base directory in which the software package resides (shown if the package is relocatable). 

CATEGORY

The software category, or categories, of which this package is a member (for example, system or application).

CLASSES

A list of classes defined for a package. The order of the list determines the order in which the classes are installed. Classes listed first will be installed first (on a media by media basis). This parameter may be modified by the request script.  

DESC

Text that describes the package. 

EMAIL

The electronic mail address for user inquiries. 

HOTLINE

Information on how to receive hotline help about this package. 

INTONLY

Indicates that the package should only be installed interactively when set to any non-NULL value. 

ISTATES

A list of allowable run states for package installation (for example, S s 1).

MAXINST

The maximum number of package instances that should be allowed on a machine at the same time. By default, only one instance of a package is allowed. 

NAME

The package name, generally text describing the package abbreviation. 

ORDER

A list of classes defining the order in which they should be put on the medium. Used by the pkgmk command in creating the package. Classes not defined in this parameter are placed on the medium using the standard ordering procedures.

PKGINST

Abbreviation for the package being installed. 

PSTAMP

The production stamp for this package. 

RSTATES

A list of allowable run states for package removal (for example, S s 1).

ULIMIT

If set, this parameter is passed as an argument to the ulimit command, which establishes the maximum size of a file during installation. This applies only to files created by procedure scripts.

VENDOR

The name of the vendor who supplied the software package. 

VERSION

The version of this package.  

VSTOCK

The vendor-supplied stock number. 

For detailed information about the pkginfo command, refer to the pkginfo(1) man page.

ProcedureHow to Obtain Information With the pkginfo Command

  1. Install your package.

    See How to Install a Package on a Standalone System or Server, if needed.

  2. Display additional information about your package.


    # pkginfo [-x | -l] [pkg-abbrev]

    -x

    Displays package information in extracted format. 

    -l

    Displays package information in long format. 

    pkg-abbrev

    Is the name of a specific package. If omitted, the pkginfo command displays information about all installed packages, in the default format.

Where to Go Next

If you are ready to go to the next task, see How to Remove a Package.

Removing a Package

Because the pkgrm command updates information in the software products database, it is important when you remove a package to use the pkgrm command—even though you might be tempted to use the rm command instead. For example, you could use the rm command to remove a binary executable file, but that is not the same as using pkgrm to remove the software package that includes that binary executable. Using the rm command to remove a package's files will corrupt the software products database. (If you really only want to remove one file, you can use the removef command, which will update the software product database correctly.

ProcedureHow to Remove a Package

  1. Log in to the system as superuser.

  2. Remove an installed package.


    # pkgrm pkg-abbrev ...

    pkg-abbrev

    Is the name of one or more packages (separated by spaces). If omitted, pkgrm removes all available packages.

  3. Verify that the package has successfully been removed, use the pkginfo command.


    $ pkginfo | egrep pkg-abbrev
    

    If pkg-abbrev is installed, the pkginfo command returns a line of information about it. Otherwise, pkginfo returns the system prompt.

Transferring a Package to a Distribution Medium

The pkgtrans command moves packages and performs package format translations. You can use the pkgtrans command to perform the following translations for an installable package:

ProcedureHow to Transfer a Package to a Distribution Medium

  1. Build your package, creating a directory format package, if you have not already done so.

    For more information, see How to Build a Package.

  2. Install your package to verify that it installs correctly.

    See How to Install a Package on a Standalone System or Server, if needed.

  3. Verify your package's integrity.

    See How to Verify the Integrity of a Package, How to Obtain Information With the pkginfo Command, and How to Obtain Information With the pkgparam Command, if needed.

  4. Remove the installed package from the system.

    See How to Remove a Package, if needed.

  5. Transfer the package (in package format) to a distribution medium.

    To perform a basic translation, execute the following command:


    $ pkgtrans device1 device2 [pkg-abbrev...]

    device1

    Is the name of the device where the package currently resides. 

    device2

    Is the name of the device onto which the translated package will be written. 

    [pkg-abbrev]

    Is one or more package abbreviations. 

    If no package names are given, all packages residing in device1 are translated and written to device2.


    Note –

    If more than one instance of a package resides on device1, you must use an instance identifier for the package. For a description of a package identifier, see Defining a Package Instance. When an instance of the package being translated already exists on device2, the pkgtrans command does not perform the translation. You can use the -o option to tell the pkgtrans command to overwrite any existing instances on the destination device and the -n option to tell it to create a new instance if one already exists. Note that this check does not apply when device2 supports a datastream format.


Where to Go Next

At this point you have completed the steps necessary to design, build, verify, and transfer your package. If you are interested in looking at some case studies, see Chapter 5, Case Studies of Package Creation. If you are interested in advanced package design ideas, see Chapter 6, Advanced Techniques for Creating Packages.