# sw(5)

### Contents

- NAME
- SYNOPSIS
- SOFTWARE PACKAGING LAYOUT
  - Minimal Package Layout
  - Distribution Files
  - Product Files
  - Fileset Files
  - Control Directory Names
  - File Storage
- SOFTWARE DEFINITIONS
  - Host Definition
  - Distribution Definition
  - Installed_software Definition
  - Media Definition
  - Vendor Definition
  - Bundle Definition
  - Product Definition
  - Category Definition
  - Subroduct Definition
  - Fileset Definition
  - File Definition
  - Control File Definition
- EXTENDED DEFINITIONS
- DISTRIBUTOR KEYWORDS
- PACKAGE SECURITY
  - Archive Digests
  - Adjunct Md5 Digest
  - Catalog Signature Header
  - Catalog Signature
  - File Md5 Digest
- SOFTWARE DEFINITION FILES
  - Additional Syntax Rules
  - Software Definition File Grammar
- EXAMPLE PACKAGE
  - Hypothetical PSF file
- SWBIS PSF CONVENTIONS
- APPLICABLE STANDARDS
- SEE ALSO
- IDENTIFICATION
- BUGS

### NAME

           sw -- POSIX Software Packaging

### SYNOPSIS

           Software Packaging Layout
           Software Definitions
           Extended Definitions
           Distributor Keywords
           Package Security
           Software Definition Files: INFO, INDEX, PSF
           Example Package

### SOFTWARE PACKAGING LAYOUT

           A package may exist in two forms: as a directory in a file system, or a
           serial access tar or cpio archive file.  A package consists of two main
           sections:  1) the exported catalog structure, and, 2) the software file
           storage structure.  Each section may contain path name components which
           serve to segregate distribution, product and fileset objects.

           Shown below is an example with one (1) product and one (1) fileset.

            <path>/
            <path>/catalog/
            <path>/catalog/INDEX
            <path>/catalog/<dfiles>
            <path>/catalog/<dfiles>/...
            <path>/catalog/<prod_dir>/
            <path>/catalog/<prod_dir>/<pfiles>/INFO
            <path>/catalog/<prod_dir>/<pfiles>/...
            <path>/catalog/<prod_dir>/<fileset_dir>/
            <path>/catalog/<prod_dir>/<fileset_dir>/INFO
            <path>/catalog/<prod_dir>/<fileset_dir>/...
            <path>/catalog/<prod_dir>/<fileset_dir>/<script>
            <path>/<prod_dir>/
            <path>/<prod_dir>/<fileset_dir>/
            <path>/<prod_dir>/<fileset_dir>/<distribution_files>
            <path>/<prod_dir>/<fileset_dir>/<distribution_files>/...

           The  exported  catalog  structure  consists of the files with pathnames
           that begin <path>/catalog.  Note that catalog is not a  legal  prod_dir
           name. Also, "dfiles", and "pfiles" should not be used as control direc-
           tory names, they are the default names for the Distribution and Product
           files  directories.   The  dfiles  and  pfiles  defaults  are  commonly
           accepted.

           The order of files in a serial access archive is  specified  and  shown
           above.   The  order  of  products  and filesets within a product is not
           specified, although they must be grouped together.  Notably, the  INDEX
           file is the first regular file in the package, followed by the <dfiles>
           directory.  For each product, the <prod_dir> is followed immediately by
           the <prod_dir>/<pfiles> directory.

       Minimal Package Layout
           To support extant usage of tar archives, this implementation supports a
           minimal package layout.  The layout is  non-intrusive  to  the  current
           practice  of  extracting  a 'binary' package in the '/' directory where
           <path>/ is nil and, likewise to 'source' packages where <path> is typi-
           cally the package name and version.  The use of nil control directories
           is not attested to in the posix normative references.

            <path>/
            <path>/catalog/
            <path>/catalog/INDEX
            <path>/catalog/dfiles/
            <path>/catalog/dfiles/INFO
            <path>/catalog/dfiles/...
            <path>/catalog/pfiles/INFO
            <path>/catalog/pfiles/...
            <path>/catalog/INFO
            <path>/<distribution_files>/...

           In this layout a single  product  and  fileset  have  control_directory
           attributes specified as an empty string.

       Distribution Files
           catalog/<dfiles>/...

           <dfiles>  is the value of the dfiles attribute and the default value is
           "dfiles".  This directory can store an INDEX file or INFO file pertain-
           ing to the distribution.  It can also store an attribute of the distri-
           bution as a separate file where file name is the name of the  attribute
           and the file contents the value.

       Product Files
           catalog/<prod_dir>/<pfiles>/...

           <pfiles>  is the value of the pfiles attribute and the default value is
           "pfiles".  This directory can store an  INFO  file  pertaining  to  the
           product  control_files,   control scripts defined in the INFO file, and
           all other distributor-defined control_files.   It  can  also  store  an
           attribute of the product as a separate file.

       Fileset Files
           catalog/<prod_dir>/<fileset_dir>/...

           This  directory contains information in the same form as does the Prod-
           uct Files although pertaining to the fileset.

       Control Directory Names
           The <prod_dir>/<fileset_dir> names are the values of the control_direc-
           tory  attribute  for the product and fileset respectively.  The default
           value is the value of the tag attribute.   <prod_dir>  must  be  unique
           within  a  distribution and <fileset_dir> must be unique within a prod-
           uct.

       File Storage
           <prod_dir>/<fileset_dir>/<distribution_files>/...

           The listing of control directories in the exported catalog structure is
           repeated  and  files of the distribution appear under these directories
           in a location determined by the metadata.

           The standard does not require that files that  are  not  regular  files
           appear in the storage section.

### SOFTWARE DEFINITIONS

           The  Software  Definitions  are metadata representations of the objects
           and attributes recognized by the standard.  The right  hand  column  in
           each  definition shows the default attribute value.  The defining stan-
           dard for each attribute is indicated as a comment (leading '#' sign) if
           it  is not IEEE-1387.2,  other defining standards are XDSA C701 (C701),
           and, this implementation (impl.).

       Host Definition
            host
              hostname     hostname       None
              os_name      os_name        None
              os_release   os_release     None
              os_version   os_version     None
              machine_type machine_type   None

           The host definition was attested to only in the  informative  annex  of
           the standard.  An implementation may chose to define this class.

           A host object can contain a distribution, or installed_software object.

       Distribution Definition
            distribution
              layout_version layout_version  1.0
              path           path            Implementation Defined
              dfiles         dfiles          dfiles
              pfiles         pfiles          pfiles
              uuid           uuid            Empty string

           The path attribute is not in a PSF nor INDEX files.   A  PSF  does  not
           contain  a uuid attribute.  An INDEX file will contain a layout_version
           attribute as the first attribute.

           A distribution object can contain bundles, products, and, media in  the
           form of software definitions.

           The  following attributes are recognized as valuable by the Informative
           Annex of POSIX.7.2.

              tag                tag                Empty string
              title              title              Empty string
              description        description        Empty string
              revision           revision           Empty string
              media_type         media_type         Empty string
              copyright          copyright          Empty string
              create_time        create_time        Empty string
              number             number             Empty string
              architecture       architecture       Empty string

           The following attributes are recognized by this implementation.

              signature          < pathname  None   # impl.
              sig_header   < pathname  None   # impl.
              sha1sum            < pathname  None   # impl.
              md5sum             < pathname  None   # impl.
              adjunct_md5sum     < pathname  None   # impl.
              files              < pathname    None  # impl.
              control_directory  control_directory      Empty string   # impl.
              owner              name                           root   # impl.
              group              name                           root   # impl.
              mode               mode                           0755    # impl.
              signer_pgm         utility_name                   GPG    # impl.
              signer_pgm_version version                        1    # impl.
              tar_format_emulation_options program_options          # impl.
              tar_format_emulation_utility software spec            # impl.

           The url attribute is the universal record locator of the packager qual-
           ified  vendor.   The  control_directory  attribute  in the distribution
           object appears as the <path> leading directory path  in  the  a  serial
           archive  package.   The  owner,  group, and mode attributes control the
           file attributes  of  the  single  path  name  prefix.   The  signature,
           sig_header,  md5sum,  and adjunct_md5sum attributes are described below
           and are stored as separate files in the dfiles directory. The  tar_for-
           mat_emulation_*  options  define the GNU tar version and format options
           that the archive file mimics, these attributes are used by the  'check-
           sig' script.

       Installed_software Definition
            installed_software
              layout_version layout_version  1.0
              path           path            Implementation Defined
              dfiles         dfiles          dfiles
              pfiles         pfiles          dfiles
              catalog        catalog         Undefined
              install_time   install_time    Undefined       # impl.

           A  software  object can be listed (written to stdout) in the form of an
           INDEX file by the swlist utility.

       Media Definition
            media
              sequence_number sequence_number  1

           An INDEX file must contain the sequence_number attribute if the distri-
           bution spans multiple media.

       Vendor Definition
            vendor
              the_term_vendor_is_misleading  true                  True or False  #impl
              tag         tag           Empty string
              title       title         Empty string
              description description   Empty string
              qualifier   qualifier     Empty string  # impl.
              url         url           Empty string  # impl.

           The  tag  attribute  is required.  The the_term_vendor_is_misleading is
           required in a PSF file to avert a (harmless) warning,  please  use  it.
           It  exists  to  allow  persons,  for  example, who are distributors (of
           existing free software) to qualify themselves away  from  the  connota-
           tions of a "vendor" which has specific meaning not applicable to a free
           software distributor.  A INDEX and PSF files can contain vendor defini-
           tions.   The  qualifier  attribute value may be one of: seller, author,
           packager, maintainer.  A distribution may have  more  than  one  vendor
           definition.

       Bundle Definition
            bundle
              tag          tag    architecture architecture    Empty string
              location     location        <bundle.directory>
              qualifier    qualifier       Empty string
              revision     revision        Empty string
              vendor_tag   vendor_tag      Empty string
              create_time  create_time     None
              description  description     Empty string
              contents     contents        Empty string
              copyright    copyright       Empty string
              directory    directory       Empty string
              instance_id  instance_id     1
              is_locatable is_locatable    true
              layout_version layoyt_version  1.0
              machine_type machine_type    Empty string
              mod_time     mod_time        Empty string
              number       number          Empty string
              os_name      os_name         Empty string
              os_release   os_release      Empty string
              os_version   os_version      Empty string
              size         size            Empty string
              title        title           Empty string
              category_tag category_tag    Empty list or patch  # C701
              is_patch     is_patch        false                # C701

           The  tag  and  contents attributes are required in INDEX and PSF files.
           The size attribute is not allowed in either file. The value of size  is
           generated  dynamically.   An  INDEX  file  will  contain  a instance_id
           attribute.  Bundle  definitions  for  distributions  will  not  contain
           either  the  location or qualifier, installed_software objects may con-
           tain these attributes.

       Product Definition
            product
              tag               tag               None
              architecture      architecture      Empty string
              location          location          <product.directory>
              qualifier         qualifier         Empty string
              revision          revision          Empty string
              vendor_tag        vendor_tag        Empty string
              all_filesets      all_filesets      Empty list
              control_directory control_directory <product.tag>
              copyright         copyright         Empty string
              create_time       create_time       None
              directory         directory         /
              description       description       Empty string
              instance_id       instance_id       1
              is_locatable      is_locatable      true
              postkernel        postkernel        Implemen. defined
              layout_version    layout_version    1.0
              machine_type      machine_type      Empty string
              number            number            Empty string
              os_name           os_name           Empty string
              os_release        os_release        Empty string
              os_version        os_version        Empty string
              mod_time          mod_time          None
              size              size              None
              title             title             title
              category_tag      category_tag      Empty list # C701
              is_patch          is_patch          false      # C701
              copyrighters      copyrighters      None       # impl.
              build_root        build_root        None       # impl.
              build_host        build_host        None       # impl.
              source_package    source_package    None       # impl.
              source_rpm        source_rpm        None       # impl.
              all_patches       all_patches       None       # impl.
              url               url               None       # impl.
              rpm_provides      rpm_provides      None       # impl.
              change_log        change_log        None       # impl.

           The tag  and  control_directory  attributes  are  required.   The  size
           attribute is not allowed in either file. The value of size is generated
           dynamically.  An INDEX file will contain a  instance_id  attribute.   A
           product  object  can  contain control_files, files, and, subproducts in
           the form of software definitions.

       Category Definition
            category
              tag           tag            None             # C701
              title         title          Empty string     # C701
              description   description    Empty string     # C701
              revision      revision       Empty string     # C701

           The Category definition describes attributes of  products  and  bundles
           related  to  its category. If is_patch is "true" then category.tag must
           equal "patch".

       Subroduct Definition
            subproduct
              tag           tag            None
              create_time   create_time    None
              description   description    Empty string
              mod_time      mod_time       None
              size          size           None
              title         title          Empty string
              contents      contents       Empty list
              category_tag  category_tag   Empty list   # C701
              is_patch      is_patch       false        # C701

           The tag and contents attributes are required.

       Fileset Definition
            fileset
              tag               tag               None
              create_time       create_time       None
              mod_time          mod_time          None
              control_directory control_directory <fileset.tag>
              corequisites      corequisites      Empty list
              description       description       Empty string
              exrequisites      exrequisites      Empty list
              is_kernel         is_kernel         false
              is_locatable      is_locatable      true
              is_reboot         is_reboot         false
              location          location          <product.directory>
              media_sequence_number media_sequence_number 1
              prerequisites     prerequisites     Empty list
              revision          revision          None
              size              size              None
              state             state             None
              title             title             Empty string
              is_sparse         is_sparse        "false"        # C701
              is_patch          is_patch         "false"        # C701
              category_tag      category_tag      empty list    # C701
              ancestor          ancestor          <product.tag>,ver_id # C701
              applied_patches   applied_patches   empty list    # C701
              patch_state       patch_state       applied or,   # C701
                                                      committed or,
                                                        superseded, (no default).
              saved_files_directory  saved_files_directory None # C701
              supersedes       supersedes          None         # C701
              superseded_by    superseded_by       None         # C701

           The tag and control_directory attributes are required.   A  PSF  should
           not   contain  the  location,  media_sequence_number,  size,  or  state
           attributes.  A fileset object can contain control_files, files, in  the
           form of software definitions.

       File Definition
            file
              path               path               None
              cksum             cksum             None
              compressed_cksum  compressed_cksum  None
              compressed_size    compressed_size    None
              compression_state  compression_state  uncompressed
              compression_type   compression_type   Empty string
              revision           revision           Empty string
              size               size               None
              source             source             None
              gid                gid                Undefined
              group              group              Empty string
              is_volatile        is_volatile        false
              link_source        link_source        None
              major              major              None
              minor              minor              None
              mode               mode               None
              mtime              mtime              None
              owner              owner              Empty string
              type               type               f
              uid                uid                undefined
              archive_path    archive_path    empty string    # C701
              md5sum           md5sum      empty string    # impl.
              rdev            rdev            empty string    # impl.
              rpm_fileflags   rpm_fileflags   empty string    # impl.

           A  PSF  must  contain source attribute.  A source  attribute in an INFO
           will be ignored.  A PSF should not contain the cksum, compressed_cksum,
           compressed_size,    compression_state,    compression_type,   or   size
           attributes.

       Control File Definition
            control_file
              tag                tag                None
              cksum             cksum             None
              compressed_cksum  compressed_cksum  None
              compressed_size    compressed_size    None
              compression_state  compression_state  uncompressed
              compression_type   compression_type   Empty string
              revision           revision           Empty string
              size               size               None
              source             source             None
              path               path               None
              interpreter        interpreter        sh
              result             result             none

           A control_file defines a control script such as those listed below (see
           Extended Control File Definitions) or an attribute stored as a file.

### EXTENDED DEFINITIONS

           A  Product Specification File (PSF) can contain Extended Definitions in
           the fileset, product or bundle software definitions.  They  would  have
           the  same  level  or containment relationship as a file or control_file
           definition in the same contaning object.

           Extended Definitions represent a minimal, expressive form for  specify-
           ing  files and file attributes.  Their use in a PSF is optional in that
           an equivalent PSF can be constructed without using them, however, their
           use is encouraged for the sake of brevity and orthogonality.

           The  swbis implementation requires that no [ordinary] attributes appear
           after Extended Definitions in the containing object, and, requires that
           Extended  Definitions  appear before logically contained objects.  That
           is, the parser uses the next object keyword to  syntacticly  and  logi-
           cally terminate the current object even if the current object has logi-
           cally contained objects.

       o  Extended Control File Definitions
                checkinstall  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]

           The source attribute defines the location in distributors's development
           system  where  the swpackage utility will find the script.  The keyword
           is the value of the tag attribute and tells the utilities when to  exe-
           cute the script.  The path attribute is optional and specifies the file
           name in the packages distribution relative to the control_directory for
           software  containing  the script. If not given the tag value is used as
           the filename.

       o  Directory Mapping
              directory  source  [destination]

           Applies the source attribute as the directory under  which  the  subse-
           quently listed files are located.  If destination is defined it will be
           used as a prefix to the path (implied) file definition.  source is typ-
           ically  a  temporary or build location and dest is its unrealized abso-
           lute pathname destination.

       o  Recursive File Definition
             file *

           Specifies every  file  in  current  source  directory.   The  directory
           extended definition must be used before the recursive specification.

       o  Explicit File Definition
             file [-t type] [-m mode] [-o owner[,uid]] [-g group[,gid]] [-n] [-v] source [path]

           source

                  source defines the pathname of the file to be used as the source
                  of file data and/or attributes.  If it is a relative path,  then
                  swpackage  searches  for  this  file  relative to the the source
                  argument of the directory keyword, if set.  If directory keyword
                  is  not  set  then the search is relative to the current working
                  directory of the swpackage utility's invocation.

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

           path

                  path defines the destination path where the file will be created
                  or installed.  If it is a relative path,  then  the  destination
                  path  of the of the directory keyword must be active and will be
                  used as the path prefix.  If path is not specified  then  source
                  is  used  as the value of path and directory mapping applied (if
                  active).

           -t type

                  type may one of 'd' (directory), or  'h'  (hard  link),  or  's'
                  (symbolic link).

                  -t d  Create a directory.
                  If path is not specified source is used as the path attribute.

                  -t h  Create a hard link.
                  path  and  source are specified.  source is used as the value of
                  the link_source attribute, and path is the  value  of  the  path
                  attribute.

                  -t s  Create a symbolic link.
                  path  and  source are specified.  source is used as the value of
                  the link_source attribute, and path is the  value  of  the  path
                  attribute.

           -m mode

                  mode defines the octal mode for the file.

       o  Default Permission Definition
             file_permissions [-m mode] [-u umask] [-o [owner[,]][uid]] [-g [group[,]][gid]]

           Applies  to  subsequently  listed file definitions in a fileset.  These
           attributes will apply where the  file  attributes  were  not  specified
           explicitly  in  a file definition.  Subsequent file_permissions defini-
           tions simply replace previous definitions (resetting all the  options).

           To  reset  the  file_permission state (i.e. turn it off) use one of the
           following:
               file_permissions ""
                or the preferred way is
               file_permissions -u 000

       o  Excluding Files
              exclude source

           Excludes a previously included file or an entire directory.

       o  Including Files
              include <filename

           The contents of filename may be more definitions for files.  The syntax
           of the included file is PSF syntax.

### DISTRIBUTOR KEYWORDS

           A  software  definition  file (INFO, INDEX or psf) may contain keywords
           not recognized by the standard.  Such keywords will  be  parsed  as  an
           attribute  keyword,  that  is  as an attribute of the containing object
           (keyword) software definition.

### PACKAGE SECURITY

           The Package Security Attributes are distribution attributes  stored  as
           separate  files.   They are implementation extensions.  They consist of
           archive digests, catalog signature, catalog signature header, and indi-
           vidual file md5 digests.

       Archive Digests
           md5sum and sha1sum are the md5 and sha1 digests (ascii representations)
           of the leading package directories that do not have the  catalog  path-
           name  component followed by the software file storage structure portion
           of the uncompressed serial access package file  including  all  archive
           format trailer blocks.

                  <path>/catalog/<dfiles>/md5sum
                  <path>/catalog/<dfiles>/sha1sum

       Adjunct Md5 Digest
           adjunct_md5sum  is the same as the md5sum excluding symbolic links.  If
           a package does not contain symbolic links the md5sum and adjunct_md5sum
           will be identical.

                  <path>/catalog/<dfiles>/adjunct_md5sum

           Explanation:  This attribute is called 'adjunct' because it is a digest
           of a subset of the files in the package.  It exists to facilitate veri-
           fying  file integrity of the directory form of a package in an environ-
           ment where the modification time of symbolic link files  are  not  pre-
           served  from the serial archive by the tar utility or operating system.
           The ability to verify even the adjunct_md5sum from the  directory  form
           of  the  package  is  dependent  on  the tar creating utility and other
           attributes of a POSIX.2 environment.

       Catalog Signature Header
           The sig_header file is a ustar header that is identical bit-for-bit  to
           the  ustar header of the signature file.  It always precedes the signa-
           ture file archive members.

                  <path>/catalog/<dfiles>/sig_header

           The sig_header protects the tar header of the signature files from tam-
           pering.   This is required because neither the signature file bytes nor
           the signature tar header are included in the signed data.

       Catalog Signature
           The signature protects the metadata section of the archive.   The  con-
           tents  of  payload  section  are  only included in the form of a cryto-
           graphic digest.  The sha1 digest is preferred over the md5  digest  for
           technical  reasons.   If the metadata section does not contain the pay-
           load section digests then there is no way to verify  the  payload  from
           the signature.

                  <path>/catalog/<dfiles>/signature

           The  signed  data is the exported catalog structure of the uncompressed
           serial archive package file up to but not including the first  byte  of
           the  software  file storage structure followed by two (2) 512 byte null
           blocks if tar format, and no trailer bytes if not tar format.  The sig-
           nature file archive member itself is not included in the signed stream,
           it is intended that the <path>/catalog/<dfiles>/md5sum file is included
           in the signed stream.

           The  signature  file is ASCII armored.  The last printable character of
           the signature is followed by one or more newline characters (0x0A) fol-
           lowed  by  one  or more NUL characters (0x00).  The total length of the
           file must match the file size  specified  in  the  size  field  of  the
           sig_header  file.   The  ustar header of every signature archive member
           shall be  identical  to  the  sig_header  file.   The  padded  size  is
           predetermined [by swpackage] and currently set to be 1024 octets.  This
           means the armored sig file has a length limitation of 1023 octets.

           If multiple signature  archive  members  exist  they  must  follow  one
           another  in  the archive with no other intervening files; and, the same
           sig_header file is the ustar header for all the signature archive  mem-
           bers.   A  signature  archive  member, whether alone or one of many, is
           never part of the signed data stream.

       File Md5 Digest
                  file.md5sum

           Each file has a md5 digest in the metadata.

### SOFTWARE DEFINITION FILES

           The metadata files, INDEX, INFO and PSF, contain information about  the
           software in the form of software definitions.  The INDEX and INFO files
           appear in a package directory structure.  They are automatically gener-
           ated  by the 'swpackage' command.  The location in the directory struc-
           ture indicates the higher level object to which  their  data  pertains.
           The PSF file does not appear in the package.  It is created by a person
           or program and it directs the action of the swpackage utility.   It  is
           internal data unless released by the distributor.

           The  files  contain  keywords  (and values) to represent the attributes
           defined in the standard.  There are three (3) different keyword  types:
           object,  attribute, and, extended. The object keyword type has no value
           and there are eleven (11) of these corresponding to the Software  Defi-
           nitions defined above: installed_software, distribution, media, bundle,
           vendor, category, product, subproduct, fileset, control_file, file.

           Each object keyword is followed by and newline and  attributes  in  the
           form  of  keyword/value  pairs.   Whitespace  separates the keyword and
           value.  Whitespace outside of a quoted value  is  not  significant.   A
           quoted  value can span multiple lines.  An object keyword with its list
           of attribute keywords (and values)  forms  a  Software  Definition.   A
           Software  Definition  is  terminated  by the start of the next Software
           Definition.  Extended  keywords  (meaning  Extended  Definitions)  only
           appear in a PSF file.

           The  order   of objects (i.e Software Definitions) is significant and a
           containment  hierarchy is determined according to parser's grammar.

       Additional Syntax Rules
              ·  A '#' (pound) character designates  a  comment.   A  comment  may
                 begin a line or appear at the end of a single line containing the
                 keyword/value pair.

              ·  A value may be quoted by the '"' (double quote)  character;  and,
                 multi-line  values  must be quoted.  Trailing white space from an
                 unquoted value will be removed.

              ·  The order of attributes is not  significant  although  the  INDEX
                 file  grammar  requires the layout_version attribute appear first
                 in distribution or installed software object.

              ·  The ", #, and, \ characters must be escaped with a backslash  (\)
                 in a quoted value.

              ·  If  a value begins with a < (less than), the value is interpreted
                 as a filename whose contents will be treated as  a  quoted  value
                 although  the  storage  of the attribute will be in the form of a
                 control file (i.e. a separate file  in  the  control  directory).
                 For  INDEX  files, the filename is relative to the control direc-
                 tory in which this attribute is contained.  For  PSF  files,  the
                 filename is a path on the host.

       Software Definition File Grammar
           A  PSF  may  contain  all Software Definitions.  An INDEX file does not
           contain control_file, or file definitions. An INFO file  contains  only
           control_file, and file definitions.

                software_definition_file : INDEX
                                         | INFO
                                         | PSF
                                         ;

                PSF :  distribution_definition
                       swo_contents
                       ;

                INDEX : swo_definition
                        swo_contents
                       ;

                INFO : fileset_contents
                       ;

                swo_definition : distribution_definition
                               | installed_software
                               ;

                distribution_definition : distribution
                                                    media
                                        ;

                swo_contents : vendor(s)
                              | category(s)
                              | products
                              | bundles
                              ;

                products : product
                           product_contents
                           ;

                bundles : bundle
                           ;

                product_contents :  control_files
                  /* control_files not valid in INDEX file */
                                | subproducts
                                |  filesets
                          ;

                filesets : fileset
                 /* fileset_contents not valid in INDEX file */
                           fileset_contents
                           ;

                fileset_contents :  control_files
                                 | files
                                 ;

### EXAMPLE PACKAGE

       Layout
            swm-1.0/catalog
            swm-1.0/catalog/INDEX
            swm-1.0/catalog/dfiles
            swm-1.0/catalog/dfiles/INFO
            swm-1.0/catalog/dfiles/md5sum
            swm-1.0/catalog/dfiles/sha1sum
            swm-1.0/catalog/dfiles/adjunct_md5sum
            swm-1.0/catalog/dfiles/sig_header
            swm-1.0/catalog/dfiles/signature
            swm-1.0/catalog/gsoft_swm
            swm-1.0/catalog/gsoft_swm/pfiles
            swm-1.0/catalog/gsoft_swm/pfiles/INFO
            swm-1.0/catalog/gsoft_swm/pfiles/remove
            swm-1.0/catalog/gsoft_swm/pfiles/configure
            swm-1.0/catalog/gsoft_swm/bin
            swm-1.0/catalog/gsoft_swm/bin/INFO
            swm-1.0/catalog/gsoft_swm/bin/postinstall
            swm-1.0/catalog/gsoft_swm/bin/configure
            swm-1.0/catalog/gsoft_swm/doc
            swm-1.0/catalog/gsoft_swm/doc/INFO
            swm-1.0/catalog/gsoft_swm/doc/postinstall
            swm-1.0/gsoft_swm
            swm-1.0/gsoft_swm/bin
            swm-1.0/gsoft_swm/bin/usr/bin/swpackage
            swm-1.0/gsoft_swm/bin/usr/bin/sw_build
            swm-1.0/gsoft_swm/doc
            swm-1.0/gsoft_swm/doc/usr/man/man1/swpackage.1
            swm-1.0/gsoft_swm/doc/usr/man/man1/sw_build.1

       Hypothetical PSF file
            distribution
              layout_version 1.0
              control_directory swm-1.0  #Implementation Extension.
              vendor
                the_term_vendor_is_misleading  false # True or False
                tag greatsoft
                title Greatersoft Corporation
                description "Greatersoft Corporation, Inc."
              product
                tag swm
                title POSIX 1387 package builder
                revision 1.0
                control_directory gsoft_swm
                vendor_tag greatsoft
                description A package building Utility.
                machine_type i386
                control_file
                     path remove
                   source /var/tmp/sw/remove.source
                configure /var/tmp/sw/configure.source
                fileset
                   tag bin
                   control_directory bin
                   title Executable Files
                   state available
                     postinstall /var/tmp/sw/bin/postinstall
                   configure /var/tmp/sw/bin/configure
                   file -m 0755 -o root -g root /var/tmp/sw/build/bin/swpackage  \
                                /usr/bin/swpackage
                   file -m 0755 -o root -g root /var/tmp/sw/build/bin/sw_build  \
                                /usr/bin/sw_build
              fileset
                 tag doc
                 control_directory doc
                 title Manual Pages
                 state available
                 postinstall /var/tmp/sw/bin/postinstall
                 file -m 0644 -o root -g root /var/tmp/sw/build/man/swpackage.1 \
                           /usr/man/man1/swpackage.1
                 file
                    mode 0644
                    owner root
                    group  root
                    source /var/tmp/sw/build/man/sw_build.1
                    path /usr/man/man1/sw_build.1

       INDEX File swm-1.0/catalog/INDEX
            distribution
              layout_version 1.0
              tag swm-1.0
              uuid 880ccf8b-de2c-4422-bff0-fd686279da73
              md5sum < md5sum
              adjunct_md5sum < adjunct_md5sum
              sig_header < sig_header
              signature < signature
              media
                sequence_number 1
              vendor
                the_term_vendor_is_misleading  false # True or False
                tag greatsoft
                title Greatersoft Corporation
                description "Greatersoft Corporation, Inc."
              product
                tag swm
                title POSIX 1387 package builder
                revision 1.0
                instance_id 1
                control_directory gsoft_swm
                vendor_tag greatsoft
                description A package building Utility.
                machine_type i386
                fileset
                   tag bin
                   control_directory bin
                   size 196643
                   title Executable Files
                   state available
                fileset
                   tag doc
                   control_directory doc
                   size 19643
                   title Manual Pages
                   state available

       INFO File swm-1.0/catalog/dfiles/INFO
            control_file
              path INFO
              tag INFO
              size 92
            control_file
              path md5sum
              tag md5sum
              size 36
            control_file
              path adjunct_md5sum
              tag adjunct_md5sum
              size 36
            control_file
              path sig_header
              tag sig_header
              size 512
            control_file
              path signature
              tag signature
              size 512

       INFO File swm-1.0/catalog/gsoft_swm/bin/INFO
            control_file
              path INFO
              tag INFO
              size 337

            control_file
              path postinstall
              type f
              size 803
              cksum 3928827394
              mode 550
              uid 0
              gid 0
              owner root
              group root
              mtime 739080341

            control_file
              path configure
              type f
              size 432
              cksum 3934546394
              mode 550
              uid 0
              gid 0
              owner root
              group root
              mtime 739340771

            file
              path /usr/bin/swpackage
              type f
              size 80860
              cksum 3929827394
              mode 755
              uid 0
              gid 0
              owner root
              group root
              mtime 739080771

            file
              path /usr/bin/sw_build
              type f
              size 120860
              cksum 9894925524
              mode 755
              uid 0
              gid 0
              owner root
              group root
              mtime 7393808731

### SWBIS PSF CONVENTIONS

           This  section  describes attribute usage and conventions imposed by the
           swbis implementation.  Not all attributes are listed here.  Those  that
           are have important effects or particular interest.

       o Distribution Attributes
           The  standard  defines a limited set of attributes for the distribution
           object.  An expanded set is suggested by the informative annex  however
           a  conforming  implementation  is not required act on them.  The reason
           for this is a distribution may be acted upon by a conforming utility in
           such  a  way  that  attributes of the distribution become invalid.  For
           this reason, some attributes that refer  to  an  entire  "package"  [in
           other package managers] are referred from the product object and attain
           their broadened scope by the distributor's convention that  their  dis-
           tribution contains just one product.

           For example, the package NAME and VERSION are referred from the product
           tag and revision, not the  distribution's.   This  convention  supports
           multiple  products  in  a distribution and is consistent with the stan-
           dard.

           tag

                  tag is the short, file system friendly, name  of  the  distribu-
                  tion.   Providing  a  distribution  tag  is optional.  The swbis
                  implementation will use this as the [single] path name prefix if
                  there is no distribution.control_directory attribute.  A distri-
                  bution tag attribute and swpackage's response to it is an imple-
                  mentation  extension.  The leading package path can also be con-
                  trolled with the ''-W dir'' option.

           control_directory

                  control_directory, in a distribution  object,  is  the  constant
                  leading  package path.  Providing this attribute is optional.  A
                  distribution   control_directory   attribute   and   swpackage's
                  response  to  it  is  an  implementation extension.  The leading
                  package path can also be controlled with the ''-W dir''  option.
                  This  attribute  will  be generated by swpackage if not set in a
                  PSF.

       o Bundle Attributes
           A bundle defines a collection of products whether or not the  distribu-
           tion has all the products present.

           tag

                  tag  is  the  short,  file  system friendly, name of the bundle.
                  This value is used by the swbis implementation as  a  path  name
                  component  in  the  installed  software  catalog.   If it is not
                  present the product tag is used.

       o Product Attributes
           A product defines the software product.

           tag

                  tag is the short, file system friendly,  name  of  the  product.
                  This  value  is  used by the swbis implementation as a path name
                  component in the installed software catalog.   It  is  required.
                  The  swbis  implementation uses it in a way that is analogous to
                  the RPMTAG_NAME attribute.

           control_directory

                  Is the directory name in the distribution under which the  prod-
                  uct  contents  are  located.   This  value  has no affect on the
                  installed software catalog.  If it is not given in  a  PSF  then
                  the tag is used.

           revision

                  Is  the  product  revision.   It  should not contain a "RELEASE"
                  attribute part or other version suffix modifiers.  This value is
                  used by the swbis implementation as a path name component in the
                  installed software catalog.  It is required by swinstall.

           vendor_tag

                  This is a short identifying name of the  distributor  that  sup-
                  plied  the  product  and  associates  the vendor object from the
                  INDEX file.  This attribute is optional.  This  attribute  value
                  should strive to be unique among all distributors.  It is one of
                  the version distinguishing attributes of a product specified  by
                  the standard.  It is transfered into the installed_software cat-
                  alog (not as a path  name  component)  by  swinstall.   If  this
                  attribute exists there should also be a vendor object in the PSF
                  in the distribution object that has this tag.  This attribute is
                  assigned the value of RPMTAG_RELEASE by swpackage when translat-
                  ing an RPM.  In this capacity it serves to distinguish  products
                  with  the  same revision and tag from the same or different dis-
                  tributor.   It  most  closely  maps  to  the  RPMTAG_RELEASE  or
                  "debian_revision" attributes.

       o Fileset Attributes
           A fileset defines the fileset.

           tag

                  tag is the short, file system friendly, name of the fileset.  It
                  is required.

           control_directory

                  Is the directory name in the product  under  which  the  fileset
                  contents are located.  This value has no affect on the installed
                  software catalog.  If it is not given in a PSF then the  tag  is
                  used.

       o Example Source Package PSF
           This  PSF packages every file is current directory. It uses nil control
           directories so the package structure does  not  change  relative  to  a
           vanilla tarball.

            distribution
              description "fooit - a program from fooware
           that does everything."
              title "fooit - a really cool program"
              COPYING < /usr/local/fooware/legalstuff/COPYING
            vendor
              the_term_vendor_is_misleading false
              tag fooware
              title fooware Consultancy Services, Inc.
              description ""
            vendor
              the_term_vendor_is_misleading true
              tag myfixes1
              title Bug fixes, Set 1
              description "a place for more detailed description"
            product
              tag fooit
              control_directory ""
              revision 1.0
              vendor_tag myfixes1  # Matches the vendor object above
            fileset
               tag fooit-SOURCE
               control_directory ""
               directory .
               file *
               exclude catalog

       o Example Runtime (Binary) Package PSF
           This  is a sample PSF for a runtime package.  It implies multiple prod-
           ucts (e.g. sub-packages) using the  bundle.contents  attribute.   Since
           the  bundle  and product tags exist in a un-regulated namespace and are
           seen by end users they should be  carefully  chosen.    Note  that  the
           bundle  and  product have the same tag which may force downstream users
           to disambiguate using software selection syntax such as  fooit,bv=*  or
           fooit,pv=* .

            distribution
              description "fooit - a program from fooware
           that does everything."
              title "fooit - a really cool program"
              COPYING < /usr/local/fooware/legalstuff/COPYING

                vendor
                   the_term_vendor_is_misleading false
                   tag fooware
                   title fooware Consultancy Services, Inc.
                   description "Provider of the programs
            that do everything"

                vendor
                   the_term_vendor_is_misleading true
                    tag fw0
                    title fooware fixes
                    description "More fixes from the fooware users"

           #  Bundle definition:  Use a bundle
                bundle
                    tag fooit
                    vendor_tag fooware
                    contents fooit,v=fw0 fooit-devel fooit-doc

           #  Product definition:
                product
                    tag fooit   # This is the package name
                    revision 1.0 # This is the package version
                    vendor_tag fw0 # This is a release name e.g. RPMTAG_RELEASE
                    postinstall scripts/postinstall
                fileset
                     tag fooit-RUN
                     file doc/man/man1/fooit.1 /usr/man/man1/fooit.1
                     file src/fooit /usr/bin/fooit

### APPLICABLE STANDARDS

           IEEE  Std  1387.2-1995  (Identical to ISO 15068-2:1999), Open Group CAE
           C701.

### SEE ALSO

            XDSA C701 http://www.opengroup.org/publications/catalog/c701.htm
            swbisparse(1) -- An implementation extension parser utility.
            swcopy(8)
            swinstall(8)
            swpackage(5)
            swpackage(8)
            swverify(8)

### IDENTIFICATION

            Copyright (C) 2005 Jim Lowe
            Version: 0.481
            Date: 2006-02-15
            Copying Terms: GNU Free Documentation License

### BUGS

           None

                                                                             sw(5)

[ Index ] [ Back ]