cde/admin/IntegTools/dbTools/UDB.format

   1
   2                         UDB     FILE    FORMAT
   3
   4         The udb (universal data base) format attempts to allow product delivery
   5         information for several closely related products to co-exist in the
   6         same database file.  This is an HP Corvallis home-grown format which
   7         was originally created to deal with the delivery of similar products
   8         on hp-ux, domain and osf platforms.
   9
  10         The format is meant to be more or less free form without regard to
  11         intervening newlines or whitespace. Comments violate this principle
  12         by being line oriented.  Any line whose first non-whitespace character
  13         is a '#' is considered a comment.  A semi-colon may be placed between
  14         two identifiers to break them up into separate tokens. If more than
  15         one keyword/value pair is placed on a line, semi-colons can be used
  16         to separate them visually. The semi-colons are ignored by the parser.
  17
  18         The special syntax characters ( "{",":",";","=","}") may be embedded
  19         in an identifier by escaping them with a backslash.
  20
  21 Semantic Note:
  22         The tools associated with the udb databases apply semantic meaning
  23         to seven kinds of information about a file.  There are seven Special
  24         Tokens which may be used to identify the keywords with which the
  25         semantic information should be associated.
  26
  27                 Special Token                    description
  28                 ------------                    -----------
  29                    <SRC>                The path (relative to the top of a
  30                                         build tree) to the source of a
  31                                         product deliverable file.
  32
  33                    <DEST>               The full destination path location of
  34                                         a deliverable file in the target
  35                                         machine's file system.
  36
  37                    <LNK>                The full path name (in the target
  38                                         machine's file system) of the source
  39                                         file for a symbolic link. (i.e. The file
  40                                         pointed to).
  41
  42                    <TYPE>               The kind of file object being installed.
  43                                         (i.e. file, sym_link, hard_link,
  44                                         directory, etc. )
  45
  46                    <MODE>               The (numeric) permissions assigned to
  47                                         the new object. This value should be
  48                                         in the usual octal notation.
  49
  50                    <OWNER>              The symbolic name of the owner of the
  51                                         new file.
  52
  53                    <GROUP>              The symbolic name of the group of the
  54                                         new file.
  55
  56         The hp-ux fileset databases have traditionally used the
  57         following keywords for these items:
  58
  59                 hpux keyword                    Special Token
  60                 ------------                    -----------
  61                 a_out_location :                    <SRC>
  62                 install_target :                    <DEST>
  63                 link_source :                       <LNK>
  64                 type :                              <TYPE>
  65                 mode :                              <MODE>
  66                 owner :                             <OWNER>
  67                 group :                             <GROUP>
  68
  69         The default for the udb databases is to associate the <SRC> semantics
  70         with the "a_out_location" keyword, the <DEST> semantics with the
  71         "install_target" keyword, etc.  This behavior may be modified by
  72         assigning a special token to a keyword in the Release Definition
  73         Section of the database file.
  74
  75
  76 General Format:
  77         A udb file has two sections.  First, a Release Definition Section,
  78         which describes the keyword pairs to be maintained for a given
  79         release stream and second, the individual file records for each
  80         file which is to be delivered.
  81
  82         1) Release Definition Section
  83
  84                 The Release Definition Section defines the keyword-value
  85                 pairs which are to be maintained for each release. The
  86                 release_id is an identifier which is used to identify the
  87                 set of defaults for a particular release.  The special
  88                 release_id of "default" is used specify the default set
  89                 of keyword/value pairs for an undefined release_id. The
  90                 values associated with keywords in this section provide
  91                 defaults for those keywords in later File Entries.
  92
  93                 The name and number of these pairs need not be the same for
  94                 all release streams.
  95         ------------------------------
  96         For example:
  97         The following entry in the Release Definition Section
  98
  99                 { hpux : defaults
 100                         src = <SRC>
 101                         dest = <DEST>
 102                         link_source =
 103                         type = file
 104                         perm = <MODE>
 105                         perm = 0555
 106                         owner = bin
 107                         group = bin
 108                         project = xwindows
 109                 }
 110
 111         defines the defaults for the "hpux" release stream.  It
 112         states that we should maintain information about src, dest, link_source,        type, perm, owner, group and project in the database.  Furthermore
 113         the semantics of <SRC> are to be associated with the keyword "src",
 114         <DEST> with "dest", link_source is associated with <LNK> by default,
 115         and type is associated with <TYPE> by default. Note that we associate
 116         perm with <MODE> semantics and supply a default value (0555) different
 117         from the automatic 0444 default. Owner and group have their usual
 118         meaning and a field called "project" is defined with a default value
 119         of "xwindows".  No semantic information is known about the "project"
 120         field but it's value will be maintained.
 121         -------------------------
 122
 123
 124         2) File Entries
 125                 After the Release Definition Section, come the entries for
 126            the deliverable files comprising the release.  The build-tree-top
 127            relative path name of a source file is followed by one or more
 128            destination specifications which describe where in the product
 129            this file should go, as well as the ownerships/permissions etc. that
 130            should be associated with it. Any missing keyword/value pairs will
 131            be filled in by the defaults provided in the Release Definition
 132            Section.
 133                 Information may differ between release
 134            streams.  If there is no destination spec for a given release and
 135            there is no "default" destination spec then that souce file will
 136            not be delivered for that release.  The "default" destination spec
 137            (if it exists) should come last and is applied for release streams
 138            that do not have more specific destination specs.
 139
 140            -------------------
 141            For example The following file entry:
 142
 143            cose/unity1/types/coe.vf
 144            { hp-ux
 145                 install_target = /usr/coe/newconfig/coe.vf
 146            }
 147            { aix
 148                 install_target = /usr/coe/types/coe.vf
 149            }
 150            { default
 151                 install_target = /var/coe/types/coe.vf
 152                 owner = sys
 153                 group = admin
 154            }
 155
 156            states that on hp-ux the file found at
 157            $(TOP)/cose/unity1/types/coe.vf in the build tree, is to be delivered
 158            to "/usr/coe/newconfig/coe.vf" on hp-ux; "/usr/coe/types/coe.vf" on
 159            aix; and "/var/coe/types/coe.vf" on all other release platforms.  In
 160            addition, on all platforms other than hp-ux and aix the default
 161            owner and group (usually bin,bin) are replaced by sys,admin for this
 162            file.
 163            ------------------
 164
 165 Pseudo-BNF:
 166         Here follows a pseudo-BNF description of the syntax of a
 167         udb file:
 168         ---------------------------------------------------------------------
 169
 170         udbFile = release_definition_section file_records
 171
 172         release_definition_section = release_def  release_definition_section |
 173                                      release_def
 174
 175         release_def = "{" release_id ":" "defaults" record_defs "}"
 176
 177         release_id = "hp-ux" | "aix" | "sun" | "usl" | "uxp" | "default"
 178
 179         record_defs = keyword_def "=" special_token |
 180                       keyword_def "=" keyword_value
 181
 182         special_token  = "<SRC>" | "<DEST>" | "<LNK>" |
 183                       "<TYPE>" | "<MODE>" | "<OWNER>" | "<GROUP>"
 184
 185         keyword_def = identifier
 186         keyword_value = identifier
 187
 188         file_records =  file_rec file_records |
 189                         file_rec
 190
 191         file_rec = src_spec dest_specs
 192
 193         src_spec = a_out_loc | link_path
 194
 195         a_out_loc = < the build tree-top relative path to the source file >
 196
 197         link_path = < the full path to the link source in the product >
 198
 199         dest_specs = dest_spec dest_specs |
 200                         dest_spec
 201
 202         dest_spec = "{" release_id  value_specs "}"
 203
 204
 205         value_spec = keyword "=" value
 206
 207         keyword = identifier
 208         value   = identifier
 209
 210         identifier = < any sequence of non-whitespace characters which
 211                    does not contain an unescaped instance of one of
 212                    the syntax_chars >
 213
 214         syntax_chars = "{", ":", ";", "=", "}"
 215
 216