<!-- 
Copyright (C) 2004 James Lowe, Jr.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or any
later version published by the Free Software Foundation; with no Invariant
Sections, with no Front-Cover Texts, and with no Back-Cover Texts.
<!DOCTYPE form
[
<!ENTITY swconventions SYSTEM "swpackage_conventions.sgml">
]>
-->
<TITLE>
SWBIS PSF CONVENTIONS
</TITLE>
<PARA>
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.
</PARA>
<REFSECT3>
<TITLE>
o Distribution Attributes
</TITLE>
<PARA>
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 <FUNCTION>distribution</FUNCTION> 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 distribution contains just one
<FUNCTION>product</FUNCTION>.
</PARA>
<PARA>
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 standard.
</PARA>

<PARA>
<OPTION>tag</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
<REPLACEABLE>tag</REPLACEABLE> is the short, file system friendly, name of the distribution.
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 distribution tag attribute and swpackage's response to it is an implementation extension.
The leading package path can also be controlled with the ''-W dir'' option. 
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>control_directory</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
<REPLACEABLE>control_directory</REPLACEABLE>, 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.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
</REFSECT3>

<REFSECT3>
<TITLE>
o Bundle Attributes
</TITLE>
<PARA>
A <FUNCTION>bundle</FUNCTION> defines a collection of products whether or not
the distribution has all the products present.
</PARA>

<PARA>
<OPTION>tag</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
<REPLACEABLE>tag</REPLACEABLE> 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.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
</REFSECT3>

<REFSECT3>
<TITLE>
o Product Attributes
</TITLE>
<PARA>
A <FUNCTION>product</FUNCTION> defines the software product.
</PARA>
<SBR>
<PARA>
<OPTION>tag</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
<REPLACEABLE>tag</REPLACEABLE> 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, namely as the public recognizable name of
the package.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>control_directory</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
Is the directory name in the distribution under which the product contents are located.
This value has no affect on the installed software catalog.  If it is not given in a PSF
then the
<REPLACEABLE>tag</REPLACEABLE> is used.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>revision</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
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.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>vendor_tag</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
This is a short identifying name of the distributor that supplied the product and
may associate (refer to) a <FUNCTION>vendor</FUNCTION> object from the INDEX file that
has a matching tag attribute.
This attribute is optional.
This attribute value should strive to be unique among all distributors. The swbis implementation
modifies the intended usage slightly as a string that strives to be globally unique for a given
product.<FUNCTION>tag</FUNCTION> and product.<FUNCTION>revision</FUNCTION>.
In this capacity it serves to distinguish products with the same revision and tag from the same or
different distributor.  It most closely maps to the RPMTAG_RELEASE or "debian_revision" attributes.
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
<OPTION>vendor</OPTION> object in the PSF in the distribution object that has this tag.
This attribute is assigned the value of RPMTAG_RELEASE by
swpackage when translating an RPM.
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>architecture</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
This string is one of the version attributes.  It is used to disambiguate
products that have the same <OPTION>tag</OPTION>, <OPTION>revision</OPTION>
and <OPTION>vendor_tag</OPTION>.  It is not used for determining a products
compatibility with a host.
The form is implementation defined.
swbis uses the output of GNU <FUNCTION>config.guess</FUNCTION> as the value of
this string.  A wildcard pattern should not be used.
The canonical swbis architecture string can be
listed with <FUNCTION>swlist</FUNCTION>. For example
<PROGRAMLISTING>
swlist -a architecture @ localhost
</PROGRAMLISTING>
Here are some example outputs from real systems.
<PROGRAMLISTING>
    System      `uname -srm`              architecture  
Red Hat 8.0:  Linux 2.4.18 i686        i686-pc-linux-gnu
OpenSolaris:  SunOS 5.11 i86pc         i386-pc-solaris2.11
NetBSD 3.1:   NetBSD 3.1 i386          i386-unknown-netbsdelf3.1
Red Hat 4.1:  Linux 2.0.36 i586        i586-pc-linux-gnulibc1
Debian 3.1:   Linux 2.6.8-2-386 i686   i686-pc-linux-gnu
</PROGRAMLISTING>
</GLOSSLIST>
</GLOSSLIST>
</PARA>

<PARA>
<OPTION>os_name</OPTION> 
<OPTION>os_release</OPTION> 
<OPTION>os_version</OPTION> 
<OPTION>machine_type</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
These attributes are used to determine compatibility with a host.
They correspond to the <FUNCTION>uname</FUNCTION> attributes defined by POSIX.1.
If an value is nil or non-existent it is assumed to match the host.
All attributes must match for there to be compatibility.  Distributors may
wish to make these values a shell pattern in their PSF's so to match
the intended collection of hosts.
swbis uses <FUNCTION>fnmatch</FUNCTION> (with FLAGS=0) to determine a match.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
</REFSECT3>

<REFSECT3>
<TITLE>
o Fileset Attributes
</TITLE>
<PARA>
A <FUNCTION>fileset</FUNCTION> defines the fileset.
</PARA>
<SBR>
<PARA>
<OPTION>tag</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
<REPLACEABLE>tag</REPLACEABLE> is the short, file system friendly, name of the fileset.
It is required although selection of filesets is  not yet supported therefore the end user
will have little to do with the fileset tag.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
<PARA>
<OPTION>control_directory</OPTION> 
<GLOSSLIST>
<GLOSSLIST> 
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
<REPLACEABLE>tag</REPLACEABLE> is used.
</GLOSSLIST>
</GLOSSLIST>
</PARA>
</REFSECT3>
<REFSECT3>
<TITLE>
o Example Source Package PSF
</TITLE>
<PARA>
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.
</PARA>
<PROGRAMLISTING><SBR>
 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
</PROGRAMLISTING>
</REFSECT3>

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