This section describes the software packaging layout. The software packaging layout consists of:
This ordering of directories and files also applies to distributions on a set of hierarchical file systems which span multiple media.
Thus, two distinct (but related) formats for the software packaging layout are supported by this Software Administration specification:
A conformant implementation does not contain any other files or directories besides those explicitly entered in the distribution catalog. However, it can contain other files and directories besides those belonging to the distribution.
This Software Administration specification defines a single directory structure for directory and serial distributions. The software packaging layout can be stored in two forms:
The same structure offers optimal load performance for serial distributions while providing a simple structure for directory distributions. This structure applies to each media if the distribution spans multiple media.
The structure supports multiple versions of a product contained within a single distribution, where versions are distinguished by a unique combination the product tag, revision, architecture, and vendor_tag attributes.
|Directory or File||Purpose|
|path/catalog/||Contains all information about the distributions contents|
|path/catalog/INDEX||Global index of distribution and its contents|
|path/catalog/dfiles/||Contains distribution attributes stored in files|
|path/catalog/product1/||Storage for information on the first product|
|path/catalog/product1/pfiles||Contains all product attributes stored in files|
|path/catalog/product1/pfiles/INFO||Control_file information for this product|
|path/catalog/product1/pfiles/script||Vendor defined control_files|
|path/catalog/product1/fileset1||Storage for information and scripts on this fileset|
|path/catalog/product1/fileset1/INFO||File and control_file information for this fileset|
|path/catalog/product1/fileset1/scripts||Vendor defined control_files|
|path/catalog/product1/fileset2/||Storage for information and scripts on the next fileset|
|path/catalog/product2/||Storage for information on the next product|
|path/product1/||Storage for this product's filesets|
|path/product1/fileset1/||Storage for this filesets files|
|path/product1/fileset1/files||Actual directory structure of files|
|path/product1/fileset2/||Storage for next fileset's files|
|path/product1/fileset2/files||Actual directory structure of files|
|path/product2/||Storage for next product's filesets|
The directory structure for the software packaging layout is divided into two areas:
This INDEX file contains the definition of all software objects in the distribution.
A distribution attribute can be stored as a separate file, the file name of which can be the name of the attribute.
A product attribute can be stored as a separate file, the file
name of which can be the name of the attribute.
Contains the definitions for the control_file objects contained within the product.
The vendor-supplied control scripts for the product.
All other vendor-defined control_files for this product.
A fileset attribute can be stored as a separate file, the filename of which can be the name of the attribute.
The vendor-supplied control scripts for the fileset.
All other vendor-defined control_files for this fileset.
The files of each fileset are store in a directory with the name <fileset_control_directory> which is itself in a directory called <product_control_directory>.
Each regular file (ones for which file.type is f) is stored in a location defined by appending the file.path attribute to the path of the fileset file storage directory. This may require the creation of additional directories. Other file types (directories, except as needed to store files, hard links and symbolic links) are not required to exist in the distribution. The POSIX.1 file permissions for files in the file storage area are undefined.
Given that multiple versions of a product may be contained in the same distribution, collisions from product control directories named by the tag attribute are common.
These conditions are met by defining a
attribute for each product and fileset that is unique
within the distribution.
The attribute uses the syntax:
%token FILENAME_CHARACTER_STRING /* as defined in 184.108.40.206 */
control_directory : tag_part
| tag_part "." instance_id_part
tag_part : FILENAME_CHARACTER_STRING
instance_id_part : FILENAME_CHARACTER_STRING
The tag_part may be the product or fileset tag attribute, truncated as necessary to meet any filename length restrictions of the operating system.
The instance_id_part is a string that, when added after the "." (period), defines a control_directory which, for products, is unique within the distribution and, for filesets, is unique within the product. For products, this instance_id_part may be the instance_id of the product if that instance_id was generated considering other products tag_parts in addition to tag attributes.
The PSF supports the same syntax as the INDEX and INFO files. Additional syntactic constructs are supported for specifying files and control_files. This file is used in selection, analysis and packaging Phases of the swpackage command.
Additionally, there is a space file that is created by the software vendor for additional disk space needed for a product or fileset. This file is used in analysis phase of the swinstall command to account for additional disk space required.
The software specification file syntax is as follows.1
The following syntax rules are applicable to software definition files:
The former is used when the hierarchy is defined by reference, and the latter when the hierarchy is defined by containment. For example, subproducts and filesets are contained within products, but filesets are referenced by subproducts.
The value associated with any keyword is processed as an
layout_version path path dfiles dfiles pfiles pfiles uuid uuid
- distribution layout_version
INDEX and PSF files can contain distribution definitions. Neither file contains the path attribute. Its value is generated dynamically by swlist.
The bundles, media, and products attributes are not stored as attributes, but rather as bundle, media, and product definitions. These attributes are not included in swlist -v output. Rather, they are generated dynamically only by swlist -a attribute.
A PSF does not require a distribution definition. The PSF does not contain the uuid attribute. It is generated dynamically, if needed, by swcopy and swpackage.
An INDEX file contains the layout_version attribute as the first attribute defined in the file. Distributions which span multiple media contains the uuid attribute.
- media sequence_number
INDEX files for distributions can contain media definitions.
An INDEX file for a distribution contains the sequence_number attribute if the distribution spans multiple media.
The storage of catalogs for installed software is undefined. With the use of the swlist utility, the contents of such catalogs may be manifested in exported catalog form. The rules contained within this section applies when the contents of an installed software catalog is manifested in exported catalog form.
INDEX files can contain installed_software definitions. This describes the attributes for installed_software objects when listed in exported catalog structure using swlist.
The products and bundles attributes are not stored as attributes, but rather as product and bundle definitions. These attributes are not included in swlist -v output. Rather, they are generated dynamically only by swlist -a attribute .
An INDEX file does not contain the path or catalog attributes; they are generated dynamically by swlist.
An INDEX file contains the layout_version attribute as the first attribute defined in the file.
tag title title description description
- vendor tag
INDEX and PSF files can contain vendor definitions. The tag attribute is required for all vendor objects.
tag title title description description revision revision
- category tag
INDEX and PSF files can contain category definitions.
attribute is required for all category objects.
tag architecture architecture category_tag category_tag location location qualifier qualifier revision revision vendor_tag vendor_tag contents contents copyright copyright create_time create_time description description directory directory instance_id instance_id is_locatable is_locatable is_locatable is_locatable is_patch is_patch machine_type machine_type mod_time mod_time number number os_name os_name os_release os_release os_version os_version size size title title
- bundle tag
INDEX and PSF files can contain bundle definitions. The tag and contents attributes are required for all bundles.
Neither file contains the size attribute. The value of the size attribute is generated dynamically based on the sizes of the filesets currently contained within the bundle.
An INDEX file also contains an instance_id attribute. The value of the instance_id attribute is generated dynamically by swpackage or swcopy. An INDEX file for installed software contains a create_time attribute and a mod_time attribute for each bundle.
Only bundle definitions for installed software may contain either the location or qualifier attributes; bundle definitions for distributions do not contain either the location or qualifier attributes.
A PSF should not contain either the location or qualifier attributes; they are ignored when parsing the file.
tag architecture architecture category_tag category_tag qualifier qualifier revision revision vendor_tag vendor_tag all_filesets all_filesets control_directory control_directory copyright copyright create_time create_time directory directory description description instance_id instance_id is_locatable is_locatable is_patch is_patch postkernel postkernel location location machine_type machine_type mod_time mod_time number number os_name os_name os_release os_release os_version os_version size size title title
- product tag
INDEX and PSF files can contain product definitions. The tag and control_directory attributes are required for all products.
Neither file contains the size attribute. The value of the size attribute is generated dynamically based on the sizes of the filesets currently contained within the product.
An INDEX file for installed software contains a create_time attribute and a mod_time attribute for each product.
The control_files, filesets, and subproducts attributes are not stored as attributes, but rather as control_file, fileset, and subproduct definitions. These attributes are not included in swlist -v output. Rather, they are generated only by swlist -a attribute .
An INDEX file contains an instance_id attribute. The value of the instance_id attribute is generated by swpackage or swcopy. An INDEX file also contains a all_filesets attribute in addition to the fileset definitions. This attribute is generated by swpackage and represents all filesets defined for the product, as opposed to those that are currently contained within the product. The value of the filesets and all_filesets attributes may differ, since some originally defined filesets might not be copied or installed. Only product definitions for installed software may contain either the location or qualifier attributes; product definitions for distributions do not contain either the location or qualifier attributes.
A PSF should not contain either the location or qualifier attributes; they are ignored when parsing the file.
tag contents subproducts category_tag category_tag create_time create_time description description is_patch is_patch mod_time mod_time size size title title
- subproduct tag
INDEX and PSF files can contain subproduct definitions. The tag and contents attributes are required for all subproducts.
Neither file contains the size attribute. The value of the size attribute is generated dynamically based on the sizes of the filesets currently contained within the subproduct.
An INDEX file for installed software contains a create_time attribute and a mod_time attribute for each subproduct.
tag ancestor ancestor applied_patches applied_patches category_tag category_tag control_directory control_directory corequisites corequisites create_time create_time description description exrequisites exrequisites is_reboot is_reboot is_kernel is_kernel is_locatable is_locatable is_patch is_patch is_sparse is_sparse location location media_sequence_number media_sequence_number mod_time mod_time patch_state patch_state prerequisites prerequisites revision revision saved_files_directory saved_files_directory size size state state superseded_by superseded_by supersedes supersedes title title
- fileset tag
INDEX and PSF files can contain fileset definitions. The tag and control_directory attributes are required for all filesets.
The control_files and files attributes are not stored as attributes, but rather as control_file and file definitions. These attributes are not included in swlist -v output. Rather, they are generated only by swlist -a attribute .
file contains a
for each defined fileset.
A PSF should not contain the applied_patches, location, media_sequence_number, patch_state, saved_files_directory, size, state, or superseded_by attributes; they are ignored when parsing the file. The value of the size attribute is generated dynamically by swpackage based on the sizes of the files and control_files.
When defining a patch, the attributes that must be defined are the files to be patched, and the fileset attribute is_patch. This automatically sets the category_tag patch; the patch category can not be specified in a PSF file. The product containing a patch or sparse fileset must have a different tag or revision attribute from the product containing the ancestor fileset being updated.
tag cksum cksum compressed_cksum compressed_cksum compressed_size compressed_size compression_state compression_state compression_type compression_type interpreter interpreter path path revision revision size size source source result result
- control_file tag
INFO and PSF files can contain control_file definitions.
A PSF should not contain the cksum, compressed_cksum, compressed_size, compression_state, compression_type, size, or result attributes; they are ignored when parsing the file. The values of the size and cksum attributes are generated dynamically by swpackage based on the source file. A PSF contains a source attribute. A PSF can contain a path attribute. If it does not, swpackage uses the basename obtained from the value of the source attribute as the value of the path attribute. A PSF can contain a tag attribute. If it does not, swpackage uses the basename obtained from the value of the path attribute as the value of the tag attribute. The swpackage utility resolves the value of the tag attribute after it resolves the value of the path attribute.
An INDEX file contains the tag, path, cksum, and size attributes. Control_file definitions for installed software also contain the result attribute. INDEX files should not contain the source attribute; it is ignored when parsing the file.
The swpackage command automatically includes the INFO file itself as a control file and adds the tag, path, and size attributes for it. The value of the cksum attribute for the INFO control_file itself is not defined. An implementation can choose to store certain software object attributes, such as copyright, as control_files.
path archive_path archive_path cksum cksum compressed_cksum compressed_cksum compressed_size compressed_size compression_state compression_state compression_type compression_type gid gid group group is_volatile is_volatile link_source link_source major major minor minor mode mode mtime mtime owner owner revision revision size size source source type type uid uid
- file path
INFO and PSF can contain file definitions.
A PSF contains a source attribute. A PSF should not contain the cksum compressed_cksum, compressed_size, compression_state, compression_type, or size attributes; they are ignored when parsing the file. Device files (including the major and minor attributes) should not be defined in a PSF (but can be added via swmodify after being created by a configure script); they are ignored when parsing the file. The values of the size and cksum attributes are generated dynamically by swpackage based on the source file. A PSF can contain a path attribute, otherwise the source is used to defined the path by swpackage. A PSF can contain gid, group, link_source, mode, mtime, owner, type, and uid attributes, otherwise they are retrieved from the source file by swpackage. A PSF can contain is_volatile and revision attributes. Automatic determination of the file revision is implementation defined.
file should not contain the
it is ignored when parsing the file.
Table: File Attributes for INFO File
Within a PSF file, if the same file is defined more than once, the attributes from the last definition are used and they redefine the attributes previously defined. This action does not cause additional copies of the file to be stored in the distribution. All attributes not specifically listed remain unchanged.
source [path] preinstall source [path] postinstall source [path] verify source [path] fix source [path] checkremove source [path] preremove source [path] postremove source [path] configure source [path] unconfigure source [path] request source [path] unpreinstall source [path] unpostinstall source [path] space source [path] control_file source [path]
A PSF can contain extended control_file definitions. Each control_file definition defines the source attribute (the source file) to be used for the script. The keyword (meaning checkinstall, preinstall, etc.) defines the tag of the script, which tells the utilities when to execute the script.
If the optional path is supplied, it is the file name in the distribution (relative to the control directory for the software containing this script) used to store the file; otherwise, the control_file.tag attribute is used as the file name. This also allows a vendor to define one script to be executed for multiple tags. The script can determine the tag being executed by the SW_CONTROL_TAG environment variable.
If the control_file keyword is used, then the basename of the source attribute is the tag of the control_file.
These mechanisms can all be used in combination with the others.
This syntax defines a source directory under which subsequently listed files are located. In addition, the user can map the source directory to a destination directory under which the packaged files will be located.
The destination directory is an absolute pathname and is used as a prefix to the path attribute for each of the files.
The source directory can be either an absolute pathname, or a relative pathname. If relative, the swpackage utility interprets it relative to the current working directory in which the utility was invoked.
If the source directory does not exist, the swpackage utility generates an error.
- file *
This syntax directs the swpackage utility to include every file (and directory) within the current source directory in the fileset. The swpackage utility attempts to include the entire, recursive contents of the source directory in the fileset.
The directory keyword is specified before the file * specification is used. After finishing the recursive processing of the source directory, the swpackage utility processes further specifications with respect to the original directory.
The user can specify multiple directory and file * pairs to gather all files from different source directories into a single fileset.
Instead of, or in addition to, the recursive file specification, the user can explicitly specify the files to be packaged into a fileset.
This syntax may be used to redefine an attribute of a previously defined file. All attributes not specifically listed remain the same.
The directory keyword can be used 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 (the path attribute) is specified for each file.
The meaning of each of these fields is as follows:
If this is a relative path, the swpackage utility searches for it relative to the source directory set by the directory keyword. If no source directory is active, the swpackage utility searches for it relative to the current working directory in which the utility 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.
When specifying a new directory to be created upon installation, and there is no destination path specified, the source defines the path of the installed directory. When specifying a new hard link or symbolic link to be created upon installation, the source defines the pathname of the installed file to use as the source for the new file.
Files with the types c (character special), b (block special) and p (named pipe | FIFO) are not supported by swpackage and swinstall and can be created via a configure control script. In general, device files and pipes are created during system configuration on the system actually running the software. Also, there can be files of other types that the swpackage utility does not recognize and which therefore cause an error.
During an installation, the owner attribute is used to set the owner name and uid, unless the owner name is not defined in the target system user database. In this case, the value of the uid attribute is used to set the uid.
During an installation, the group attribute is used to set the group name and gid, unless the group name is not defined in the target system group database. In this case, the gid attribute is used to set the gid.
file_permissions [-m mode | -u umask][-o [owner[,]][uid]]
A destination file object inherits the mode, owner, and group of the source file. The file_permissions keyword can be specified to set a default permission mask, owner, and group for all the files being packaged into the fileset:
By specifying a
A file listed after the exclude keyword that was previously included, for example from a recursive file definition, is excluded from the list of files.
If the source specifies a directory, then all files below that directory are excluded.
- file <
The file keyword can be used to include definitions for files from a separate include_file by specifying a < (less than) character followed by the include_file.
For each path listed in the space file, the swinstall utility adds the size, in bytes, to the disk space requirements. The size can be positive (reflecting the maximum transient or permanent disk space required for the install), or negative (reflecting space freed by one of the scripts executed by the swinstall command). An implementation must consider positive records and may consider negative records.
Implementations support serial distributions if the underlying operating system supports the pax utility, as defined in POSIX.2, or otherwise supports reading and writing of the extended tar and extended cpio archives defined in POSIX.1. If serial distributions are supported, the serial distribution formats supported include extended tar and extended cpio.
The distribution is implemented as a set of one or more POSIX.1 extended cpio or extended tar archives. The archives reside on a set of one or more serial media, or in a file. Each media in a serial distribution contains one and only one archive.
A distribution may span multiple media in a hierarchical structure.
In this case, the set of files on any particular media, including the
attributes defined in any software definition files,
should be similar to that
for a serial archive.
In other words, the decision for which files are put on which media
be the same whether the distribution is serial or hierarchical.
Space considerations on media may cause some differences.
The following are the rules regarding ordering of files within serial distributions. These rules, including generation of the fileset.media_sequence_number, are implemented by the swpackage utility.
Additionally, in order to increase the usability of multiple media serial distributions, the following guidelines should be used and in decreasing importance:
Thus a conforming implementation is able to:
Note that in all respects, a serial distribution conforms to the specifications of the extended cpio or extended tar archives. See POSIX.1. This includes, but is not limited to, the following: