Changes between Version 2 and Version 3 of Obsolete/MovedToTree/PackageManagement/FileFormat


Ignore:
Timestamp:
Feb 15, 2011, 6:08:15 PM (9 years ago)
Author:
zooey
Comment:

Added package format description, repository format description and updated with current state of implementation

Legend:

Unmodified
Added
Removed
Modified
  • Obsolete/MovedToTree/PackageManagement/FileFormat

    v2 v3  
    4444        uint32  attributes_length_compressed;
    4545        uint32  attributes_length_uncompressed;
     46        uint32  attributes_strings_length;
     47        uint32  attributes_strings_count;
    4648
    4749        // TOC section
     
    4951        uint64  toc_length_compressed;
    5052        uint64  toc_length_uncompressed;
    51 
    52         uint64  toc_attribute_types_length;
    53         uint64  toc_attribute_types_count;
    5453        uint64  toc_strings_length;
    5554        uint64  toc_strings_count;
     
    7473 attributes_length_uncompressed::
    7574   The uncompressed size of the package attributes section.
     75 attributes_strings_length::
     76   The size of the strings subsection of the package attributes section.
     77 attributes_strings_count::
     78   The number of entries in the strings subsection of the package attributes section.
    7679
    7780 toc_compression::
     
    8285 toc_length_uncompressed::
    8386   The uncompressed size of the TOC section.
    84 
    85  toc_attribute_types_length::
    86    The size of the attributes types subsection of the TOC section.
    87  toc_attribute_types_count::
    88    The number of entries in the attributes types subsection of the TOC section.
    8987 toc_strings_length::
    9088   The size of the strings subsection of the TOC section.
     
    9593=== TOC ===
    9694
    97 The TOC section contains a list of attribute trees. An attribute has a name, a data type, and a value, and can have child attributes. E.g.:
    98  - "shopping list" : string : "bakery"
    99    - "item" : string : "rye bread"
    100    - "item" : string : "bread roll"
    101      - "count" : int : 10
    102    - "item" : string : "cookie"
    103      - "count" : int : 5
    104  - "shopping list" : string : "hardware store"
    105    - "item" : string : "hammer"
    106    - "item" : string : "nail"
    107      - "size" : int : 10
    108      - "count" : int : 100
    109 
    110 Attributes often share the same name and data type, particularly when lists of some kind are stored. In order to save space each unique name and data type pair is stored as an attribute type in a separate subsection and is referenced by an index.
    111 
    112 A similar optimization exists for shared string attribute values. A string value used by more than one attribute is stored in the strings subsection and is referenced by an index as well.
    113 
    114 Hence the TOC section consists of three subsections:
    115  Attribute types::
    116    A table of attribute name, data type pairs.
     95The TOC section contains a list of attribute trees. An attribute has an ID, a data type, and a value, and can have child attributes. E.g.:
     96 - ATTRIBUTE_ID_SHOPPING_LIST : string : "bakery"
     97   - ATTRIBUTE_ID_ITEM : string : "rye bread"
     98   - ATTRIBUTE_ID_ITEM : string : "bread roll"
     99     - ATTRIBUTE_ID_COUNT : int : 10
     100   - ATTRIBUTE_ID_ITEM : string : "cookie"
     101     - ATTRIBUTE_ID_COUNT : int : 5
     102 - ATTRIBUTE_ID_SHOPPING_LIST : string : "hardware store"
     103   - ATTRIBUTE_ID_ITEM : string : "hammer"
     104   - ATTRIBUTE_ID_ITEM : string : "nail"
     105     - ATTRIBUTE_ID_SIZE : int : 10
     106     - ATTRIBUTE_ID_COUNT : int : 100
     107
     108The main TOC section refers to any attribute by its unique ID (see below) and stores the attribute's value, either as a reference into the heap or as inline data.
     109
     110An optimization exists for shared string attribute values. A string value used by more than one attribute is stored in the strings subsection and is referenced by an index.
     111
     112Hence the TOC section consists of two subsections:
    117113 Strings::
    118114   A table of commonly used strings.
     
    120116   The attribute trees.
    121117
    122 ==== Attribute Types ====
    123 
    124 The attribute types subsection consists of a list of attribute type entries terminated by a 0 byte. An attribute type entry is stored as:
    125  Attribute data type::
    126    A uint8 specifying the data type.
    127  Attribute name::
    128    A null-terminated UTF-8 string.
    129 
    130 These are the specified data type values:
     118==== Attribute Data Types ====
     119
     120These are the specified data type values for attributes:
    131121||0||B_HPKG_ATTRIBUTE_TYPE_INVALID||invalid||
    132122||1||B_HPKG_ATTRIBUTE_TYPE_INT||signed integer||
     
    134124||3||B_HPKG_ATTRIBUTE_TYPE_STRING||UTF-8 string||
    135125||4||B_HPKG_ATTRIBUTE_TYPE_RAW||raw data||
    136 
    137 Each attribute type is implicity assigned the (null-based) index at which the respective entry appears in the list, i.e. the nth entry has the index n - 1. The attribute is referenced by this index in the main TOC subsection.
    138126
    139127==== Strings ====
     
    154142   entries terminated by a 0 byte.
    155143
    156 The attribute tag encodes three pieces of information:
    157   {{{(typeIndex << 3) + (encoding << 1) + hasChildren + 1}}}
    158 
    159  typeIndex::
    160    The index of the attribute type.
     144The attribute tag encodes four pieces of information:
     145  {{{(encoding << 10) + (hasChildren << 9) + (dataType << 6) + id + 1}}}
     146
    161147 encoding::
    162148   Specifies the encoding of the attribute value as described below.
    163149 hasChildren::
    164150   1, if the attribute has children, 0 otherwise.
     151 dataType::
     152   The data type of the attribute (B_HPKG_ATTRIBUTE_TYPE_...).
     153 id::
     154   The ID of the attribute (B_HPKG_ATTRIBUTE_ID_...).
    165155
    166156==== Attribute Values ====
     
    189179
    190180The package attributes section contains a list of attribute trees, just like
    191 the TOC section. Since the purpose of the section is to store meta data of the package as a whole, it will be relatively small and less repetitive (no or only short item lists). Therefore this section does not have attribute types and strings subsections. It directly stores a list of self contained attribute entries terminated by a 0 byte. An entry has the following format:
    192  Attribute data type::
    193    A uint8 specifying the data type of the attribute value.
    194  Has children::
    195    A uint8: non 0, if the attribute has children, 0 otherwise.
    196  Attribute name::
    197    A null-terminated UTF-8 string.
    198  Attribute value::
    199    The value of the attribute encoded as described in the Main TOC section.
    200  Attribute child list::
    201    Only if this attribute is marked to have children: A list of attribute
    202    entries terminated by a 0 byte.
     181the TOC section. The structure of this section follows the TOC, i.e. there's a subsection for shared strings and a subsection that stores a list of attribute entries terminated by a 0 byte. An entry has the same format as the ones in the TOC (only using different attribute IDs).
    203182
    204183
     
    223202}}}
    224203could be represented by this attribute tree:
    225  - "dir:entry" : string : "bin"
    226   - "file:type" : uint : 1 (0x1)
    227   - "file:mtime" : uint : 1258110729 (0x4afd3f09)
    228   - "dir:entry" : string : "awk"
    229     - "file:type" : uint : 2 (0x2)
    230     - "file:mtime" : uint : 1258110676 (0x4afd3ed4)
    231     - "symlink:path" : string : "gawk"
    232   - "dir:entry" : string : "gawk"
    233     - "file:permissions" : uint : 493 (0x1ed)
    234     - "file:mtime" : uint : 1258110676 (0x4afd3ed4)
    235     - "data" : raw : size: 301699, offset: 0
    236     - "file:attribute" : string : "BEOS:APP_VERSION"
    237       - "file:attribute:type" : uint : 1095782486 (0x41505056)
    238       - "data" : raw : size: 680, offset: 301699
    239     - "file:attribute" : string : "BEOS:TYPE"
    240       - "file:attribute:type" : uint : 1296649555 (0x4d494d53)
    241       - "data" : raw : size: 35, offset: 302379
    242 
    243 
    244 === Attribute Types ===
    245 
    246 The following attribute types are specified by the archive format. Any other attributes will be ignored.
    247 
    248 ==== B_HPKG_ATTRIBUTE_NAME_DIRECTORY_ENTRY ("dir:entry") ====
     204 - B_HPKG_ATTRIBUTE_ID_DIR_ENTRY : string : "bin"
     205  - B_HPKG_ATTRIBUTE_ID_FILE_TYPE : uint : 1 (0x1)
     206  - B_HPKG_ATTRIBUTE_ID_FILE_MTIME : uint : 1258110729 (0x4afd3f09)
     207  - B_HPKG_ATTRIBUTE_ID_DIR_ENTRY : string : "awk"
     208    - B_HPKG_ATTRIBUTE_ID_FILE_TYPE : uint : 2 (0x2)
     209    - B_HPKG_ATTRIBUTE_ID_FILE_MTIME : uint : 1258110676 (0x4afd3ed4)
     210    - B_HPKG_ATTRIBUTE_ID_SYMLINK_PATH : string : "gawk"
     211  - B_HPKG_ATTRIBUTE_ID_DIR_ENTRY : string : "gawk"
     212    - B_HPKG_ATTRIBUTE_ID_FILE_PERMISSIONS : uint : 493 (0x1ed)
     213    - B_HPKG_ATTRIBUTE_ID_FILE_MTIME : uint : 1258110676 (0x4afd3ed4)
     214    - B_HPKG_ATTRIBUTE_ID_DATA : raw : size: 301699, offset: 0
     215    - B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE : string : "BEOS:APP_VERSION"
     216      - B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE : uint : 1095782486 (0x41505056)
     217      - B_HPKG_ATTRIBUTE_ID_DATA : raw : size: 680, offset: 301699
     218    - B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE : string : "BEOS:TYPE"
     219      - B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE : uint : 1296649555 (0x4d494d53)
     220      - B_HPKG_ATTRIBUTE_ID_DATA : raw : size: 35, offset: 302379
     221
     222
     223=== Attribute IDs ===
     224
     225The following attribute IDs are specified by the archive format. Any other attributes will be ignored.
     226
     227==== B_HPKG_ATTRIBUTE_ID_DIRECTORY_ENTRY ("dir:entry") ====
    249228 - '''Type:''' string
    250229 - '''Value:''' File name of the entry.
    251230 - '''Allowed Values:''' Any valid file (not path!) name, save "." and "..".
    252231 - '''Child Attributes:'''
    253    - B_HPKG_ATTRIBUTE_NAME_FILE_TYPE: The file type of the entry.
    254    - B_HPKG_ATTRIBUTE_NAME_FILE_PERMISSIONS: The file permissions of the entry.
    255    - B_HPKG_ATTRIBUTE_NAME_FILE_USER: The owning user of the entry.
    256    - B_HPKG_ATTRIBUTE_NAME_FILE_GROUP: The owning group of the entry.
    257    - B_HPKG_ATTRIBUTE_NAME_FILE_ATIME[_NANOS]: The entry's file access time.
    258    - B_HPKG_ATTRIBUTE_NAME_FILE_MTIME[_NANOS]: The entry's file modification time.
    259    - B_HPKG_ATTRIBUTE_NAME_FILE_CRTIME[_NANOS]: The entry's file creation time.
    260    - B_HPKG_ATTRIBUTE_NAME_FILE_ATTRIBUTE: An extended file attribute associated with entry.
    261    - B_HPKG_ATTRIBUTE_NAME_DATA: Only if the entry is a file: The file data.
    262    - B_HPKG_ATTRIBUTE_NAME_SYMLINK_PATH: Only if the entry is a symlink: The path the symlink points to.
    263    - B_HPKG_ATTRIBUTE_NAME_DIRECTORY_ENTRY: Only if the entry is a directory: A child entry in that directory.
    264 
    265 ==== B_HPKG_ATTRIBUTE_NAME_FILE_TYPE ("file:type") ====
     232   - B_HPKG_ATTRIBUTE_ID_FILE_TYPE: The file type of the entry.
     233   - B_HPKG_ATTRIBUTE_ID_FILE_PERMISSIONS: The file permissions of the entry.
     234   - B_HPKG_ATTRIBUTE_ID_FILE_USER: The owning user of the entry.
     235   - B_HPKG_ATTRIBUTE_ID_FILE_GROUP: The owning group of the entry.
     236   - B_HPKG_ATTRIBUTE_ID_FILE_ATIME[_NANOS]: The entry's file access time.
     237   - B_HPKG_ATTRIBUTE_ID_FILE_MTIME[_NANOS]: The entry's file modification time.
     238   - B_HPKG_ATTRIBUTE_ID_FILE_CRTIME[_NANOS]: The entry's file creation time.
     239   - B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE: An extended file attribute associated with entry.
     240   - B_HPKG_ATTRIBUTE_ID_DATA: Only if the entry is a file: The file data.
     241   - B_HPKG_ATTRIBUTE_ID_SYMLINK_PATH: Only if the entry is a symlink: The path the symlink points to.
     242   - B_HPKG_ATTRIBUTE_ID_DIRECTORY_ENTRY: Only if the entry is a directory: A child entry in that directory.
     243
     244==== B_HPKG_ATTRIBUTE_ID_FILE_TYPE ("file:type") ====
    266245 - '''Type:''' uint
    267246 - '''Value:''' Type of the entry.
     
    274253 - '''Child Attributes:''' none
    275254
    276 ==== B_HPKG_ATTRIBUTE_NAME_FILE_PERMISSIONS ("file:permissions") ====
     255==== B_HPKG_ATTRIBUTE_ID_FILE_PERMISSIONS ("file:permissions") ====
    277256 - '''Type:''' uint
    278257 - '''Value:''' File permissions.
     
    284263 - '''Child Attributes:''' none
    285264
    286 ==== B_HPKG_ATTRIBUTE_NAME_FILE_USER ("file:user") ====
     265==== B_HPKG_ATTRIBUTE_ID_FILE_USER ("file:user") ====
    287266 - '''Type:''' string
    288267 - '''Value:''' Name of the user owning the file.
     
    290269 - '''Child Attributes:''' none
    291270
    292 ==== B_HPKG_ATTRIBUTE_NAME_FILE_GROUP ("file:group") ====
     271==== B_HPKG_ATTRIBUTE_ID_FILE_GROUP ("file:group") ====
    293272 - '''Type:''' string
    294273 - '''Value:''' Name of the group owning the file.
     
    296275 - '''Child Attributes:''' none
    297276
    298 ==== B_HPKG_ATTRIBUTE_NAME_FILE_ATIME ("file:atime") ====
     277==== B_HPKG_ATTRIBUTE_ID_FILE_ATIME ("file:atime") ====
    299278 - '''Type:''' uint
    300279 - '''Value:''' File access time (seconds since the Epoch).
     
    302281 - '''Child Attributes:''' none
    303282
    304 ==== B_HPKG_ATTRIBUTE_NAME_FILE_ATIME_NANOS ("file:mtime:nanos") ====
     283==== B_HPKG_ATTRIBUTE_ID_FILE_ATIME_NANOS ("file:mtime:nanos") ====
    305284 - '''Type:''' uint
    306285 - '''Value:''' The nano seconds fraction of the file access time.
     
    309288 - '''Child Attributes:''' none
    310289
    311 ==== B_HPKG_ATTRIBUTE_NAME_FILE_MTIME ("file:mtime") ====
     290==== B_HPKG_ATTRIBUTE_ID_FILE_MTIME ("file:mtime") ====
    312291 - '''Type:''' uint
    313292 - '''Value:''' File modified time (seconds since the Epoch).
     
    315294 - '''Child Attributes:''' none
    316295
    317 ==== B_HPKG_ATTRIBUTE_NAME_FILE_MTIME_NANOS ("file:mtime:nanos") ====
     296==== B_HPKG_ATTRIBUTE_ID_FILE_MTIME_NANOS ("file:mtime:nanos") ====
    318297 - '''Type:''' uint
    319298 - '''Value:''' The nano seconds fraction of the file modified time.
     
    322301 - '''Child Attributes:''' none
    323302
    324 ==== B_HPKG_ATTRIBUTE_NAME_FILE_CRTIME ("file:crtime") ====
     303==== B_HPKG_ATTRIBUTE_ID_FILE_CRTIME ("file:crtime") ====
    325304 - '''Type:''' uint
    326305 - '''Value:''' File creation time (seconds since the Epoch).
     
    328307 - '''Child Attributes:''' none
    329308
    330 ==== B_HPKG_ATTRIBUTE_NAME_FILE_CRTIM_NANOS ("file:crtime:nanos") ====
     309==== B_HPKG_ATTRIBUTE_ID_FILE_CRTIM_NANOS ("file:crtime:nanos") ====
    331310 - '''Type:''' uint
    332311 - '''Value:''' The nano seconds fraction of the file creation time.
     
    335314 - '''Child Attributes:''' none
    336315
    337 ==== B_HPKG_ATTRIBUTE_NAME_FILE_ATTRIBUTE ("file:attribute") ====
     316==== B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE ("file:attribute") ====
    338317 - '''Type:''' string
    339318 - '''Value:''' Name of the extended file attribute.
    340319 - '''Allowed Values:''' Any valid attribute name.
    341320 - '''Child Attributes:'''
    342    - B_HPKG_ATTRIBUTE_NAME_FILE_ATTRIBUTE_TYPE: The type of the file attribute.
    343    - B_HPKG_ATTRIBUTE_NAME_DATA: The file attribute data.
    344 
    345 ==== B_HPKG_ATTRIBUTE_NAME_FILE_ATTRIBUTE_TYPE ("file:attribute:type") ====
     321   - B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE: The type of the file attribute.
     322   - B_HPKG_ATTRIBUTE_ID_DATA: The file attribute data.
     323
     324==== B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE ("file:attribute:type") ====
    346325 - '''Type:''' uint
    347326 - '''Value:''' Type of the file attribute.
     
    349328 - '''Child Attributes:''' none
    350329
    351 ==== B_HPKG_ATTRIBUTE_NAME_DATA ("data") ====
     330==== B_HPKG_ATTRIBUTE_ID_DATA ("data") ====
    352331 - '''Type:''' data
    353332 - '''Value:''' Raw data of a file or attribute.
    354333 - '''Allowed Values:''' Any value, if uncompressed, otherwise see below.
    355334 - '''Child Attributes:'''
    356    - B_HPKG_ATTRIBUTE_NAME_DATA_COMPRESSION: The compression algorithm used for
     335   - B_HPKG_ATTRIBUTE_ID_DATA_COMPRESSION: The compression algorithm used for
    357336     storing the data.
    358    - B_HPKG_ATTRIBUTE_NAME_DATA_SIZE: The size of the uncompressed data.
    359    - B_HPKG_ATTRIBUTE_NAME_DATA_CHUNK_SIZE: The size of an uncompressed data chunk.
    360 
    361 ==== B_HPKG_ATTRIBUTE_NAME_DATA_COMPRESSION ("data:compression") ====
     337   - B_HPKG_ATTRIBUTE_ID_DATA_SIZE: The size of the uncompressed data.
     338   - B_HPKG_ATTRIBUTE_ID_DATA_CHUNK_SIZE: The size of an uncompressed data chunk.
     339
     340==== B_HPKG_ATTRIBUTE_ID_DATA_COMPRESSION ("data:compression") ====
    362341 - '''Type:''' uint
    363342 - '''Value:''' ID of the data compression algorithm.
     
    369348 - '''Child Attributes:''' none
    370349
    371 ==== B_HPKG_ATTRIBUTE_NAME_DATA_SIZE ("data:size") ====
     350==== B_HPKG_ATTRIBUTE_ID_DATA_SIZE ("data:size") ====
    372351 - '''Type:''' uint
    373352 - '''Value:''' Size of the uncompressed data.
     
    376355 - '''Child Attributes:''' none
    377356
    378 ==== B_HPKG_ATTRIBUTE_NAME_DATA_CHUNK_SIZE ("data:chunk_size") ====
     357==== B_HPKG_ATTRIBUTE_ID_DATA_CHUNK_SIZE ("data:chunk_size") ====
    379358 - '''Type:''' uint
    380359 - '''Value:''' Size of an uncompressed data chunk.
     
    385364 - '''Child Attributes:''' none
    386365
    387 ==== B_HPKG_ATTRIBUTE_NAME_SYMLINK_PATH ("symlink:path") ====
     366==== B_HPKG_ATTRIBUTE_ID_SYMLINK_PATH ("symlink:path") ====
    388367 - '''Type:''' string
    389368 - '''Value:''' The path the symlink refers to.
     
    395374=== TOC Attributes ===
    396375
    397 The TOC can directly contain any number of attributes of the B_HPKG_ATTRIBUTE_NAME_DIRECTORY_ENTRY type, which in turn contain descendent attributes as specified in the previous section. Any other attributes are ignored.
     376The TOC can directly contain any number of attributes of the B_HPKG_ATTRIBUTE_ID_DIRECTORY_ENTRY type, which in turn contain descendent attributes as specified in the previous section. Any other attributes are ignored.
    398377
    399378
    400379=== Data Compression ===
    401380
    402 Data referred to by an B_HPKG_ATTRIBUTE_NAME_DATA attribute will be the raw data, if uncompressed. If compressed, the data have a special format, that allows for fast random access.
     381Data referred to by an B_HPKG_ATTRIBUTE_ID_DATA attribute will be the raw data, if uncompressed. If compressed, the data have a special format, that allows for fast random access.
    403382
    404383==== B_HPKG_COMPRESSION_ZLIB ====
     
    411390== The Package Format ==
    412391
    413 TODO...
     392This section specifies how informative package attributes (package-name, version, provides, requires, ...) are stored in a HPKG file. It builds on top of the container format, defining the types of attributes, their order, and allowed values.
     393
     394E.g. a ".PackageInfo" file, containing a package description that is being converted into a package file:
     395{{{
     396name = mypackage
     397version = 0.7.2-1
     398architecture = x86
     399summary = "is a very nice package"
     400description = "has lots of cool features\nand is written in MyC++"
     401vendor = "Me, Myself & I, Inc."
     402packager = "me@test.com"
     403copyrights = [ "(C) 2009-2011, Me, Myself & I, Inc." ]
     404licenses = [ "Me, Myself & I Commercial License", "MIT" ]
     405provides = [
     406        cmd:me
     407        lib:libmyself = 0.7
     408]
     409requires = [
     410        haiku >= r1
     411        wget
     412]
     413}}}
     414could be represented by this attribute tree:
     415 - B_HPKG_ATTRIBUTE_ID_PACKAGE_NAME : string : "mypackage"
     416 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR : string : "0"
     417   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR : string : "7"
     418   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO : string : "2"
     419   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_RELEASE : uint : 1
     420 - B_HPKG_ATTRIBUTE_ID_PACKAGE_ARCHITECTURE : uint : 1
     421 - B_HPKG_ATTRIBUTE_ID_PACKAGE_SUMMARY : string : "is a very nice package"
     422 - B_HPKG_ATTRIBUTE_ID_PACKAGE_DESCRIPTION : string : "has lots of cool features\nand is written in MyC++"
     423 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VENDOR : string : "Me, Myself & I, Inc."
     424 - B_HPKG_ATTRIBUTE_ID_PACKAGE_PACKAGER : string : "me@test.com"
     425 - B_HPKG_ATTRIBUTE_ID_PACKAGE_COPYRIGHT : string : "(C) 2009-2011, Me, Myself & I, Inc."
     426 - B_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE : string : "Me, Myself & I Commercial License"
     427 - B_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE : string : "MIT"
     428 - B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES : string : "cmd:me"
     429   - B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES_TYPE : uint : 2
     430 - B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES : string : "lib:libmyself"
     431   - B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES_TYPE : uint : 1
     432   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR : string : "0"
     433     - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR : string : "7"
     434 - B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES : string : "haiku"
     435   - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR : uint : 4
     436   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR : string : "r1"
     437 - B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES : string : "wget"
     438
     439
     440=== Attribute IDs ===
     441
     442The following attribute IDs are specified by the package format. Any other attributes will be rejected.
     443
     444==== B_HPKG_ATTRIBUTE_ID_PACKAGE_NAME ("package:name") ====
     445 - '''Type:''' string
     446 - '''Value:''' Name of the package.
     447 - '''Allowed Values:''' Any name composed of <alphanum_underline> (i.e. [a-zA-Z0-9_]).
     448 - '''Child Attributes:''' none
     449
     450==== B_HPKG_ATTRIBUTE_ID_PACKAGE_SUMMARY ("package:summary") ====
     451 - '''Type:''' string
     452 - '''Value:''' Short description of the package.
     453 - '''Allowed Values:''' Any single-lined string.
     454 - '''Child Attributes:''' none
     455
     456==== B_HPKG_ATTRIBUTE_ID_PACKAGE_DESCRIPTION ("package:description") ====
     457 - '''Type:''' string
     458 - '''Value:''' Long description of the package.
     459 - '''Allowed Values:''' Any string (may contain multiple lines).
     460 - '''Child Attributes:''' none
     461
     462==== B_HPKG_ATTRIBUTE_ID_PACKAGE_VENDOR ("package:vendor") ====
     463 - '''Type:''' string
     464 - '''Value:''' Name of the person/organization that is publishing this package.
     465 - '''Allowed Values:''' Any single-lined string.
     466 - '''Child Attributes:''' none
     467
     468==== B_HPKG_ATTRIBUTE_ID_PACKAGE_PACKAGER ("package:packager") ====
     469 - '''Type:''' string
     470 - '''Value:''' E-Mail of person that created this package.
     471 - '''Allowed Values:''' Any single-lined string, but e-mail preferred.
     472 - '''Child Attributes:''' none
     473
     474==== B_HPKG_ATTRIBUTE_ID_PACKAGE_FLAGS ("package:flags") ====
     475 - '''Type:''' uint
     476 - '''Value:''' Set of boolean flags applying to package.
     477 - '''Allowed Values:''' Any combination of the following.
     478
     479   ||1||B_PACKAGE_FLAG_APPROVE_LICENSE||this package's license requires approval (i.e. must be shown to and acknowledged by user before installation)||
     480   ||2||B_PACKAGE_FLAG_SYSTEM_PACKAGE||this is a system package (i.e. lives under /boot/system)||
     481 - '''Default Value:''' 0.
     482 - '''Child Attributes:''' none
     483
     484==== B_HPKG_ATTRIBUTE_ID_PACKAGE_ARCHITECTURE ("package:architecture") ====
     485 - '''Type:''' uint
     486 - '''Value:''' System architecture this package was built for.
     487 - '''Allowed Values:'''
     488
     489   ||0||B_PACKAGE_ARCHITECTURE_ANY||this package doesn't depend on the system architecture||
     490   ||1||B_PACKAGE_ARCHITECTURE_X86||x86, 32-bit, built with gcc4||
     491   ||2||B_PACKAGE_ARCHITECTURE_X86_GCC2||x86, 32-bit, built with gcc2||
     492 - '''Child Attributes:''' none
     493
     494==== B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR ("package:version.major") ====
     495 - '''Type:''' string
     496 - '''Value:''' Major (first) part of package version.
     497 - '''Allowed Values:''' Any single-lined string, composed of <alphanum_underline>
     498 - '''Child Attributes:'''
     499   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR: The minor part of the package version.
     500   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO: The micro part of the package version.
     501   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_RELEASE: The release part of the package version.
     502
     503==== B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR ("package:version.minor") ====
     504 - '''Type:''' string
     505 - '''Value:''' Minor (second) part of package version.
     506 - '''Allowed Values:''' Any single-lined string, composed of <alphanum_underline>
     507 - '''Child Attributes:''' none
     508
     509==== B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO ("package:version.micro") ====
     510 - '''Type:''' string
     511 - '''Value:''' Micro (third) part of package version.
     512 - '''Allowed Values:''' Any single-lined string, composed of <alphanum_underline>
     513 - '''Child Attributes:''' none
     514
     515==== B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_RELEASE ("package:version.release") ====
     516 - '''Type:''' string
     517 - '''Value:''' Release (fourth) part of package version.
     518 - '''Allowed Values:''' Any single-lined string, composed of <alphanum_underline>
     519 - '''Child Attributes:''' none
     520
     521==== B_HPKG_ATTRIBUTE_ID_PACKAGE_COPYRIGHT ("package:copyright") ====
     522 - '''Type:''' string
     523 - '''Value:''' Copyright applying to the software contained in this package.
     524 - '''Allowed Values:''' Any (preferably single-lined) string.
     525 - '''Child Attributes:''' none
     526
     527==== B_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE ("package:license") ====
     528 - '''Type:''' string
     529 - '''Value:''' Name of license applying to the software contained in this package.
     530 - '''Allowed Values:''' Any single-lined string.
     531 - '''Child Attributes:''' none
     532
     533==== B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES ("package:provides") ====
     534 - '''Type:''' string
     535 - '''Value:''' Name of a (optionally typed) entity that is being provided by this package.
     536 - '''Allowed Values:''' Any string matching [ <alphanum-underline> ':' ] <alphanum_underline>.
     537 - '''Child Attributes:''' none
     538   - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_TYPE: The resolvable type as int.
     539   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable version.
     540
     541==== B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES_TYPE ("package:provides.type") ====
     542 - '''Type:''' uint
     543 - '''Value:''' Type of resolvable.
     544 - '''Allowed Values:'''
     545
     546   ||0||B_PACKAGE_RESOLVABLE_TYPE_DEFAULT||this resolvable isn't typed ()||
     547   ||1||B_PACKAGE_RESOLVABLE_TYPE_LIBRARY||this resolvable represents a library ('lib:')||
     548   ||2||B_PACKAGE_RESOLVABLE_TYPE_COMMAND||this resolvable represents a console command ('cmd:')||
     549   ||3||B_PACKAGE_RESOLVABLE_TYPE_APPLICATION||this resolvable represents an application ('app:')||
     550   ||4||B_PACKAGE_RESOLVABLE_TYPE_ADD_ON||this resolvable represents an add-on ('add-on:')||
     551 - '''Child Attributes:''' none
     552
     553==== B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES ("package:requires") ====
     554 - '''Type:''' string
     555 - '''Value:''' Name of an entity that is required by this package (and hopefully being provided by another).
     556 - '''Allowed Values:''' Any string matching [ <alphanum-underline> ':' ] <alphanum_underline>.
     557 - '''Child Attributes:'''
     558   - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as int.
     559   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable version.
     560
     561==== B_HPKG_ATTRIBUTE_ID_PACKAGE_SUPPLEMENTS ("package:supplements") ====
     562 - '''Type:''' string
     563 - '''Value:''' Name of an entity that is supplemented by this package (i.e. this package will automatically be selected for installation if the supplemented resolvables are already installed).
     564 - '''Allowed Values:''' Any string matching [ <alphanum-underline> ':' ] <alphanum_underline>.
     565 - '''Child Attributes:'''
     566   - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as int.
     567   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable version.
     568
     569==== B_HPKG_ATTRIBUTE_ID_PACKAGE_CONFLICTS ("package:conflicts") ====
     570 - '''Type:''' string
     571 - '''Value:''' Name of an entity that this package conflicts with (i.e. only one of both can be installed at any time).
     572 - '''Allowed Values:''' Any string matching [ <alphanum-underline> ':' ] <alphanum_underline>.
     573 - '''Child Attributes:'''
     574   - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as int.
     575   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable version.
     576
     577==== B_HPKG_ATTRIBUTE_ID_PACKAGE_FRESHENS ("package:freshens") ====
     578 - '''Type:''' string
     579 - '''Value:''' Name of an entity that is being freshened by this package (i.e. this package will patch one or more files of the package that provide this resolvable).
     580 - '''Allowed Values:''' Any string matching [ <alphanum-underline> ':' ] <alphanum_underline>.
     581 - '''Child Attributes:'''
     582   - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as int.
     583   - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable version.
     584
     585==== B_HPKG_ATTRIBUTE_ID_PACKAGE_REPLACES ("package:replaces") ====
     586 - '''Type:''' string
     587 - '''Value:''' Name of an entity that is being replaced by this package (used if the name of a package changes, or if a package has been split).
     588 - '''Allowed Values:''' Any string matching [ <alphanum-underline> ':' ] <alphanum_underline>.
     589 - '''Child Attributes:''' none
     590
     591==== B_HPKG_ATTRIBUTE_ID_PACKAGE_CHECKSUM ("package:checksum") ====
     592 - '''Type:''' string
     593 - '''Value:''' SHA256-chechsum of this package, in hexdump format. N.B.: this attribute can only be found in package repository files, not in package files.
     594 - '''Allowed Values:''' 64-bytes of hexdump.
     595 - '''Child Attributes:''' none
     596
     597== Haiku Package Repository Format ==
     598
     599Very similar to the package format, there's a Haiku Package Repository (HPKR) file format. Such a file contains informative attributes about the package repository and package attributes for all packages contained in the repository. However, this format does not contain any files.
     600
     601Two stacked format layers can be identified:
     602 - A generic container format for structured data.
     603 - A package format, extending the archive format with attributes for package management.
     604
     605
     606=== The Data Container Format ===
     607
     608A HPKR file consists of three sections:
     609 Header::
     610   Identifies the file as HPKR file and provides access to the other sections.
     611 Repository Info::
     612   A section containing an archived BMessage of a BRepositoryInfo object.
     613 Package Attributes::
     614   A section just like the package attributes section of the HPKG, only that this section contains the package attributes of all the packages contained in the repository (not just one).
     615
     616
     617==== Header ====
     618
     619The header has the following structure:
     620
     621{{{
     622struct hpkg_repo_header {
     623        uint32  magic;
     624        uint16  header_size;
     625        uint16  version;
     626        uint64  total_size;
     627
     628        // repository info section
     629        uint32  info_compression;
     630        uint32  info_length_compressed;
     631        uint32  info_length_uncompressed;
     632
     633        // package attributes section
     634        uint32  packages_compression;
     635        uint64  packages_length_compressed;
     636        uint64  packages_length_uncompressed;
     637        uint64  packages_strings_length;
     638        uint64  packages_strings_count;
     639};
     640}}}
     641
     642 magic::
     643   The string 'hpkr' (B_HPKG_REPO_MAGIC).
     644 header_size::
     645   The size of the header.
     646 version::
     647   The version of the HPKR format the file conforms to. The current version is
     648   1 (B_HPKG_REPO_VERSION).
     649 total_size::
     650   The total file size.
     651
     652 info_compression::
     653   The compression algorithm used for the repository info section.
     654 info_length_compressed::
     655   The compressed size of the repository info section. Equals
     656   info_length_uncompressed, if the section is not compressed.
     657 info_length_uncompressed::
     658   The uncompressed size of the repository info section.
     659
     660 packages_compression::
     661   The compression algorithm used for the package attributes section.
     662 packages_length_compressed::
     663   The compressed size of the package attributes section. Equals
     664   attributes_length_uncompressed, if the section is not compressed.
     665 packages_length_uncompressed::
     666   The uncompressed size of the package attributes section.
     667 packages_strings_length::
     668   The size of the strings subsection of the package attributes section.
     669 packages_strings_count::
     670   The number of entries in the strings subsection of the package attributes section.