sw(5)

Contents

NAME

       sw -- POSIX Software Packaging

SYNOPSIS

       Software Packaging Layout
       Software Definitions
       Extended Definitions
       Vendor 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 leading path  name  compo-
       nents  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 vendor-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 vendor distribution appear under these direc-
       tories 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.
          gnu_tar_format_options program_options            -b1    # 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  leading  path.   The  signature, sig_header,
       md5sum, and adjunct_md5sum  attributes  are  described  below  and  are
       stored as separate files in the dfiles directory.

   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
          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.  A INDEX and PSF files can contain ven-
       dor definitions.  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 vendor's development sys-
       tem where the swpackage utility will find the script.  The  keyword  is
       the  value of the tag attribute and tells the utilities when to execute
       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.

VENDOR 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 prede-
       termined [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
       vendor internal data unless released by the vendor.

       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
          o  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.

          o  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.

          o  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.

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

          o  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
             directory  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
            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
            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 vendor's convention that their distribu-
       tion 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 [constant] leading path 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 vendor that supplied the
              product.  This attribute  is  optional.   This  attribute  value
              should  strive to be unique among all vendors.  It is one of the
              version distinguishing attributes of a product specified by  the
              standard.   It is transfered into the installed_software catalog
              (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 ven-
              dor.   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"
          LICENSE < /usr/local/fooware/legalstuff/LICENSE
        vendor
          tag fooware
          title fooware Consultancy Services, Inc.
        product
          tag fooit
          control_directory ""
        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 bun-
       dle  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"
          LICENSE < /usr/local/fooware/legalstuff/LICENSE

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

            vendor
                tag fw0
                title fooware Packaging Services, Inc.
                description "fooware Re-packaging service"

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

       #  Product definition:
            product
                tag fooit
                revision 1.34.56
                vendor_tag fw0
                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) 2003 Jim Lowe
        Version: 0.443
        Date: 2005-05-05
        Copying Terms: GNU Free Documentation License

BUGS

       None



                                                                         sw(5)

[ Index ] [ Back ]