sw(5)									 sw(5)



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-
       digest' 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.
	  vendor_tag  tag	    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  vendor_tag  attribute  contains  the  vendor.tag  of  the
       upstream distributor.  The qualifier attribute value  may  be  one  of:
       seller,	author,  packager,  maintainer.   A distribution may have more
       than one vendor definition.  They may form a chain of  references  from
       the  product.vendor_tag	to  the  last  vendor  referred to by the ven-
       dor.vendor_tag attributes.


   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.

       The  product.vendor_tag	refers	to  the  downstream distributor.  This
       value is be the	analogous  to  the  RPMTAG_RELEASE  or	debian_release
       attributes.  The original upstream author's package, for example, would
       not use this attribute because that package would not  have  a  release
       part  in its name, but could (or should) provide a vendor object in the
       PSF.


   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	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
       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
	  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 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"
	  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.499
	Last Updated: 2006-01
	Copying Terms: GNU Free Documentation License

BUGS
       None



									 sw(5)
