Creating a Product Specification File (PSF)

SD-UX uses a Product Specification File (PSF) to define the physical product package. The PSF provides a “road map” that identifies the product according to its attributes, contents, compatibilities, dependencies and descriptions. The PSF drives the swpackage session. It describes how the product is structured and defines the attributes that apply to it.

SD-UX packages, distributes, installs files. The SD-UX packager uses these files after they have been built and installed into specific directory locations. These directory locations may reside in separate, unconnected directory trees or in the specific file locations needed to make the software run on your system. You can specify files by a root directory (gathering all files below it) or by explicit individual file paths. The file attributes can be taken from the files themselves, specified separately for each file, or specified for a set of files.

The PSF can:

Define vendor information (optional) for groups of products (including all products), or for individual products.
Specify one or more products (required).
For each product, define attributes for one or more subproducts (optional), filesets (required), and files (required).
Define attributes for the distribution depot/media (optional).
Specify what computer(s) and operating system(s) the product supports.
Define attributes that describe the software objects.

Product Specification File Examples

Minimal PSF

Here is an example of the minimum PSF, which includes only the required keywords. This PSF creates a product SD with fileset commands and contains one file, /usr/sbin/swcopy:

product
   tag   SD
fileset
  tag   commands
file    swcopy /usr/sbin/swcopy




	NOTE: You must use an absolute path for the second file term in this minimum format.

Typical PSF

Here is a sample PSF that describes the SD-UX product:

# PSF defining SD as a sample product.
depot
  layout_version 1.0
# Vendor definition:
vendor
  tag           HP
  title         Hewlett-Packard Company
  description   < data/description.hp
category
  tag            system_mgt
  title          Systems Management Applications
  description    These are the system management applications
  revision       1.0
end
# Product definition:
product
  tag            SD
  revision       A.01.00
  architecture   HP-UX_B.11_32/64
  vendor_tag     HP
  is_patch       false
  title          HP-UX Distributor
  number         B2000A
  category_tag   system_mgt
  description    < data/descr.sd
  copyright      < data/copyr.sd
  readme         < data/README.sd
  machine_type   *
  os_name        HP-UX
  os_release     ?.11.*
  os_version     ?
  directory      /
  is_locatable   false
# Specify a checkremove script that executes during the 
# swremove analysis phase. (This script prevents the
# removal of the SD product and returns an ERROR.
    checkremove     scripts/checkremove.sd
 
# Subproduct definitions:
  subproduct
    tag          Manager
    title        Management Utilities
    contents     commands agent data man
  end
  subproduct
    tag          Agent
    title        Agent component
    contents     agent data man
  end
 # Fileset definitions:
  fileset
    tag          commands
    title        Commands (management utilities)
    revision     2.42
    description  < data/descr.commands
 # Dependencies
    corequisites  SD.data
    corequisites SD.agent
 # Control files:
    configure    scripts/configure.commands
 # Files:
    directory    ./commands=/usr/sbin
    file         swinstall
    file         swcopy
# (...Other file definitions can go here...)
    directory    ./nls=/usr/lib/nls/C
    file         swinstall.cat
    file         swpackage.cat
 
    directory    ./ui=/var/adm/sw/ui
    file         *
# (...Other file definitions can go here...)
 end
 # Commands
 # (...Other fileset definitions can go here...)
 # Manpage fileset definitions:
 fileset
    tag          man
    title        Manual pages for the SD-UX
    revision     2.05
    directory    ./man/man1m=/usr/man/man1m.Z
    file         *
    directory    ./man/man4=/usr/man/man4.Z
    file         *
    directory    ./man/man5=/usr/man/man5.Z
    file         *
  end  
 #man
end
#SD

PSF Syntax

Each SD-UX object (product, subproduct, filesets, and file) has its own set of attributes and each attribute has a keyword that defines it. Most attributes are optional; they do not all need to be specified in the PSF. Each attribute has its own specific requirements, but the following rules apply:

Keyword syntax is:
keyword value
All keywords require one or more values, except as noted. If the keyword is there but the value is missing, a warning message is generated and the keyword is ignored.
Place comments on a line by themselves or after the keyword-value syntax. Comment lines are designated by preceding them with #.
Use quotes when defining a value (for example, description) that can span multiple lines. Quotes are not required when defining a single-line value that contains embedded whitespace.
Any errors encountered while reading the PSF cause swpackage to terminate. Errors are also logged to both stderr and the logfile.

PSF Object Syntax

The following tables and sections describe the PSF keywords, the allowable values for each keyword, and the syntax for the objects you can define in a PSF.

Keywords marked with a + apply to products only.
Keywords marked with a - apply to bundles only.
Keywords marked with a * are of the version_component type, as well as the type indicated in the table.

Table 10-2 Keywords Used in the Product Specification File

Keyword

Value

Max Size in bytes

Example

Distribution Class

distribution
 layout_version 
 tag 
 copyright
 description 
 number 
 title


revision_string
tag_string
multi_line_string
multi_line_string
one_line_string
one_line_string


1.0
EXAMPLE_DEPOT < data/copyr.depot
data/descr.depot 
B2358-13601
Example packages

Vendor Class

vendor
 tag 
 description
 title


tag_string
multi_line_string
one_line_string


64
8K
256


HP
<data/desc.hp
HP Company

Category Class

category
 tag 
 description 
 revision
 title


tag_string
multi_line_string
revision_string
one_line_string


patch_normal 
Normal problems
0.0
Category of Patches

Product Class

product or bundle
* tag
* architecture
  category_tag
- contents
 
  copyright
  description
  directory
  is_locatable
  is_patch
  machine_type
  number
  os_name
  os_release
  os_version
+ postkernel
+ readme
+ revision
+ share_link
  title
* vendor_tag


tag_string
one_line_string
one_line_string
repeatable list of 
software specs
multi_line_string
multi_line_string
path_string
boolean
boolean
uname_string
one_line_string
uname_string
uname_string
uname_string
path_string
multi_line_string
revision_string
one_line_string
one_line_string
tag_string


SD-UX 
HP-UX_B.11.11_32/64
Systems Management
pr.fs,r=1.0,a=,v=
 
<data/copyr.sd
<data/descr.sd
/
false
false
9000/800
B2000A
HP-UX
?.11.*
A
/usr/bin/kern_bld
<data/README.sd
A.01.00
 
Software Distributor 
HP

Subproduct Class

subproduct 
  tag
  contents
 
  description 
  title


tag_string
one-line list of tag
string values
multi_line_string
one_line_string


64
none
 
8K
256


Manager 
commands agent data man 
 
<data/desc.mgr
Management Utilities

Fileset Class

fileset 
* tag
  ancestor
 
  architecture
  category_tag
  corequisite
  description
  exrequisite
  is_kernel
  is_patch
  dynamic_module
  is_reboot
  is_sparse
  machine_type
  os_name
  os_release
  os_version
  prerequisite
* revision
  supersedes
  title


tag_string
repeatable list of
product.fileset
revision_string
tag_string
software_spec
multi_line_string
software_spec
boolean
boolean
one_line_string
boolean
boolean
uname_string
uname_string
uname_string
uname_string
software_spec
revision_string
software_spec
one_line_string


64
none
 
64
64
none
8K
none
9
9
256
9
64
64
64
64
64
none
64
none
256


commands
prod.oldfileset
 
HP-UX_B.11.11_32/64
patch_normal
SD-UX.man.r>=2.0
<data/descr.cmd
SD-UX.data,R>=2.1
false
false
ipf pfil
false
false-
9000/8*
HP-UX
?.11.*
A
SD-UX.agent,r>=2.0
2.42
product.fileset
SD-UX Commands

Class

control_files
 directory
 file_permissions
 file


path_mapping_string
permission_string
file_specification


none
none
none


./commands=/usr/sbin
-u 0222 -o root -g sys
-m 04555 bin/swinstall (or) *

Table 10-3 Control File Attributes

Keyword Type Size in Bytes Example

checkinstall
checkremove
configure
control_file
fix
postinstall
postremove
preinstall
preremove
request
unconfigure
unpreinstall
unpostinstall
verify

path_string
path_string
path_string
path_string
path_string
path_string
path_string
path_string
path_string
path_string
path_string
path_string
path_string
path_string

1K
1K
1K
1K
1K
1K
1K
1K
1K
1K
1K
1K
1K
1K

./scripts/checkinstall
./scripts/checkremove
./scripts/configure
./scripts/subscripts
./scripts/fix
./scripts/postinstall
./scripts/postremove
./scripts/preinstall
./scripts/preremove
./scripts/request
./scripts/unconfigure
./scripts/unpreinstall
./scripts/unpostinstall
./scripts/verify

Control Files

SD-UX supports execution of control files (also known as control scripts) at the product and fileset level. Control scripts let you perform additional checks and operations. The swinstall, swconfig, swverify, and swremove commands each execute one or more vendor supplied scripts. All scripts are optional but many times are needed correctly complete the task that you want your software package to perform. See Chapter 11: “Using Control Scripts ” for a complete discussion of control scripts.

Selecting the PSF Layout Version

You can select the layout version in the depot definition in the PSF (see “Product Specification File Semantics”) or with the layout_version option for swpackage, swmodify, swcopy, or swlist.

PSF syntax conforms to the layout_version=1.0 of the IEEE Standard 1387.2: Software Administration (POSIX). Previous versions of SD supported the POSIX layout_version=0.8 syntax, which continues to be supported.

Software depots cannot mix layout versions; they must be one or the other.

Differences between the two layout versions include the following:

The vendor specification is handled differently.
For the current standard (layout_version=1.0), each vendor class definition is associated only with subsequent products or bundles that contain a vendor_tag attribute that matches the tag attribute within the vendor class definition.
For the previous standard (layout_version=0.8) or if you do not specify a layout_version, products or bundles are automatically associated with the last vendor class you defined at the distribution level, or from a vendor that you define within the product or bundle. Explicitly defined vendor_tag attributes (with or without a value) take precedence.
The corequisites and prerequisites have singular titles for layout_version=0.8 (that is, corequisite and prerequisite). See “Dependency Specification” for more information.
Category objects and keywords are handled differently.
For layout_version=1.0 (current standard):
- category_tag is a valid product attribute that replaces the category and category_title attributes.
- you can define category class objects.
For layout_version=0.8 (previous standard):
- category and category_title are valid product attributes that replace the category_tag attribute.
- category class objects are not recognized.

For a more complete description of PSF requirements for layout_version=0.8, refer to the swpackage.4 manual page in a previous version of HP-UX.

PSF Value Types

With the exception of vendor-defined attributes (see “Vendor-Defined Attributes”), the values for each attribute keyword in your PSF must match one of the specific types discussed below.




	NOTE: PSF syntax conforms to the `layout_version=1.0` of the POSIX 1387.2 Software Administration standard. Previous versions of SD-UX supported the POSIX `layout_version=0.8` syntax, which continues to be supported. See “Selecting the PSF Layout Version ” for more information.

boolean

Maximum length: 9 bytes
One of the values true or false.
Examples: true, false

file_specification

Maximum length: none
Explicitly specifies a file or directory to be packaged, using the format:
[-m mode] [-o [owner[,]] [uid]] [-g [group[,]][gid]] [-v][source] [destination]
The source and destination can be paths relative to source and destination directories specified in the path_mapping_string.
You can also use * to include all files below the source directory specified by a directory keyword.
Examples: -m 04555 sbin/swinstall or * (to denote all files and directories)

multi_line_string

Maximum length: 8 kbyte (1Mbyte for a readme file)
Each multi-line strings support all isascii characters. (Refer to the ctype(3) manpage.) It represent one or more paragraphs of text. It can be specified in-line, surrounded by double-quotes or read from a files.
File entries must use this syntax:
< filename
Example: </mfg/sd/description

one_line_string

Maximum length: 256 bytes
One-line strings support a subset of isascii characters only. (Refer to the ctype(3) manpage.)
No isspace characters, except for space and tab, are allowed.
Examples: Hewlett-Packard Company

path_mapping_string

Maximum length: none
A value of the form: source[=destination] where the source defines the directory in which subsequently defined files are located. The optional destination maps the source to a destination directory in which the files will actually be installed.
Examples:/mfg/sd/files/usr = /usr

path_string

Maximum length: 255 bytes for tapes, 1024 bytes for depots
An absolute or relative path to a file. Many attributes of this type are restricted to 255 bytes in length. This restriction is due to the tar(1) command, which requires a file’s basename(1) be <= 100 bytes, and a file’s dirname(1) to be <= 155 bytes. (Some implementations of tar enforce < and not <=.)
Examples: /usr /mfg/sd/scripts/configure

permission_string

Maximum length: none
A value of the form:
[-m mode|-u umask] [-o [owner[,]][uid]] [-g [group[,]][gid]]
where each component defines a default permissions value for each file and directory defined in a fileset. The default values can be overridden in each file’s specific definition. The owner and group fields are of type tag_string. The uid and gid fields are of type unsigned integer. The mode and umask are unsigned integers, but only supports the octal character set, 0-7.
SD-UX will not override existing permissions based on this attribute if a file already exists on a target.
Examples: -u 0222 -o root -g sys

revision_string

Maximum length: 64 bytes
Revision strings contain zero or more dot-separated one_line_string (above).
Examples: 2.0, B.11.00

software_specification

Maximum length: none
Software specifications are used to specify software in dependencies, ancestors and other attributes, as well as command line selections. This attribute uses the standard syntax for SD-UX software_selections. See “Software Selections” for complete information.
Examples: SD.agent or SD,r=2.0,a=HP-UX_B.11.00_32

tag_string

Maximum length: 64 bytes
Tag strings support a subset of isascii() characters only:
- Requires one or more characters from: “A-Z”, “a-z”, “0-9”, including the first character.
- The isspace() characters are not allowed.
- SDU metacharacters not allowed: . , : =
- Shell metacharacters not allowed: # ; & () {} | < >
- Shell quoting characters not allowed: “ ‘ ’ \
- Directory path character (/) not allowed.
Examples: HP, SD-UX

uname_string

Maximum length: 64 bytes
Uname strings containing a subset of isascii() characters only.
No isspace() characters are allowed.
Shell pattern matching notation allowed: [ ] * ? !
Patterns can be “ORed” together using the separator: |
Examples: 9000/7*:*|9000/8*:*, HP-UX, ?.11.*

Product Specification File Semantics

The following sections describe how to specify a PSF and defines keywords.

Vendor-Defined Attributes

You can create your own software attributes when packaging software.

Vendor-defined attributes are noted during packaging or when modified with swmodify. You can list these attributes with swlist.

When SD-UX encounters a keyword in a PSF that is not one of the standard keywords, the keyword and its associated values are preserved by being transferred to the INDEX or INFO files created by swpackage.

Nonstandard keywords are defined as a filename character string. The value associated with a keyword is processed as an attribute_value. It can be continued across multiple input lines or can reference a file containing the value for the keyword.




	CAUTION: If you misspell a standard keyword, SD-UX may mistake the keyword for a vendor-defined attribute, which may lead to packaging errors.

Distribution (Depot) Specification

Distribution attributes let you list information about the media that will hold the depot (either tapes or CD/directory.) See “Depot Management Commands and Concepts” for more information about depots. Here is a PSF for a distribution:

distribution
  layout_version       1.0
  tag                  APPLICATIONS_CD
  copyright            < data/copyright.cd
  description          <data/description.cd
  number               B1234-56789
  title                HP-UX Applications Software Disk
# Optional vendor specification can be included.
# AT LEAST ONE PRODUCT SPECIFICATION MUST BE INCLUDED.
# Other product specifications are optional.
end

The distribution keyword is always required. All other attributes are optional.

distribution or depot: Keyword that begins the distribution specification. Each keyword defines an attribute of the distribution depot or tape itself. All keywords are optional, even if a distribution specification is included in a PSF.
layout_version: PSF syntax conforms to the layout_version=1.0 of the POSIX 1387.2 Software Administration standard. Previous versions of SD-UX supported the POSIX layout_version=0.8 syntax, which continues to be supported. (You can also select the layout version with the layout_version option for swpackage, swmodify, swcopy, or swlist.) See “Selecting the PSF Layout Version ” for more information.
tag: The short name of the target depot (tape) being created/modified by swpackage.
copyright: The text (or a pointer to a filename) for the copyright information for the depot’s contents.
description: The description of the target depot; either the text itself or a pointer to a filename that contains the text.
number: The part or manufacturing number of the distribution media (CD or tape depot).
title: The full name of the target depot (tape) being created/modified by swpackage.
end: Ends the distribution specification, no value is required. This keyword is optional. If you use it and it is incorrectly placed, the specification will fail.

Vendor Specification

The vendor attributes let you add a description to the PSF.

The layout_version defined for the PSF file determines how vendor specifications are associated with products and bundles. If a layout_version is not defined or is defined as 1.0, vendor specifications will be associated with all subsequent products and bundles that define a matching vendor_tag attribute.

If a layout_version of 0.8 is specified, all subsequent products and bundles will automatically be assigned to a vendor_tag from the last vendor object defined at the distribution level, if any, or from a vendor object defined within a product or bundle, unless a vendor_tag is explicitly defined.

The following is an example of a vendor specification:

vendor
 tag          HP
 description  < data/description.hp
 title        Hewlett-Packard Company
end

Each keyword defines an attribute of a vendor object. If a vendor specification is included in the PSF, swpackage requires the vendor and tag keywords.




	NOTE: The vendor specification is not the same as vendor-defined attributes. See “Vendor-Defined Attributes” for more information.

vendor: Keyword that begins the vendor specification.
tag: Defines the identifier (short name) for the vendor.
title: Defines the full name (one line description) for the vendor.
description: Defines the multi-paragraph description of the vendor; the value is either the text itself (within double-quotes) or a pointer to the filename containing the text.
end: Ends the vendor specification. This keyword is optional.

Category Specification

(Does not apply to layout version 0.8.) A software collection can contain a list of category objects that are used as a selection mechanism. Category objects are identified by the keyword “category” and contain additional information about the category. The category_tag attribute points to a particular category object and can appear anywhere within a product, bundle, subproduct, or fileset.

All software objects with the attribute of is_patch set to true are automatically assigned a category of “patch.”




	NOTE: The `layout_version` keyword in the `distribution class` affects how categories are associated with products and bundles. See “Selecting the PSF Layout Version ” and “Product Specification File Semantics” for more information.

The category specification looks like this:

category
   tag          patch_normal
   title        Category of patches
   description  For normal problems
   revision     0.0
end

Each keyword defines an attribute of the category object. If a category specification is included in the PSF, swpackage requires only the category and tag keywords.

category: Keyword that begins the category specification.
tag: The category short name identifier. Associates this object with a product or bundle. This tag attribute must match the category_tag attribute in the product or bundle.
title: A one-line string that defines the full name for the category.
description: A multi-line description of the category. The description value can consist of text or a filename for a text file.
revision: The revision information (release number, version). Determines which category object definition to maintain in a depot when a definition being installed or copied does not match a definition already in the depot with the same category tag.
end: An optional keyword that ends the specification. No value is required. If you place this keyword incorrectly in the PSF, the specification will fail.

Product or Bundle Specification

The product specification is a required class in the PSF. It lets you identify the product you are packaging.




	NOTE: The `layout_version` keyword in the `distribution class` affects how category and vendor objects are associated with products and bundles. See “Selecting the PSF Layout Version ” and “Product Specification File Semantics” for more information.

The product specification looks like this:

product
tag            SD
architecture   HP-UX_B.11.00_32/64
category_tag   systems_management
contents       prod.fsl,r=1.0,a=,v=
copyright      </mfg/sd/data/copyright
description    </mfg/sd/data/description
directory      /usr
is_locatable   false
is_patch       false
machine_type   *
number         J2326AA
os_name        HP-UX
os_release     ?.11.00.*
os_version     B.11.**
postkernel     /usr/lbin/kernel_build
+ readme       </mfg/sd/data/README
revision       2.0
title          Software Distributor
vendor_tag     HP
 
# Optional vendor specification
# Optional subproduct specification
# REQUIRED FILESET SPECIFICATION
 
end

For each product object specified, swpackage requires only the product and tag keywords, plus one or more fileset definitions. For each bundle specified, swpackage requires the bundle, tag and contents keywords.

product

Required keyword that begins the product specification.

tag

The product’s identifier (short name).

architecture

The target system on which the product or bundle will run. Provides a human-readable summary of the four uname attributes (machine_type, os_name, os_release and os_version), which define the exact target system(s) the product supports.

bundle

Required keyword that begins the bundle specification.

category_tag

A repeatable tag-based attribute identifying a set of categories of which the software object is a member. This is used as a selection mechanism and can be used independent of patches. The default value is an empty list or patch if the is_patch attribute is set to true. Like vendor_tag, this attribute can be used as a pointer to a category object that contains additional information about the category (for example, a one-line title definition and a description of the category).




	NOTE: The category tag `patch` is reserved. When the `is_patch` product attribute is set to true, a built-in `category_tag` attribute of value `patch` is automatically included with the product definition.

contents

The list of fully qualified (all version distinguishing attributes included) software specs for the bundle.

copyright

A multi-line description of the product’s copyright; either the text itself (in double quotes) or a pointer to the filename that contains the text.

description

A multi-paragraph description of the product; either the text itself (within double-quotes) or a pointer to the filename that contains the text.

directory

The default, absolute pathname to the directory in which the product’s files will be installed (the root directory of the product). If not specified, swpackage assigns a value of /.

is_locatable

Defines whether a product or bundle can be installed to any product directory, or whether it must be installed into a specific directory. The attribute can be set to true or false. If not defined, swpackage sets the default attribute to “false.”

is_patch

A boolean flag that identifies a software object as a patch. The default value is false. When set to true, a built-in category_tag attribute of value patch is automatically included with the product definition.

machine_type

The system type on which the product will run. If not specified, the keyword is assigned a wildcard value of *, meaning it will run on all machines. If there are multiple platforms, you must separate each machine designation with a | (vertical bar). For example, a keyword value of 9000/7*|9000/8* means the product will run on all HP Series 9000 Model 7XX or all HP 9000 Series 8XX machines. Alternatively, the value 9000/[78]* would also work.

Other examples:

* (If not concerned with the machine type.)

9000/7??:32* (Series 700, 32-bit capable hardware required)

*:*64 (64-bit capable hardware required)

*:32: (32-bit capable hardware required)

9000/7??:*64 (Series 700, 64-bit capable hardware required)

9000/[78]??:32* (Series 800, 32-bit capable hardware required)

9000/[78]??:*64 (Series 800, 64-bit capable hardware required)

The value is matched against a target’s uname -m or getconf _CS_HW_CPU_SUPP_BITS result.

number

The part or order number of the product.

os_name

The operating system name on which the product will run. If not specified, the attribute is assigned a value of *, meaning it will run on all operating systems. If there are multiple operating systems, use wildcards or the | symbol to separate them. The value is matched against a target’s uname -s or getconf _CS_KERNEL_BITS result.

os_release

The release number of the product’s operating system. If not specified, the attribute is assigned a value of *, meaning it will run on all operating systems. If there are multiple operating systems, use wildcards or the | symbol to separate them. The value is matched against a target’s uname -r result.

os_version

The version number of the operating system(s) on which the product will run. If not specified, the attribute is assigned a value of *, meaning it runs on any version. If there are multiple operating systems, use wildcards or the | symbol to separate them. The value is matched against a target’s uname -v result.

postkernel

Defines a kernel build script to be executed when kernel filesets are loaded. Kernel filesets have the is_kernel attribute set to true. The default kernel script is /usr/sbin/mk_kernel. (See the manual reference page for mk_kernel(1M) for more information.) The default script executes when the postkernel attribute is not specified. Only one kernel build script is allowed per product, and the script executes only once, even if defined for multiple filesets.

readme

A text file of the README information for the product. The value must be a pointer to the filename containing the text

revision

The revision information (release number, version) for the product or bundle.

title

A one-line string that further identifies the product or bundle.

vendor_tag

Associates this product or bundle with a vendor object defined separately in the PSF, if that object has a matching tag attribute.

end

Ends the product or bundle specification. No value is required. This keyword is optional. If you use it and it is incorrectly placed, the specification will fail.

Control Script Specification

SD-UX supports execution of product and fileset control scripts that allow you to perform additional checks and operations with other HP-UX commands and functions. The swask, swinstall, swconfig, swverify, and swremove commands each can execute one or more control scripts on the primary roots. All scripts are optional but many times are needed correctly complete the task that you want your software package to perform. See Chapter 11: “Using Control Scripts ” for a complete discussion of control scripts.

Subproduct Specification

The subproduct specification lets you group filesets within a larger product specification. Subproducts are optional. A subproduct specification looks like this:

subproduct
  tag          Manager
  contents     manager agent packager man doc
  description  </mfg/sd/data/manager/description
  title        SD Management Interfaces Subset
end

Each keyword defines an attribute of a subproduct object. If a subproduct object is specified, swpackage requires the subproduct, tag, and contents keywords.

subproduct

Keyword that begins a subproduct specification.

tag

The subproduct’s identifier (short name).

contents

A whitespace-separated list of the subproduct’s fileset tag values (that is, contents fileset1 fileset2 fileset3 ...filesetN).

In the PSF, fileset definitions are not contained within subproduct definitions. The contents keyword is used to assign filesets to subproducts. This linkage allows a fileset to be contained in multiple subproducts.

description

A multi-line description of the subproduct; either the text itself (within double-quotes), or a pointer to the filename that contains the text.

title

A one-line string that further identifies the subproduct.

end

Ends the subproduct specification. No value is required. This keyword is optional. If you use it and it is incorrectly placed, the specification will fail.

Fileset Specification

The fileset specification is required in the PSF. Use filesets to group files together.

A fileset specification looks like this:

fileset
   tag            manB
   ancestor       OLDSD.MAN
   architecture   HP-UX_B.11.00_32/64
   category_tag   manpg
   description    </mfg/sd/data/man/description
   is_kernel      false
   is_locatable   false
   is_patch       false
   is_reboot      false
   is_sparse      false
   machine_type   *
   os_name        HP-UX
   os_release     ?.11.00.*
   os_version     ?
   revision       2.40
   supersedes     product.fileset,fr=revision
   title          Commands (management utilities)
# Optional control script specification
# Optional dependency specification
# REQUIRED FILE SPECIFICATION
# Additional file specifications optional.
end

Each keyword defines an attribute as a fileset object. For each fileset object specified, swpackage requires the fileset and tag keywords, plus zero or more file specifications.

tag

The fileset identifier (short name).

architecture

Describes the target system(s) on which the fileset will run if filesets for multiple architecture are included in a single product. Provides a human-readable summary of the four uname(1) attributes which define the exact target system(s) the product supports. Many filesets do not include an architecture; only a product architecture need be defined.

ancestor

A list of filesets that will match the current fileset when installed on a target system, if the match_target installation option is specified. Also designates an ancestor fileset to check for when patch_match_target is defined.

category_tag

A repeatable tag-based attribute identifying a set of categories of which the software object is a member. This is used as a selection mechanism and can be used independent of patches. The default value is an empty list or patch if the is_patch attribute is set to true.Like vendor_tag, this attribute can be used as a pointer to a category object that contains additional information about the category (for example, a one-line title definition and a description of the category).




	NOTE: The category tag `patch` is reserved. When the `is_patch` file attribute is set to true, a built-in `category_tag` attribute of value `patch` is automatically included with the file definition.

description

Defines the multi-paragraph description of the fileset; the value is either the text itself (within double-quotes) or a pointer to the filename containing the text.

is_kernel

A value of true defines the fileset as being a contributor to the operating system kernel; the target system(s) kernel build process will be invoked after the fileset is installed. If this attribute is not specified, swpackage assumes a default value of false.

is_locatable

Defines whether a fileset can be installed to any product directory, or whether it must be installed into a specific directory. The attribute can be set to true or false. If not defined, swpackage sets the default attribute to false.

is_patch

Identifies a software object as a patch. The default value is false. When set to true, a built-in category_tag attribute of value patch is automatically included.

dynamic_module

A space-separated list of strings specifies the list of dynamically loadable kernel modules (DLKMs) packaged into the fileset. The dynamic modules themselves must be delivered to /usr/conf/mod/. If the dynamic_module attribute is omitted, no DLKMs may be delivered in the fileset.

When a dynamic module is packaged, it is customary to include a call to the control_util mod_systemfile in a postinstall script to link the module to the kernel. If a state of static is specified in the mod_sytemfile call, the attributes is_kernel and is_rebootmust also be set to true. In addition, if a system reboot is needed to activate the module, the is_reboot attribute must be set to true.

is_reboot

A value of true declares that the fileset requires a system reboot after installation. If this attribute is not specified, swpackage assumes a default value of false.

is_sparse

Indicates that a fileset contains only a subset of files in the base (ancestor) fileset and that the contents are to be merged with the base fileset. The default value is false. If the is_patch attribute is true, is_sparse is also set to true for the fileset, although it can be forced to false.

machine_type

The machine type on which the product will run. If not specified, the keyword is assigned a wildcard value of *, meaning it will run on all machines. If there are multiple machine platforms, you must separate each machine designation with a | (vertical bar). For example, a keyword value of 9000/7*|9000/8* means the product will run on all HP Series 9000 Model 7XX or all HP 9000 Series 8XX machines. Alternatively, the value 9000/[78]* would also work.

Other examples:

*: If not concerned with the machine type.
9000/7??:32*: Series 700, 32-bit capable hardware required.
*:*64: 64-bit capable hardware required.
*:32:: 32-bit capable hardware required.
9000/7??:*64: Series 700, 64-bit capable hardware required.
9000/[78]??:32*: Series 800, 32-bit capable hardware required.
9000/[78]??:*64: Series 800, 64-bit capable hardware required.

The value is matched against a target’s uname -m or getconf _CS_HW_CPU_SUPP_BITS result.

os_name

Defines the operating system(s) on which the files will run if a fileset architecture has been defined. (If not specified, swpackage assigns a value of *, meaning the files run on all operating systems.) If there are multiple operating systems, use wildcards or use the ’|’ character to separate them. This attribute should pattern match to the value of uname -s or getconf KERNEL_BITS on the supported target systems.

os_release

Defines the operating system release(s) on which the files will run. (If not specified, swpackage assigns a value of *, meaning the files run on all releases.) If there are multiple operating system releases, use wildcards or use the ’|’ character to separate them. This attribute should pattern match to the value of uname -r on the supported target system(s).

os_version

revision

Defines the revision (release number, version number) of the fileset.

supersedes

Used when a patch is replaced by (or merged into) a later patch. The attribute indicates which previous patches are replaced by the patch being installed or copied. This attribute value is a list of software specifications of other patches that this patch supersedes.

title

Defines the full name (one-line description) of the fileset.

end

Optional keyword to end the fileset specification. No value is required. If you place this keyword incorrectly, the file specification will fail.

Dependency Specification

The swinstall, swcopy, swverify, and swremove commands recognize software dependencies. The default behavior for swinstall, for example, prevents an install unless all dependencies are met.

The PSF specifies dependencies between filesets. Dependencies are defined within the fileset class definition. (See “Fileset Specification”.)

You can also define dependencies between:

A fileset and another product (namely, a subset of that product).
A particular fileset within that product.
The entire product.

SD-UX supports these types of dependencies:

Corequisite

Software that must be present for a fileset to operate correctly. For example, specifying a corequisite for an install fileset means that the corequisite must be installed or being installed when the fileset itself is installed.

(Note that a corequisite dependency does not imply any “run-time dependency” (load order).)

Exrerequisite

Software that may not be present when the fileset is operated on by SD-UX. For example, specifying an exrequisite for a fileset prevents the fileset from being installed if any of the specified exrequisite software objects are installed or are being installed.

Prerequisite

Software that must be installed and/or configured correctly before a fileset can be operated on by SD-UX. Prerequisites control the order of an installation with swinstall (install-time dependency).

Dependencies are specified as a software_specification value type within the PSF. (See “PSF Value Types ” for more information.) For example:

   corequisites   SD.data
   prerequisites  productA,r>=2.1
   exrequisites   productB,r>=2.1




	NOTE: A dependency must always be specified using a software specification that starts with the product tag for the requisite software.

You can specify multiple dependencies to define AND relationships between the dependencies (AND meaning that all dependencies must be satisfied).

You can also define OR relationships using the or (|) character. The following rules apply:

White spaces are allowed around the OR character.
OR dependencies are resolved from left to right.

Here is an example:

corequisite  P.F
prerequisite ProdA | ProdB | ProdC.F | ProdC.FS
corequisite  ProdX | ProdY | ProdZ | ProdW.FS

Control Script Specification

SD-UX supports execution of product and fileset control scripts that allow you to perform additional checks and operations with other HP-UX commands and functions. The swask, swinstall, swconfig, swverify, and swremove commands each can execute one or more control scripts on the primary roots. You can write the scripts and include them in your software package. All scripts are optional but often are needed correctly complete the task that you want your software package to perform. See Chapter 11: “Using Control Scripts ” for a complete discussion of control scripts.

File Specification

Within a fileset specification, you can specify the following file types to be packaged into the fileset by swpackage:

control script
directory
hard link
regular file
symbolic link
archive

swpackage generates an error if the PSF contains an unrecognized or unpackageable file type.

The swpackage command supports specific mechanisms for specifying the files contained in a fileset:

default permission specification: For all or some of the files in the fileset, you can define a default set of permissions.
directory mapping: You can point swpackage at a source directory in which the fileset’s files are located. In addition, you can map this source directory to the appropriate (destination) directory in which this subset of the product’s files will be located.
explicit file specification: For all or some of the files in the fileset, you can name each source file and destination location.
recursive (implicit) file specification: If directory mapping is active, you can simply tell swpackage to recursively include all files in the directory into the fileset.
PSF extensions: You can use include and exclude files to extend file definitions.

These mechanisms can all be used in combination with the others.

Default Permission Specifications

By default, a destination file will inherit the mode, owner, and group of the source file. You can use the file_permissions keyword to set a default permission mask, owner, and group for all the files being packaged into the fileset:

file_permissions [-m mode| -u umask] [-o [owner[,]] [uid]] [-g [group[,]][gid]][-t type]

file_permissions

This keyword applies only to the fileset in which it is defined. You can specify multiple file_permissions; later definitions replace previous definitions.

-m mode

This option defines a default (octal) mode for all files.

-u umask

Instead of specifying an octal mode as the default, you can specify an octal umask (1) value that gets “subtracted” from an existing source file’s mode to generate the mode of the destination file.

By specifying a umask, you can set a default mode for executable files, non-executable files, and directories. (A specific mode can be set for any file using -m.)

-o [owner[,]][uid]

This option defines the destination file’s owner name and/or or uid. See the discussion of the -o option in “Explicit File Specification ” for more information.

-g [group[,]][gid]

This option defines the destination file’s group name and/or or gid. See the discussion of the -g option in “Explicit File Specification ” for more information.

-t type

Defines files that need not exist before packaging.

The following examples illustrate the use of the file_permission keyword.

Set a read only 444 mode for all file objects (requires override for every executable file and directory):
file_permissions -m 444
Set a read mode for non-executable files, and a read/execute mode for executable files and directories:
file_permissions -u 222
Set the same mode defaults, plus an owner and group:
file_permissions -u 222 -o bin -g bin
Set the same mode defaults, plus a uid and gid:
file_permissions -u 222 -o 2 -g 2
Set the owner write permission in addition to the above:
file_permissions -u 022 -o 2 -g 2
If you do not define file_permissions, swpackage uses the default value file_permissions -u 000 for destination file objects based on existing source files. (Meaning the mode, owner/uid, group/gid are set based on the source file, unless specific overrides are specified for a destination file.)

Directory Mapping

(Optional) The directory source [= destination] specification defines the source directory under which subsequently listed files are located. In addition, you can map the source directory to a destination directory under which the packaged files will be installed.

For example, the definition:

directory /build/hpux/mfg/usr = /usr

causes files from the /build/hpux/mfg/ directory to have the prefix /usr/sbin when installed. The destination directory must be a superset of the product’s directory attribute, if defined in the product specification. If the product’s directory is defined, and the destination is not a superset, swpackage generates an error.

The destination directory must be an absolute pathname. If not, then swpackage generates an error.

The source directory can be either an absolute pathname, or a relative pathname. If relative, swpackage interprets it relative to the current working directory in which the command was invoked.

If the source directory does not exist, swpackage generates an error.

Explicit File Specification

You can explicitly specify the files to be packaged into a fileset. If you want to recursively include all files and directories, use the recursive file specification (file *).

You can use the directory keyword to define a source (and destination) for explicitly specified files. If no directory keyword is active, then the full source path and the absolute destination path must be specified for each file. An explicit file specification overrides or adds to, on a file-by-file basis, the specifications set by the directory and/or file_permissions keywords.

An explicit file specification uses this form:

file [-v] [-m mode] [-o [owner[,]][uid]] [-g [group[,]][gid]] 
[-t type] [source] [destination]

file

This keyword specifies an existing file (usually within the currently active source directory) to include in the fileset.

source

This value defines the path to a file you want to include in the package.

If this is a relative path, swpackage will search for it relative to the source directory set by the directory keyword. If no source directory is active, swpackage will search for it relative to the current working directory in which the command was invoked.

All attributes for the destination file object are taken from the source file, unless a file_permission keyword is active, or the -m, -o, or -g options are also included in the file specification.

destination

This value defines the destination path at which the file will be installed. If destination is a relative path, the active destination directory set by the directory keyword will be prefixed to it. If it is a relative path, and no destination directory is active, swpackage generates an error. If the destination is not specified, then the source path is used as the destination, with the appropriate mapping done with the active destination directory (if any).

-m mode

This option defines the (octal) mode for a file or directory at its destination.

-o [owner[,]][uid]

This option defines the file’s owner name and/or uid at its destination. If only the owner is specified, then the owner and uid attributes are set for the destination file based on the packaging host’s /etc/owner. If only the uid is specified, it is set as the destination’s uid attribute and no owner name is assigned. If both are specified, each sets the corresponding attribute for the file object.

On systems that support numeric usernames, to specify a numeric username for owner, both the numeric username and the uid must be supplied. If a numeric username alone is specified, it is interpreted as a uid.

During an installation, the owner attribute is used to set the owner name and uid, unless the owner name is not specified or is not defined in the target system’s /etc/passwd file. In this case, the uid attribute is used to set the uid.

-g [group[,]][gid]

This option defines the file’s group name and/or gid at its destination. If only the group is specified, then the group and gid attributes are set for the destination file based on the packaging host’s /etc/group. If only the gid specified, it is set as the destination’s gid attribute and no group name is assigned. If both are specified, each sets the corresponding attribute for the file object.

On systems that support numeric groupnames, to specify a numeric groupname, both the numeric groupname and the gid must be supplied. If a numeric groupname alone is specified, it is interpreted as a gid.

During an installation, the group attribute is used to set the group name and gid, unless the group name is not specified or is not defined in the Target system’s /etc/group. In this case, the gid attribute is used to set the gid.

-t type

Defines a file of type d (directory), s (symbolic), h (hard link), or a (archive) for files that need not exist before packaging.

-v

This option marks the file as volatile, meaning it can be modified (that is, deleted) after it is installed without impacting the fileset.

Files that may have their attributes (size, last modified time, etc.) changed through normal use after they are installed should be specified in the PSF file as volatile (by specifying -v on the line defining the file). swverify will not, by default, check file attributes for files that have the is_volatile attribute set to true (see the check_volatile option for swverify).

Error Messages

When processing existing files in a source directory, swpackage identifies the following four kinds of errors:

Cannot search directory (permission denied)
Cannot read the file (permission denied)
Unsupported file type encountered (source file must be a control script, regular file, directory, hard link or symbolic link)
File does not exist

Using Directory and File Keywords

The following examples illustrate the use of the directory and file keywords.

Include all files under /build/hpux/mfg to be rooted under /usr:
directory /build/hpux/mfg=/usr file *

Include only certain files under /build/hpux/mfg/, to be rooted under /usr and /var/adm/sw:

directory /build/hpux/mfg=/usr
file      sbin/swinstall
file      sbin/swcopy
. . .
directory /build/hpux/mfg=/var/adm/sw
file      nls/swinstall.cat  nls/en_US.88591/swinstall.cat
file      defaults newconfig/defaults
file      defaults defaults

Explicitly list files, no directory mapping specified:

file  /build/hpux/mfg/usr/bin/swinstall /usr/sbin/swinstall
file  /build/hpux/mfg/usr/bin/swcopy /usr/sbin/swcopy
file  /build/hpux/mfg/data/nls/swinstall.cat
      /var/adm/sw/nls/en_US.88591/swinstall.cat
file  /build/hpux/mfg/data/defaults 
      /var/adm/sw/newconfig/defaults
file  /build/hpux/mfg/data/defaults /var/adm/sw/defaults

Use all specification types to include files:

directory /build/hpux/mfg/usr=/usr
file      *
directory /build/hpux/mfg/data=/var/adm/sw
file     defaults  newconfig/defaults
file     /build/hpux/mfg/data/defaults=/var/adm/sw/defaults

Recursive File Specification

The file * keyword directs swpackage to include every file (and directory) within the current source directory in the fileset. swpackage attempts to include the entire, recursive contents of the source directory in the fileset. (Partial wildcarding is not supported, e.g. file dm* to indicate all files starting with “dm”.)

All attributes for the destination file object are taken from the source file, unless a file_permission keyword is active (this keyword is described below).

The user can specify multiple

directory  source[=destination]
file       *

pairs to gather all files from different source directories into a single fileset.

If you do not want to recursively include all files and directories, use the explicit file specification.

The directory keyword must have been previously specified before the file * specification can be used. If not, swpackage generates an error.

Error Messages

When processing the directory recursively, swpackage encounters the following errors:

Cannot search directory (permission denied)
Cannot read the file (permission denied)
Unsupported file type encountered

PSF Extensions

A PSF can contain extended file definitions. SD currently supports exclude and include files.

Exclude files let you explicitly exclude files that would otherwise be included in the PSF. The syntax is:

exclude filename

An exclude file can only be specified after a file definition. The file listed after the exclude keyword is excluded from the current context (for example, from a recursive file definition or wildcard).

If the filename specifies a directory, then all files below that directory are excluded.

Include files let you include file definitions from a separate file. The syntax is:

file < filename

The include file must be separated from the file keyword by a less than sign (<).

Re-Specifying Files

In addition to being able to specify files as a group (with file *) for general attributes, the PSF also allows you to “re-specify” files within that definition to modify individual attributes.

For example, suppose you wanted to specify all the files in a fileset which contained 100 files. All these files were to be recursively “discovered” and packaged into the fileset. Most of them would have the same owner, group, and mode (and other file attributes).

Out of those 100 files, there might be five that are volatile (that is, you don’t care if they get modified or deleted). So, instead of listing all 100 files individually, and using the -v option for the five, you could specify all 100 with file * and then modify the five individually in their own way. For example, with files 1, 2, 3, 4, and 5:

directory source = /product file *
 
   file -v 1
   file -v 2
   file -v 3
   file -v 4
   file -v 5

This also works well for permissions. For example, assume that nearly all the 100 files in the preceding example had the same permission attributes, but files 1, 2, and 3 required a different owner and mode:

directory  source = /product
 
   file_permissions -o bin -g bin -m 555
   file *
 
   file_permissions -o root -g other -m -04555
   file 1
   file 2
   file 3

This capability combines the recursive file specifications function with explicit file specification. (See “Explicit File Specification ”).

Creating a Product Specification File (PSF)

Technical documentation

» Table of Contents

» Glossary

» Index

Product Specification File Examples

Minimal PSF

Typical PSF

PSF Syntax

PSF Object Syntax

Control Files

Selecting the PSF Layout Version

PSF Value Types

Product Specification File Semantics

Vendor-Defined Attributes

Distribution (Depot) Specification

Vendor Specification

Category Specification

Product or Bundle Specification

Control Script Specification

Subproduct Specification

Fileset Specification

Dependency Specification

Control Script Specification

File Specification

Default Permission Specifications

Directory Mapping

Explicit File Specification

Recursive File Specification

PSF Extensions

Re-Specifying Files