.. _hpkg_file_format:=========================Haiku Package File Format=========================.. contents:::depth: 2:backlinks: noneThis document specifies the Haiku Package (HPKG) file format, which was designedfor efficient use by Haiku's package file system. It is somewhat inspired by the`XAR format`_ (separate TOC and data heap), but aims for greater compactness(no XML for the TOC)... _XAR format: http://code.google.com/p/xar/Three stacked format layers can be identified:- A generic container format for structured data.- An archive format specifying how file system data are stored in the container.- A package format, extending the archive format with attributes for packagemanagement.The Data Container Format=========================A HPKG file consists of four sections:HeaderIdentifies the file as HPKG file and provides access to the other sections.HeapContains arbitrary (mostly unstructured) data referenced by the next twosections.TOC (table of contents)The main section, containing structured data with references to unstructureddata in the heap section.Package AttributesA section similar to the TOC. Rather than describing the data contained inthe file, it specifies meta data of the package as a whole.The TOC and Package Attributes sections aren't really separate sections, as theyare stored at the end of the heap.All numbers in the HPKG are stored in big endian format or `LEB128`_ encoding... _LEB128: http://en.wikipedia.org/wiki/LEB128Header------The header has the following structure::struct hpkg_header {uint32 magic;uint16 header_size;uint16 version;uint64 total_size;uint16 minor_version;uint16 heap_compression;uint32 heap_chunk_size;uint64 heap_size_compressed;uint64 heap_size_uncompressed;uint32 attributes_length;uint32 attributes_strings_length;uint32 attributes_strings_count;uint32 reserved1;uint64 toc_length;uint64 toc_strings_length;uint64 toc_strings_count;};magicThe string 'hpkg' (B_HPKG_MAGIC).header_sizeThe size of the header. This is also the absolute offset of the heap.versionThe version of the HPKG format the file conforms to. The current version is2 (B_HPKG_VERSION).total_sizeThe total file size.minor_versionThe minor version of the HPKG format the file conforms to. The current minorversion is 1 (B_HPKG_MINOR_VERSION). Additions of new attributes to theattributes or TOC sections should generally only increment the minor version.When a file with a greater minor version is encountered, the reader shouldignore unknown attributes...heap_compressionCompression format used for the heap.heap_chunk_sizeThe size of the chunks the uncompressed heap data are divided into.heap_size_compressedThe compressed size of the heap. This includes all administrative data (thechunk size array).heap_size_uncompressedThe uncompressed size of the heap. This is only the size of the raw data(including the TOC and attributes section), not including administrative data(the chunk size array)...attributes_lengthThe uncompressed size of the package attributes section.attributes_strings_lengthThe size of the strings subsection of the package attributes section.attributes_strings_countThe number of entries in the strings subsection of the package attributessection...reserved1Reserved for later use...toc_lengthThe uncompressed size of the TOC section.toc_strings_lengthThe size of the strings subsection of the TOC section.toc_strings_countThe number of entries in the strings subsection of the TOC section.Heap----The heap provides storage for arbitrary data. Data from various sources areconcatenated without padding or separator, forming the uncompressed heap. Aspecific section of data is usually referenced (e.g. in the TOC and attributessections) by an offset and the number of bytes. These references always pointinto the uncompressed heap, even if the heap is actually stored in a compressedformat. The ``heap_compression`` field in the header specifies which format isused. The following values are defined:= ======================= =======================0 B_HPKG_COMPRESSION_NONE no compression1 B_HPKG_COMPRESSION_ZLIB zlib (LZ77) compression= ======================= =======================The uncompressed heap data are divided into equally sized chunks (64 KiB). Thelast chunk in the heap may have a different uncompressed length from thepreceding chunks. The uncompressed length of the last chunk can be derived. Eachindividual chunk may be stored compressed or not.Unless B_HPKG_COMPRESSION_NONE is specified, a uint16 array at the end of theheap contains the actual in-file (compressed) size of each chunk (minus 1 -- 0means 1 byte), save for the last one, which is omitted since it is implied. Achunk is only stored compressed, if compression actually saves space. That isif the chunk's compressed size equals its uncompressed size, the data aren'tcompressed. If B_HPKG_COMPRESSION_NONE is specified, the chunk size table isomitted entirely.The TOC and the package attributes sections are stored (in this order) at theend of the uncompressed heap. The offset of the package attributes section datais therefore ``heap_size_uncompressed - attributes_length`` and the offset ofthe TOC section data``heap_size_uncompressed - attributes_length - toc_length``.TOC---The TOC section contains a list of attribute trees. An attribute has an ID, adata type, and a value, and can have child attributes. E.g.:- ATTRIBUTE_ID_SHOPPING_LIST : string : "bakery"- ATTRIBUTE_ID_ITEM : string : "rye bread"- ATTRIBUTE_ID_ITEM : string : "bread roll"- ATTRIBUTE_ID_COUNT : int : 10- ATTRIBUTE_ID_ITEM : string : "cookie"- ATTRIBUTE_ID_COUNT : int : 5- ATTRIBUTE_ID_SHOPPING_LIST : string : "hardware store"- ATTRIBUTE_ID_ITEM : string : "hammer"- ATTRIBUTE_ID_ITEM : string : "nail"- ATTRIBUTE_ID_SIZE : int : 10- ATTRIBUTE_ID_COUNT : int : 100The main TOC section refers to any attribute by its unique ID (see below) andstores the attribute's value, either as a reference into the heap or as inlinedata.An optimization exists for shared string attribute values. A string value usedby more than one attribute is stored in the strings subsection and is referencedby an index.Hence the TOC section consists of two subsections:StringsA table of commonly used strings.Main TOCThe attribute trees.Attribute Data Types`````````````````````These are the specified data type values for attributes:= ============================= =================0 B_HPKG_ATTRIBUTE_TYPE_INVALID invalid1 B_HPKG_ATTRIBUTE_TYPE_INT signed integer2 B_HPKG_ATTRIBUTE_TYPE_UINT unsigned integer3 B_HPKG_ATTRIBUTE_TYPE_STRING UTF-8 string4 B_HPKG_ATTRIBUTE_TYPE_RAW raw data= ============================= =================Strings```````The strings subsections consists of a list of null-terminated UTF-8 strings. Thesection itself is terminated by a 0 byte.Each string is implicitly assigned the (null-based) index at which it appears inthe list, i.e. the nth string has the index n - 1. The string is referenced bythis index in the main TOC subsection.Main TOC````````The main TOC subsection consists of a list of attribute entries terminated by a0 byte. An attribute entry is stored as:Attribute tagAn unsigned LEB128 encoded number.Attribute valueThe value of the attribute encoded as described below.Attribute child listOnly if this attribute is marked to have children: A list of attribute entriesterminated by a 0 byte.The attribute tag encodes four pieces of information::(encoding << 11) + (hasChildren << 10) + (dataType << 7) + id + 1encodingSpecifies the encoding of the attribute value as described below.hasChildren1, if the attribute has children, 0 otherwise.dataTypeThe data type of the attribute (B_HPKG_ATTRIBUTE_TYPE\_...).idThe ID of the attribute (B_HPKG_ATTRIBUTE_ID\_...).Attribute Values````````````````A value of each of the data types can be encoded in different ways, which isdefined by the encoding value:- B_HPKG_ATTRIBUTE_TYPE_INT and B_HPKG_ATTRIBUTE_TYPE_UINT:= ==================================== ============0 B_HPKG_ATTRIBUTE_ENCODING_INT_8_BIT int8/uint81 B_HPKG_ATTRIBUTE_ENCODING_INT_16_BIT int16/uint162 B_HPKG_ATTRIBUTE_ENCODING_INT_32_BIT int32/uint323 B_HPKG_ATTRIBUTE_ENCODING_INT_64_BIT int64/uint64= ==================================== ============- B_HPKG_ATTRIBUTE_TYPE_STRING:= ======================================= ==================================0 B_HPKG_ATTRIBUTE_ENCODING_STRING_INLINE null-terminated UTF-8 string1 B_HPKG_ATTRIBUTE_ENCODING_STRING_TABLE unsigned LEB128: index into stringtable= ======================================= ==================================- B_HPKG_ATTRIBUTE_TYPE_RAW:= ==================================== =======================================0 B_HPKG_ATTRIBUTE_ENCODING_RAW_INLINE unsigned LEB128: size; followed by rawbytes1 B_HPKG_ATTRIBUTE_ENCODING_RAW_HEAP unsigned LEB128: size; unsigned LEB128:offset into the uncompressed heap= ==================================== =======================================Package Attributes------------------The package attributes section contains a list of attribute trees, just like theTOC section. The structure of this section follows the TOC, i.e. there's asubsection for shared strings and a subsection that stores a list of attributeentries terminated by a 0 byte. An entry has the same format as the ones in theTOC (only using different attribute IDs).The Archive Format==================This section specifies how file system objects (files, directories, symlinks)are stored in a HPKG file. It builds on top of the container format, definingthe types of attributes, their order, and allowed values.E.g. a "bin" directory, containing a symlink and a file::bin 0 2009-11-13 12:12:09 drwxr-xr-xawk 0 2009-11-13 12:11:16 lrwxrwxrwx -> gawkgawk 301699 2009-11-13 12:11:16 -rwxr-xr-xcould be represented by this attribute tree:- B_HPKG_ATTRIBUTE_ID_DIR_ENTRY : string : "bin"- B_HPKG_ATTRIBUTE_ID_FILE_TYPE : uint : 1 (0x1)- B_HPKG_ATTRIBUTE_ID_FILE_MTIME : uint : 1258110729 (0x4afd3f09)- B_HPKG_ATTRIBUTE_ID_DIR_ENTRY : string : "awk"- B_HPKG_ATTRIBUTE_ID_FILE_TYPE : uint : 2 (0x2)- B_HPKG_ATTRIBUTE_ID_FILE_MTIME : uint : 1258110676 (0x4afd3ed4)- B_HPKG_ATTRIBUTE_ID_SYMLINK_PATH : string : "gawk"- B_HPKG_ATTRIBUTE_ID_DIR_ENTRY : string : "gawk"- B_HPKG_ATTRIBUTE_ID_FILE_PERMISSIONS : uint : 493 (0x1ed)- B_HPKG_ATTRIBUTE_ID_FILE_MTIME : uint : 1258110676 (0x4afd3ed4)- B_HPKG_ATTRIBUTE_ID_DATA : raw : size: 301699, offset: 0- B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE : string : "BEOS:APP_VERSION"- B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE : uint : 1095782486 (0x41505056)- B_HPKG_ATTRIBUTE_ID_DATA : raw : size: 680, offset: 301699- B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE : string : "BEOS:TYPE"- B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE : uint : 1296649555 (0x4d494d53)- B_HPKG_ATTRIBUTE_ID_DATA : raw : size: 35, offset: 302379Attribute IDs-------------B_HPKG_ATTRIBUTE_ID_DIRECTORY_ENTRY ("dir:entry"):Type: string:Value: File name of the entry.:Allowed Values: Any valid file (not path!) name, save "." and "..".:Child Attributes:- B_HPKG_ATTRIBUTE_ID_FILE_TYPE: The file type of the entry.- B_HPKG_ATTRIBUTE_ID_FILE_PERMISSIONS: The file permissions of the entry.- B_HPKG_ATTRIBUTE_ID_FILE_USER: The owning user of the entry.- B_HPKG_ATTRIBUTE_ID_FILE_GROUP: The owning group of the entry.- B_HPKG_ATTRIBUTE_ID_FILE_ATIME[_NANOS]: The entry's file access time.- B_HPKG_ATTRIBUTE_ID_FILE_MTIME[_NANOS]: The entry's file modificationtime.- B_HPKG_ATTRIBUTE_ID_FILE_CRTIME[_NANOS]: The entry's file creation time.- B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE: An extended file attribute associatedwith entry.- B_HPKG_ATTRIBUTE_ID_DATA: Only if the entry is a file: The file data.- B_HPKG_ATTRIBUTE_ID_SYMLINK_PATH: Only if the entry is a symlink: The paththe symlink points to.- B_HPKG_ATTRIBUTE_ID_DIRECTORY_ENTRY: Only if the entry is a directory: Achild entry in that directory.B_HPKG_ATTRIBUTE_ID_FILE_TYPE ("file\:type"):Type: uint:Value: Type of the entry.:Allowed Values:= ========================== =========0 B_HPKG_FILE_TYPE_FILE file1 B_HPKG_FILE_TYPE_DIRECTORY directory2 B_HPKG_FILE_TYPE_SYMLINK symlink= ========================== =========:Default Value: B_HPKG_FILE_TYPE_FILE:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_FILE_PERMISSIONS ("file\:permissions"):Type: uint:Value: File permissions.:Allowed Values: Any valid permission mask.:Default Value:- For files: 0644 (octal).- For directories: 0755 (octal).- For symlinks: 0777 (octal).:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_FILE_USER ("file\:user"):Type: string:Value: Name of the user owning the file.:Allowed Values: Any non-empty string.:Default Value: The user owning the installation location where the package isactivated.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_FILE_GROUP ("file\:group"):Type: string:Value: Name of the group owning the file.:Allowed Values: Any non-empty string.:Default Value: The group owning the installation location where the packageis activated.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_FILE_ATIME ("file\:atime"):Type: uint:Value: File access time (seconds since the Epoch).:Allowed Values: Any value.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_FILE_ATIME_NANOS ("file\:mtime:nanos"):Type: uint:Value: The nano seconds fraction of the file access time.:Allowed Values: Any value in [0, 999999999].:Default Value: 0:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_FILE_MTIME ("file\:mtime"):Type: uint:Value: File modified time (seconds since the Epoch).:Allowed Values: Any value.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_FILE_MTIME_NANOS ("file\:mtime:nanos"):Type: uint:Value: The nano seconds fraction of the file modified time.:Allowed Values: Any value in [0, 999999999].:Default Value: 0:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_FILE_CRTIME ("file\:crtime"):Type: uint:Value: File creation time (seconds since the Epoch).:Allowed Values: Any value.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_FILE_CRTIM_NANOS ("file\:crtime:nanos"):Type: uint:Value: The nano seconds fraction of the file creation time.:Allowed Values: Any value in [0, 999999999].:Default Value: 0:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE ("file\:attribute"):Type: string:Value: Name of the extended file attribute.:Allowed Values: Any valid attribute name.:Child Attributes:- B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE: The type of the file attribute.- B_HPKG_ATTRIBUTE_ID_DATA: The file attribute data.B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE ("file\:attribute:type"):Type: uint:Value: Type of the file attribute.:Allowed Values: Any value in [0, 0xffffffff].:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_DATA ("data"):Type: data:Value: Raw data of a file or attribute.:Allowed Values: Any value.B_HPKG_ATTRIBUTE_ID_SYMLINK_PATH ("symlink:path"):Type: string:Value: The path the symlink refers to.:Allowed Values: Any valid symlink path.:Default Value: Empty string.:Child Attributes: noneTOC Attributes--------------The TOC can directly contain any number of attributes of theB_HPKG_ATTRIBUTE_ID_DIRECTORY_ENTRY type, which in turn contain descendantattributes as specified in the previous section. Any other attributes areignored.The Package Format==================This section specifies how informative package attributes (package-name,version, provides, requires, ...) are stored in a HPKG file. It builds on top ofthe container format, defining the types of attributes, their order, and allowedvalues.E.g. a ".PackageInfo" file, containing a package description that is beingconverted into a package file::name mypackageversion 0.7.2-1architecture x86summary "is a very nice package"description "has lots of cool features\nand is written in MyC++"vendor "Me, Myself & I, Inc."packager "me@test.com"copyrights { "(C) 2009-2011, Me, Myself & I, Inc." }licenses { "Me, Myself & I Commercial License"; "MIT" }provides {cmd:melib:libmyself = 0.7}requires {haiku >= r1wget}could be represented by this attribute tree:- B_HPKG_ATTRIBUTE_ID_PACKAGE_NAME : string : "mypackage"- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR : string : "0"- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR : string : "7"- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO : string : "2"- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION : uint : 1- B_HPKG_ATTRIBUTE_ID_PACKAGE_ARCHITECTURE : uint : 1- B_HPKG_ATTRIBUTE_ID_PACKAGE_SUMMARY : string : "is a very nice package"- B_HPKG_ATTRIBUTE_ID_PACKAGE_DESCRIPTION : string : "has lots of cool features\nand is written in MyC++"- B_HPKG_ATTRIBUTE_ID_PACKAGE_VENDOR : string : "Me, Myself & I, Inc."- B_HPKG_ATTRIBUTE_ID_PACKAGE_PACKAGER : string : "me@test.com"- B_HPKG_ATTRIBUTE_ID_PACKAGE_COPYRIGHT : string : "(C) 2009-2011, Me, Myself &I, Inc."- B_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE : string : "Me, Myself & I CommercialLicense"- B_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE : string : "MIT"- B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES : string : "cmd:me"- B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES : string : "lib:libmyself"- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR : string : "0"- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR : string : "7"- B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES : string : "haiku"- B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR : uint : 4- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR : string : "r1"- B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES : string : "wget".. _The Package Format/Attribute IDs:Attribute IDs-------------B_HPKG_ATTRIBUTE_ID_PACKAGE_NAME ("package:name"):Type: string:Value: Name of the package.:Allowed Values: Any string matching <entity_name_char>+, with<entity_name_char> being any character but '-', '/', '=', '!', '<', '>', orwhitespace.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_SUMMARY ("package:summary"):Type: string:Value: Short description of the package.:Allowed Values: Any single-lined string.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_DESCRIPTION ("package:description"):Type: string:Value: Long description of the package.:Allowed Values: Any string (may contain multiple lines).:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_VENDOR ("package:vendor"):Type: string:Value: Name of the person/organization that is publishing this package.:Allowed Values: Any single-lined string.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_PACKAGER ("package:packager"):Type: string:Value: E-Mail address of person that created this package.:Allowed Values: Any single-lined string, but e-mail preferred.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_BASE_PACKAGE ("package:base-package"):Type: string:Value: Name of the package that is the base package for this package. Thebase package must also be listed as a requirement for this package (cf.B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES). The package manager shall ensure thatthis package is installed in the same installation location as its basepackage.:Allowed Values: Valid package names.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_FLAGS ("package:flags"):Type: uint:Value: Set of boolean flags applying to package.:Allowed Values: Any combination of the following.= ============================== ==========================================1 B_PACKAGE_FLAG_APPROVE_LICENSE this package's license requires approval(i.e. must be shown to and acknowledged byuser before installation)2 B_PACKAGE_FLAG_SYSTEM_PACKAGE this is a system package (i.e. lives under/boot/system)= ============================== ==========================================:Default Value: 0:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_ARCHITECTURE ("package:architecture"):Type: uint:Value: System architecture this package was built for.:Allowed Values:= =============================== =========================================0 B_PACKAGE_ARCHITECTURE_ANY this package doesn't depend on the systemarchitecture1 B_PACKAGE_ARCHITECTURE_X86 x86, 32-bit, built with gcc42 B_PACKAGE_ARCHITECTURE_X86_GCC2 x86, 32-bit, built with gcc23 B_PACKAGE_ARCHITECTURE_SOURCE source code, doesn't depend on the systemarchitecture4 B_PACKAGE_ARCHITECTURE_X86_64 x86-645 B_PACKAGE_ARCHITECTURE_PPC PowerPC6 B_PACKAGE_ARCHITECTURE_ARM ARM7 B_PACKAGE_ARCHITECTURE_M68K m68k8 B_PACKAGE_ARCHITECTURE_SPARC sparc= =============================== =========================================:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR ("package:version.major"):Type: string:Value: Major (first) part of package version.:Allowed Values: Any single-lined string, composed of <alphanum_underline>:Child Attributes:- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR: The minor part of the packageversion.- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO: The micro part of the packageversion.- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_PRE_RELEASE: The pre-release part ofthe package version.- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION: The revision part of thepackage version.B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR ("package:version.minor"):Type: string:Value: Minor (second) part of package version.:Allowed Values: Any single-lined string, composed of <alphanum_underline>.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO ("package:version.micro"):Type: string:Value: Micro (third) part of package version.:Allowed Values: Any single-lined string, composed of<alphanum_underline_dot>.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_PRE_RELEASE ("package:version.prerelease"):Type: string:Value: Pre-release (fourth) part of package version. Typically something like"alpha1", "beta2", "rc3".:Allowed Values: Any single-lined string, composed of<alphanum_underline_dot>.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION ("package:version.revision"):Type: uint:Value: Revision (fifth) part of package version.:Allowed Values: Any integer greater than 0.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_COPYRIGHT ("package:copyright"):Type: string:Value: Copyright applying to the software contained in this package.:Allowed Values: Any (preferably single-lined) string.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE ("package:license"):Type: string:Value: Name of license applying to the software contained in this package.:Allowed Values: Any single-lined string.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_URL ("package:url"):Type: string:Value: URL of the packaged software's project home page.:Allowed Values: A regular URL or an email-like named URL (e.g."Project Foo <http://foo.example.com>").:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_SOURCE_URL ("package:source-url"):Type: string:Value: URL of the packaged software's source code or build instructions.:Allowed Values: A regular URL or an email-like named URL (e.g."Project Foo <http://foo.example.com>").:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES ("package:provides"):Type: string:Value: Name of a (optionally typed) entity that is being provided by thispackage.:Allowed Values: Any string matching <entity_name_char>+.:Child Attributes:- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvableversion.- B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES_COMPATIBLE: The major part of theresolvable compatible version.B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES_COMPATIBLE ("package:provides.compatible"):Type: string:Value: Major (first) part of the resolvable compatible version, structurallyidentical to B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR.:Allowed Values: Any string matching <entity_name_char>+.:Child Attributes:- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR: The minor part of the resolvablecompatible version.- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO: The micro part of the resolvablecompatible version.- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_PRE_RELEASE: The pre-release part ofthe resolvable compatible version.- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION: The revision part of theresolvable compatible version.B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES ("package:requires"):Type: string:Value: Name of an entity that is required by this package (and hopefullybeing provided by another).:Allowed Values: Any string matching <entity_name_char>+.:Child Attributes:- B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator asint.- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvableversion.B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR ("package:resolvable.operator"):Type: uint:Value: Comparison operator for versions.:Allowed Values:= ===================================== ===================================0 B_PACKAGE_RESOLVABLE_OP_LESS less than the specified version1 B_PACKAGE_RESOLVABLE_OP_LESS_EQUAL less than or equal to the specifiedversion2 B_PACKAGE_RESOLVABLE_OP_EQUAL equal to the specified version3 B_PACKAGE_RESOLVABLE_OP_NOT_EQUAL not equal to the specified version4 B_PACKAGE_RESOLVABLE_OP_GREATER_EQUAL greater than the specified version5 B_PACKAGE_RESOLVABLE_OP_GREATER greater than or equal to thespecified version= ===================================== ===================================:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_SUPPLEMENTS ("package:supplements"):Type: string:Value: Name of an entity that is supplemented by this package (i.e. thispackage will automatically be selected for installation if the supplementedresolvables are already installed).:Allowed Values: Any string matching <entity_name_char>+.:Child Attributes:- B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator asint.- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvableversion.B_HPKG_ATTRIBUTE_ID_PACKAGE_CONFLICTS ("package:conflicts"):Type: string:Value: Name of an entity that this package conflicts with (i.e. only one ofboth can be installed at any time).:Allowed Values: Any string matching <entity_name_char>+.:Child Attributes:- B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator asint.- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvableversion.B_HPKG_ATTRIBUTE_ID_PACKAGE_FRESHENS ("package:freshens"):Type: string:Value: Name of an entity that is being freshened by this package (i.e. thispackage will patch one or more files of the package that provide thisresolvable).:Allowed Values: Any string matching <entity_name_char>+.:Child Attributes:- B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator asint.- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvableversion.B_HPKG_ATTRIBUTE_ID_PACKAGE_REPLACES ("package:replaces"):Type: string:Value: Name of an entity that is being replaced by this package (used if thename of a package changes, or if a package has been split).:Allowed Values: Any string matching <entity_name_char>+.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_CHECKSUM ("package:checksum"):Type: string:Value: SHA256-chechsum of this package, in hexdump format. N.B.: thisattribute can only be found in package repository files, not in packagefiles.:Allowed Values: 64-bytes of hexdump.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_GLOBAL_WRITABLE_FILE ("package:global-writable-file"):Type: string:Value: Relative path of a global writable file either included in the packageor created by the included software. If the file is included in the package,it will be installed upon activation. In this case the attribute mustcontain a B_HPKG_ATTRIBUTE_ID_PACKAGE_WRITABLE_FILE_UPDATE_TYPE childattribute. The file may actually be a directory, which is indicated by theB_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY child attribute.:Allowed Values: Installation location relative path (e.g. "settings/...").:Child Attributes:- B_HPKG_ATTRIBUTE_ID_PACKAGE_WRITABLE_FILE_UPDATE_TYPE: Specifies what to dowith the writable file on package update.- B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY: Specifies whether thefile is actually a directory.B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_SETTINGS_FILE ("package:user-settings-file"):Type: string:Value: Relative path of a user settings file created by the included softwareor required by the software to be created by the user. The file may actuallybe a directory, which is indicated by theB_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY child attribute.:Allowed Values: Installation location relative path (i.e. "settings/...").:Child Attributes:- B_HPKG_ATTRIBUTE_ID_PACKAGE_SETTINGS_FILE_TEMPLATE: A template for thesettings file.- B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY: Specifies whether thefile is actually a directory.B_HPKG_ATTRIBUTE_ID_PACKAGE_WRITABLE_FILE_UPDATE_TYPE ("package:writable-file-update-type"):Type: uint:Value: Specifies what to do on package update when the writable file providedby the package has been changed by the user.:Allowed Values:= ====================================== ==================================0 B_WRITABLE_FILE_UPDATE_TYPE_KEEP_OLD the old file shall be kept1 B_WRITABLE_FILE_UPDATE_TYPE_MANUAL the old file needs to be updatedmanually2 B_WRITABLE_FILE_UPDATE_TYPE_AUTO_MERGE an automatic three-way merge shallbe attempted= ====================================== ==================================:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY ("package:is-writable-directory"):Type: uint:Value: Specifies whether the parent global writable file or user settings file attribute actually refers to a directory.:Allowed Values:= ===========================================0 The parent attribute refers to a file.1 The parent attribute refers to a directory.= ===========================================:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_SETTINGS_FILE_TEMPLATE ("package:settings-file-template"):Type: string:Value: Relative path of an included template file for the user settings file.:Allowed Values: Installation location relative path of a file included in thepackage.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_USER ("package:user"):Type: string:Value: Name of a user required by the package. Upon package activation theuser will be created, if necessary.:Allowed Values: Any valid user name, i.e. must be non-empty composed of<alphanum_underline>.:Child Attributes:- B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_REAL_NAME: The user's real name.- B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_HOME: The user's home directory.- B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_SHELL: The user's shell.- B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_GROUP: The user's group(s).B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_REAL_NAME ("package:user.real-name"):Type: string:Value: The real name of the user.:Allowed Values: Any string.:Default Value: The user name.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_USER_HOME ("package:user.home"):Type: string:Value: The path to the home directory of the user.:Allowed Values: Any valid path.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_USER_SHELL ("package:user.shell"):Type: string:Value: The path to the shell to be used for the user.:Allowed Values: Any valid path.:Default Value: "/bin/bash".:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_USER_GROUP ("package:user.group"):Type: string:Value: A group the user belongs to. At least one must be specified.:Allowed Values: Any valid group name, i.e. must be non-empty composed of<alphanum_underline>.:Default Value: The default group for users.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_GROUP ("package:group"):Type: string:Value: Name of a group required by the package. Upon package activation thegroup will be created, if necessary.:Allowed Values: Any valid group name, i.e. must be non-empty composed of<alphanum_underline>.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_POST_INSTALL_SCRIPT ("package:post-install-script"):Type: string:Value: Relative path of a script that shall be executed after packageactivation.:Allowed Values: Installation location relative path of a file included in thepackage. Must start with "boot/post-install/", so besides being run afterpackage installation, it also gets run on the first boot after the OS isinstalled.:Child Attributes: noneB_HPKG_ATTRIBUTE_ID_PACKAGE_PRE_UNINSTALL_SCRIPT ("package:pre-uninstall-script"):Type: string:Value: Relative path of a script that shall be executed before packagedeactivation.:Allowed Values: Installation location relative path of a file included inthe package. For consistency, it is recommended to start with"boot/pre-uninstall/".:Child Attributes: none.. _hpkr_file_format:Haiku Package Repository Format===============================Very similar to the package format, there's a Haiku Package Repository (HPKR)file format. Such a file contains informative attributes about the packagerepository and package attributes for all packages contained in the repository.However, this format does not contain any files.Two stacked format layers can be identified:- A generic container format for structured data.- A package format, extending the archive format with attributes for packagemanagement.The Data Container Format-------------------------A HPKR file consists of three sections:HeaderIdentifies the file as HPKR file and provides access to the other sections.HeapContains the next two sections.Repository InfoA section containing an archived BMessage of a BRepositoryInfo object.Package AttributesA section just like the package attributes section of the HPKG, only that thissection contains the package attributes of all the packages contained in therepository (not just one).The Repository Info and Package Attributes sections aren't really separatesections, as they are stored at the end of the heap.Header``````The header has the following structure::struct hpkg_repo_header {uint32 magic;uint16 header_size;uint16 version;uint64 total_size;uint16 minor_version;// heapuint16 heap_compression;uint32 heap_chunk_size;uint64 heap_size_compressed;uint64 heap_size_uncompressed;// repository info sectionuint32 info_length;uint32 reserved1;// package attributes sectionuint64 packages_length;uint64 packages_strings_length;uint64 packages_strings_count;};magicThe string 'hpkr' (B_HPKG_REPO_MAGIC).header_sizeThe size of the header. This is also the absolute offset of the heap.versionThe version of the HPKR format the file conforms to. The current version is2 (B_HPKG_REPO_VERSION).total_sizeThe total file size.minor_versionThe minor version of the HPKR format the file conforms to. The current minorversion is 1 (B_HPKG_REPO_MINOR_VERSION). Additions of new attributes to theattributes section should generally only increment the minor version. When afile with a greater minor version is encountered, the reader should ignoreunknown attributes...heap_compressionCompression format used for the heap.heap_chunk_sizeThe size of the chunks the uncompressed heap data are divided into.heap_size_compressedThe compressed size of the heap. This includes all administrative data (thechunk size array).heap_size_uncompressedThe uncompressed size of the heap. This is only the size of the raw data(including the repository info and attributes section), not includingadministrative data (the chunk size array)...info_lengthThe uncompressed size of the repository info section...reserved1Reserved for later use...packages_lengthThe uncompressed size of the package attributes section.packages_strings_lengthThe size of the strings subsection of the package attributes section.packages_strings_countThe number of entries in the strings subsection of the package attributessection.Attribute IDs-------------The package repository format defines only the top-level attribute IDB_HPKG_ATTRIBUTE_ID_PACKAGE. An attribute with that ID represents a package. Itschild attributes specify the various meta information for the package as definedin the `The Package Format/Attribute IDs`_ section.