swpackage(5)							  swpackage(5)



NAME
       swpackage -- file formats

SYNOPSIS
       Output format - Data Interchange Formats
       Input format - Product Specification File (PSF)

SWPACKAGE OUTPUT FORMAT
       The  output  format  is	either one of two formats specified in POSIX.1
       (ISO/IEC 9945-1) which are tar (header  magic=ustar)  or  cpio  (header
       magic=070707).	The  default  format  of  the  swbis implementation is
       "ustar".  The POSIX spec under specifies definitions for  some  of  the
       ustar header fields.  The personality of the default swbis ustar format
       mimics GNU tar 1.15.1 and is designed to be compliant to POSIX.1.   The
       personality  of	the "ustar0" format mimics, for pathnames less than 99
       octets,	GNU tar 1.13.25 using the "-b1 --posix"  options.   This  bit-
       for-bit	sameness does not exist for pathnames greater than 99 chars as
       swbis follows the POSIX	spec  and  GNU	tar  1.13.25  does  not.   The
       "ustar0"  ustar personality is deprecated.  It is only slightly differ-
       ent from 'ustar' in how device number fields are filled	(with  spaces,
       zeros or NULs) for non-device files.

       In  addition  the swbis implementation supports several other tar vari-
       ants including bit-for-bit mimicry of GNU tar (1.13.25) default	format
       which  uses  a  non-standard name split and file type (type 'L').  This
       format is known as '--format=oldgnu'.  Also supported is the gnu format
       of GNU tar 1.15.1 specified by '--format=gnu'

       The  defacto  cpio  formats are also supported.	"new ASCII" (sometimes
       called SVR4 cpio) and "crc" cpio formats with header magic "070701" and
       "070702" respectively.

       Support for "pax Interchange Format" (Extended header tar) described in
       IEEE 1003.1-2001 under the "pax" manual page is planned.

       The entirety of the output byte stream is a single valid  file  of  one
       the formats mentioned above.

       The swbis implementation writes its output to stdout.  The default out-
       put block size is 10240 bytes.  The last block is not padded and there-
       fore  the  last write(2) may be a short write.  The selected block size
       does not affect the output file contents.

       The swbis implementation is biased, in terms of capability and  default
       settings,  to the tar format.  Package signing is only supported in tar
       format.

SWPACKAGE INPUT FILE FORMAT
       The input file is called a product specification file or PSF.  It  con-
       tains  information  to direct swpackage and information that is package
       meta-data [that is merely transferred unchanged into the  global  INDEX
       file].

       A PSF may contain object keywords, attributes (keyword/value pairs) and
       Extended Definitions (described below).	An object keyword  connotes  a
       logical object (i.e. software structure) supported by the standard.  An
       object keyword does not have a value field after  it,  as  it  contains
       Attributes  and	Extended Definitions.  An attribute keyword conotes an
       attribute which is always in the form of a keyword/value pair.

       Attribute keywords not recognized by the standard are allowed  and  are
       transferred into the INDEX file.  Object keywords not recognized by the
       standard are not allowed and will generate an error.  Extended  Defini-
       tions  may  only  appear  in a PSF (never in a INDEX or INFO created by
       swpackage).  Extended Definitions are translated  [by  swpackage]  into
       object keywords (objects) and attributes recognized by the standard.

       Comments  in a PSF are not transferred into the INDEX file by the swbis
       implementation of swpackage.

       The file syntax is the same as a INDEX, or INFO file.  A PSF  may  con-
       tain  all  objects  defined by the standard as well as extended defini-
       tions.

       For additional information see
       XDSA C701 http://www.opengroup.org/publications/catalog/c701.htm, or
       sw manual page.

   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.


   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
       POSIX.1, 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
	info swbis
	sw(5)
	swpackage(8)
	swbisparse(1) -- An implementation extension parser utility.

IDENTIFICATION
	Copyright (C) 2004,2005 Jim Lowe
	Version: 0.499
	Last Updated: 2006-07-01
	Copying Terms: GNU Free Documentation License

BUGS
       None



								  swpackage(5)
