1========================= 2Haiku Package File Format 3========================= 4 5.. contents:: 6 :depth: 2 7 :backlinks: none 8 9This document specifies the Haiku Package (HPKG) file format, which was designed 10for efficient use by Haiku's package file system. It is somewhat inspired by the 11`XAR format`_ (separate TOC and data heap), but aims for greater compactness 12(no XML for the TOC). 13 14.. _XAR format: http://code.google.com/p/xar/ 15 16Three stacked format layers can be identified: 17 18- A generic container format for structured data. 19- An archive format specifying how file system data are stored in the container. 20- A package format, extending the archive format with attributes for package 21 management. 22 23The Data Container Format 24========================= 25A HPKG file consists of four sections: 26 27Header 28 Identifies the file as HPKG file and provides access to the other sections. 29 30Heap 31 Contains arbitrary (mostly unstructured) data referenced by the next two 32 sections. 33 34TOC (table of contents) 35 The main section, containing structured data with references to unstructured 36 data in the heap section. 37 38Package Attributes 39 A section similar to the TOC. Rather than describing the data contained in 40 the file, it specifies meta data of the package as a whole. 41 42The TOC and Package Attributes sections aren't really separate sections, as they 43are stored at the end of the heap. 44 45All numbers in the HPKG are stored in big endian format or `LEB128`_ encoding. 46 47.. _LEB128: http://en.wikipedia.org/wiki/LEB128 48 49Header 50------ 51The header has the following structure:: 52 53 struct hpkg_header { 54 uint32 magic; 55 uint16 header_size; 56 uint16 version; 57 uint64 total_size; 58 uint16 minor_version; 59 60 uint16 heap_compression; 61 uint32 heap_chunk_size; 62 uint64 heap_size_compressed; 63 uint64 heap_size_uncompressed; 64 65 uint32 attributes_length; 66 uint32 attributes_strings_length; 67 uint32 attributes_strings_count; 68 uint32 reserved1; 69 70 uint64 toc_length; 71 uint64 toc_strings_length; 72 uint64 toc_strings_count; 73 }; 74 75magic 76 The string 'hpkg' (B_HPKG_MAGIC). 77 78header_size 79 The size of the header. This is also the absolute offset of the heap. 80 81version 82 The version of the HPKG format the file conforms to. The current version is 83 2 (B_HPKG_VERSION). 84 85total_size 86 The total file size. 87 88minor_version 89 The minor version of the HPKG format the file conforms to. The current minor 90 version is 0 (B_HPKG_MINOR_VERSION). Additions of new attributes to the 91 attributes or TOC sections should generally only increment the minor version. 92 When a file with a greater minor version is encountered, the reader should 93 ignore unknown attributes. 94 95.. 96 97heap_compression 98 Compression format used for the heap. 99 100heap_chunk_size 101 The size of the chunks the uncompressed heap data are divided into. 102 103heap_size_compressed 104 The compressed size of the heap. This includes all administrative data (the 105 chunk size array). 106 107heap_size_uncompressed 108 The uncompressed size of the heap. This is only the size of the raw data 109 (including the TOC and attributes section), not including administrative data 110 (the chunk size array). 111 112.. 113 114attributes_length 115 The uncompressed size of the package attributes section. 116 117attributes_strings_length 118 The size of the strings subsection of the package attributes section. 119 120attributes_strings_count 121 The number of entries in the strings subsection of the package attributes 122 section. 123 124.. 125 126reserved1 127 Reserved for later use. 128 129.. 130 131toc_length 132 The uncompressed size of the TOC section. 133 134toc_strings_length 135 The size of the strings subsection of the TOC section. 136 137toc_strings_count 138 The number of entries in the strings subsection of the TOC section. 139 140Heap 141---- 142The heap provides storage for arbitrary data. Data from various sources are 143concatenated without padding or separator, forming the uncompressed heap. A 144specific section of data is usually referenced (e.g. in the TOC and attributes 145sections) by an offset and the number of bytes. These references always point 146into the uncompressed heap, even if the heap is actually stored in a compressed 147format. The ``heap_compression`` field in the header specifies which format is 148used. The following values are defined: 149 150= ======================= ======================= 1510 B_HPKG_COMPRESSION_NONE no compression 1521 B_HPKG_COMPRESSION_ZLIB zlib (LZ77) compression 153= ======================= ======================= 154 155The uncompressed heap data are divided into equally sized chunks (64 KiB). The 156last chunk in the heap may have a different uncompressed length from the 157preceding chunks. The uncompressed length of the last chunk can be derived. Each 158individual chunk may be stored compressed or not. 159 160Unless B_HPKG_COMPRESSION_NONE is specified, a uint16 array at the end of the 161heap contains the actual in-file (compressed) size of each chunk (minus 1 -- 0 162means 1 byte), save for the last one, which is omitted since it is implied. A 163chunk is only stored compressed, if compression actually saves space. That is 164if the chunk's compressed size equals its uncompressed size, the data aren't 165compressed. If B_HPKG_COMPRESSION_NONE is specified, the chunk size table is 166omitted entirely. 167 168The TOC and the package attributes sections are stored (in this order) at the 169end of the uncompressed heap. The offset of the package attributes section data 170is therefore ``heap_size_uncompressed - attributes_length`` and the offset of 171the TOC section data 172``heap_size_uncompressed - attributes_length - toc_length``. 173 174TOC 175--- 176The TOC section contains a list of attribute trees. An attribute has an ID, a 177data type, and a value, and can have child attributes. E.g.: 178 179- ATTRIBUTE_ID_SHOPPING_LIST : string : "bakery" 180 181 - ATTRIBUTE_ID_ITEM : string : "rye bread" 182 - ATTRIBUTE_ID_ITEM : string : "bread roll" 183 184 - ATTRIBUTE_ID_COUNT : int : 10 185 186 - ATTRIBUTE_ID_ITEM : string : "cookie" 187 188 - ATTRIBUTE_ID_COUNT : int : 5 189 190- ATTRIBUTE_ID_SHOPPING_LIST : string : "hardware store" 191 192 - ATTRIBUTE_ID_ITEM : string : "hammer" 193 - ATTRIBUTE_ID_ITEM : string : "nail" 194 195 - ATTRIBUTE_ID_SIZE : int : 10 196 - ATTRIBUTE_ID_COUNT : int : 100 197 198The main TOC section refers to any attribute by its unique ID (see below) and 199stores the attribute's value, either as a reference into the heap or as inline 200data. 201 202An optimization exists for shared string attribute values. A string value used 203by more than one attribute is stored in the strings subsection and is referenced 204by an index. 205 206Hence the TOC section consists of two subsections: 207 208Strings 209 A table of commonly used strings. 210 211Main TOC 212 The attribute trees. 213 214Attribute Data Types 215````````````````````` 216These are the specified data type values for attributes: 217 218= ============================= ================= 2190 B_HPKG_ATTRIBUTE_TYPE_INVALID invalid 2201 B_HPKG_ATTRIBUTE_TYPE_INT signed integer 2212 B_HPKG_ATTRIBUTE_TYPE_UINT unsigned integer 2223 B_HPKG_ATTRIBUTE_TYPE_STRING UTF-8 string 2234 B_HPKG_ATTRIBUTE_TYPE_RAW raw data 224= ============================= ================= 225 226Strings 227``````` 228The strings subsections consists of a list of null-terminated UTF-8 strings. The 229section itself is terminated by a 0 byte. 230 231Each string is implicitly assigned the (null-based) index at which it appears in 232the list, i.e. the nth string has the index n - 1. The string is referenced by 233this index in the main TOC subsection. 234 235Main TOC 236```````` 237The main TOC subsection consists of a list of attribute entries terminated by a 2380 byte. An attribute entry is stored as: 239 240Attribute tag 241 An unsigned LEB128 encoded number. 242 243Attribute value 244 The value of the attribute encoded as described below. 245 246Attribute child list 247 Only if this attribute is marked to have children: A list of attribute entries 248 terminated by a 0 byte. 249 250The attribute tag encodes four pieces of information:: 251 252 (encoding << 11) + (hasChildren << 10) + (dataType << 7) + id + 1 253 254encoding 255 Specifies the encoding of the attribute value as described below. 256 257hasChildren 258 1, if the attribute has children, 0 otherwise. 259 260dataType 261 The data type of the attribute (B_HPKG_ATTRIBUTE_TYPE\_...). 262 263id 264 The ID of the attribute (B_HPKG_ATTRIBUTE_ID\_...). 265 266Attribute Values 267```````````````` 268A value of each of the data types can be encoded in different ways, which is 269defined by the encoding value: 270 271- B_HPKG_ATTRIBUTE_TYPE_INT and B_HPKG_ATTRIBUTE_TYPE_UINT: 272 273 = ==================================== ============ 274 0 B_HPKG_ATTRIBUTE_ENCODING_INT_8_BIT int8/uint8 275 1 B_HPKG_ATTRIBUTE_ENCODING_INT_16_BIT int16/uint16 276 2 B_HPKG_ATTRIBUTE_ENCODING_INT_32_BIT int32/uint32 277 3 B_HPKG_ATTRIBUTE_ENCODING_INT_64_BIT int64/uint64 278 = ==================================== ============ 279 280- B_HPKG_ATTRIBUTE_TYPE_STRING: 281 282 = ======================================= ================================== 283 0 B_HPKG_ATTRIBUTE_ENCODING_STRING_INLINE null-terminated UTF-8 string 284 1 B_HPKG_ATTRIBUTE_ENCODING_STRING_TABLE unsigned LEB128: index into string 285 table 286 = ======================================= ================================== 287 288- B_HPKG_ATTRIBUTE_TYPE_RAW: 289 290 = ==================================== ======================================= 291 0 B_HPKG_ATTRIBUTE_ENCODING_RAW_INLINE unsigned LEB128: size; followed by raw 292 bytes 293 1 B_HPKG_ATTRIBUTE_ENCODING_RAW_HEAP unsigned LEB128: size; unsigned LEB128: 294 offset into the uncompressed heap 295 = ==================================== ======================================= 296 297Package Attributes 298------------------ 299The package attributes section contains a list of attribute trees, just like the 300TOC section. The structure of this section follows the TOC, i.e. there's a 301subsection for shared strings and a subsection that stores a list of attribute 302entries terminated by a 0 byte. An entry has the same format as the ones in the 303TOC (only using different attribute IDs). 304 305The Archive Format 306================== 307This section specifies how file system objects (files, directories, symlinks) 308are stored in a HPKG file. It builds on top of the container format, defining 309the types of attributes, their order, and allowed values. 310 311E.g. a "bin" directory, containing a symlink and a file:: 312 313 bin 0 2009-11-13 12:12:09 drwxr-xr-x 314 awk 0 2009-11-13 12:11:16 lrwxrwxrwx -> gawk 315 gawk 301699 2009-11-13 12:11:16 -rwxr-xr-x 316 317could be represented by this attribute tree: 318 319- B_HPKG_ATTRIBUTE_ID_DIR_ENTRY : string : "bin" 320 321 - B_HPKG_ATTRIBUTE_ID_FILE_TYPE : uint : 1 (0x1) 322 - B_HPKG_ATTRIBUTE_ID_FILE_MTIME : uint : 1258110729 (0x4afd3f09) 323 - B_HPKG_ATTRIBUTE_ID_DIR_ENTRY : string : "awk" 324 325 - B_HPKG_ATTRIBUTE_ID_FILE_TYPE : uint : 2 (0x2) 326 - B_HPKG_ATTRIBUTE_ID_FILE_MTIME : uint : 1258110676 (0x4afd3ed4) 327 - B_HPKG_ATTRIBUTE_ID_SYMLINK_PATH : string : "gawk" 328 329 - B_HPKG_ATTRIBUTE_ID_DIR_ENTRY : string : "gawk" 330 331 - B_HPKG_ATTRIBUTE_ID_FILE_PERMISSIONS : uint : 493 (0x1ed) 332 - B_HPKG_ATTRIBUTE_ID_FILE_MTIME : uint : 1258110676 (0x4afd3ed4) 333 - B_HPKG_ATTRIBUTE_ID_DATA : raw : size: 301699, offset: 0 334 - B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE : string : "BEOS:APP_VERSION" 335 336 - B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE : uint : 1095782486 (0x41505056) 337 - B_HPKG_ATTRIBUTE_ID_DATA : raw : size: 680, offset: 301699 338 339 - B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE : string : "BEOS:TYPE" 340 341 - B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE : uint : 1296649555 (0x4d494d53) 342 - B_HPKG_ATTRIBUTE_ID_DATA : raw : size: 35, offset: 302379 343 344Attribute IDs 345------------- 346B_HPKG_ATTRIBUTE_ID_DIRECTORY_ENTRY ("dir:entry") 347 :Type: string 348 :Value: File name of the entry. 349 :Allowed Values: Any valid file (not path!) name, save "." and "..". 350 :Child Attributes: 351 352 - B_HPKG_ATTRIBUTE_ID_FILE_TYPE: The file type of the entry. 353 - B_HPKG_ATTRIBUTE_ID_FILE_PERMISSIONS: The file permissions of the entry. 354 - B_HPKG_ATTRIBUTE_ID_FILE_USER: The owning user of the entry. 355 - B_HPKG_ATTRIBUTE_ID_FILE_GROUP: The owning group of the entry. 356 - B_HPKG_ATTRIBUTE_ID_FILE_ATIME[_NANOS]: The entry's file access time. 357 - B_HPKG_ATTRIBUTE_ID_FILE_MTIME[_NANOS]: The entry's file modification 358 time. 359 - B_HPKG_ATTRIBUTE_ID_FILE_CRTIME[_NANOS]: The entry's file creation time. 360 - B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE: An extended file attribute associated 361 with entry. 362 - B_HPKG_ATTRIBUTE_ID_DATA: Only if the entry is a file: The file data. 363 - B_HPKG_ATTRIBUTE_ID_SYMLINK_PATH: Only if the entry is a symlink: The path 364 the symlink points to. 365 - B_HPKG_ATTRIBUTE_ID_DIRECTORY_ENTRY: Only if the entry is a directory: A 366 child entry in that directory. 367 368B_HPKG_ATTRIBUTE_ID_FILE_TYPE ("file\:type") 369 :Type: uint 370 :Value: Type of the entry. 371 :Allowed Values: 372 373 = ========================== ========= 374 0 B_HPKG_FILE_TYPE_FILE file 375 1 B_HPKG_FILE_TYPE_DIRECTORY directory 376 2 B_HPKG_FILE_TYPE_SYMLINK symlink 377 = ========================== ========= 378 379 :Default Value: B_HPKG_FILE_TYPE_FILE 380 :Child Attributes: none 381 382B_HPKG_ATTRIBUTE_ID_FILE_PERMISSIONS ("file\:permissions") 383 :Type: uint 384 :Value: File permissions. 385 :Allowed Values: Any valid permission mask. 386 :Default Value: 387 388 - For files: 0644 (octal). 389 - For directories: 0755 (octal). 390 - For symlinks: 0777 (octal). 391 392 :Child Attributes: none 393 394B_HPKG_ATTRIBUTE_ID_FILE_USER ("file\:user") 395 :Type: string 396 :Value: Name of the user owning the file. 397 :Allowed Values: Any non-empty string. 398 :Default Value: The user owning the installation location where the package is 399 activated. 400 :Child Attributes: none 401 402B_HPKG_ATTRIBUTE_ID_FILE_GROUP ("file\:group") 403 :Type: string 404 :Value: Name of the group owning the file. 405 :Allowed Values: Any non-empty string. 406 :Default Value: The group owning the installation location where the package 407 is activated. 408 :Child Attributes: none 409 410B_HPKG_ATTRIBUTE_ID_FILE_ATIME ("file\:atime") 411 :Type: uint 412 :Value: File access time (seconds since the Epoch). 413 :Allowed Values: Any value. 414 :Child Attributes: none 415 416B_HPKG_ATTRIBUTE_ID_FILE_ATIME_NANOS ("file\:mtime:nanos") 417 :Type: uint 418 :Value: The nano seconds fraction of the file access time. 419 :Allowed Values: Any value in [0, 999999999]. 420 :Default Value: 0 421 :Child Attributes: none 422 423B_HPKG_ATTRIBUTE_ID_FILE_MTIME ("file\:mtime") 424 :Type: uint 425 :Value: File modified time (seconds since the Epoch). 426 :Allowed Values: Any value. 427 :Child Attributes: none 428 429B_HPKG_ATTRIBUTE_ID_FILE_MTIME_NANOS ("file\:mtime:nanos") 430 :Type: uint 431 :Value: The nano seconds fraction of the file modified time. 432 :Allowed Values: Any value in [0, 999999999]. 433 :Default Value: 0 434 :Child Attributes: none 435 436B_HPKG_ATTRIBUTE_ID_FILE_CRTIME ("file\:crtime") 437 :Type: uint 438 :Value: File creation time (seconds since the Epoch). 439 :Allowed Values: Any value. 440 :Child Attributes: none 441 442B_HPKG_ATTRIBUTE_ID_FILE_CRTIM_NANOS ("file\:crtime:nanos") 443 :Type: uint 444 :Value: The nano seconds fraction of the file creation time. 445 :Allowed Values: Any value in [0, 999999999]. 446 :Default Value: 0 447 :Child Attributes: none 448 449B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE ("file\:attribute") 450 :Type: string 451 :Value: Name of the extended file attribute. 452 :Allowed Values: Any valid attribute name. 453 :Child Attributes: 454 455 - B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE: The type of the file attribute. 456 - B_HPKG_ATTRIBUTE_ID_DATA: The file attribute data. 457 458B_HPKG_ATTRIBUTE_ID_FILE_ATTRIBUTE_TYPE ("file\:attribute:type") 459 :Type: uint 460 :Value: Type of the file attribute. 461 :Allowed Values: Any value in [0, 0xffffffff]. 462 :Child Attributes: none 463 464B_HPKG_ATTRIBUTE_ID_DATA ("data") 465 :Type: data 466 :Value: Raw data of a file or attribute. 467 :Allowed Values: Any value. 468 469B_HPKG_ATTRIBUTE_ID_SYMLINK_PATH ("symlink:path") 470 :Type: string 471 :Value: The path the symlink refers to. 472 :Allowed Values: Any valid symlink path. 473 :Default Value: Empty string. 474 :Child Attributes: none 475 476TOC Attributes 477-------------- 478The TOC can directly contain any number of attributes of the 479B_HPKG_ATTRIBUTE_ID_DIRECTORY_ENTRY type, which in turn contain descendant 480attributes as specified in the previous section. Any other attributes are 481ignored. 482 483The Package Format 484================== 485This section specifies how informative package attributes (package-name, 486version, provides, requires, ...) are stored in a HPKG file. It builds on top of 487the container format, defining the types of attributes, their order, and allowed 488values. 489 490E.g. a ".PackageInfo" file, containing a package description that is being 491converted into a package file:: 492 493 name mypackage 494 version 0.7.2-1 495 architecture x86 496 summary "is a very nice package" 497 description "has lots of cool features\nand is written in MyC++" 498 vendor "Me, Myself & I, Inc." 499 packager "me@test.com" 500 copyrights { "(C) 2009-2011, Me, Myself & I, Inc." } 501 licenses { "Me, Myself & I Commercial License"; "MIT" } 502 provides { 503 cmd:me 504 lib:libmyself = 0.7 505 } 506 requires { 507 haiku >= r1 508 wget 509 } 510 511could be represented by this attribute tree: 512 513- B_HPKG_ATTRIBUTE_ID_PACKAGE_NAME : string : "mypackage" 514- B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR : string : "0" 515 516 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR : string : "7" 517 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO : string : "2" 518 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION : uint : 1 519 520- B_HPKG_ATTRIBUTE_ID_PACKAGE_ARCHITECTURE : uint : 1 521- B_HPKG_ATTRIBUTE_ID_PACKAGE_SUMMARY : string : "is a very nice package" 522- B_HPKG_ATTRIBUTE_ID_PACKAGE_DESCRIPTION : string : "has lots of cool features 523 \nand is written in MyC++" 524- B_HPKG_ATTRIBUTE_ID_PACKAGE_VENDOR : string : "Me, Myself & I, Inc." 525- B_HPKG_ATTRIBUTE_ID_PACKAGE_PACKAGER : string : "me@test.com" 526- B_HPKG_ATTRIBUTE_ID_PACKAGE_COPYRIGHT : string : "(C) 2009-2011, Me, Myself & 527 I, Inc." 528- B_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE : string : "Me, Myself & I Commercial 529 License" 530- B_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE : string : "MIT" 531- B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES : string : "cmd:me" 532- B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES : string : "lib:libmyself" 533 534 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR : string : "0" 535 536 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR : string : "7" 537 538- B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES : string : "haiku" 539 540 - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR : uint : 4 541 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR : string : "r1" 542 543- B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES : string : "wget" 544 545.. _The Package Format/Attribute IDs: 546 547Attribute IDs 548------------- 549B_HPKG_ATTRIBUTE_ID_PACKAGE_NAME ("package:name") 550 :Type: string 551 :Value: Name of the package. 552 :Allowed Values: Any string matching <entity_name_char>+, with 553 <entity_name_char> being any character but '-', '/', '=', '!', '<', '>', or 554 whitespace. 555 :Child Attributes: none 556 557B_HPKG_ATTRIBUTE_ID_PACKAGE_SUMMARY ("package:summary") 558 :Type: string 559 :Value: Short description of the package. 560 :Allowed Values: Any single-lined string. 561 :Child Attributes: none 562 563B_HPKG_ATTRIBUTE_ID_PACKAGE_DESCRIPTION ("package:description") 564 :Type: string 565 :Value: Long description of the package. 566 :Allowed Values: Any string (may contain multiple lines). 567 :Child Attributes: none 568 569B_HPKG_ATTRIBUTE_ID_PACKAGE_VENDOR ("package:vendor") 570 :Type: string 571 :Value: Name of the person/organization that is publishing this package. 572 :Allowed Values: Any single-lined string. 573 :Child Attributes: none 574 575B_HPKG_ATTRIBUTE_ID_PACKAGE_PACKAGER ("package:packager") 576 :Type: string 577 :Value: E-Mail address of person that created this package. 578 :Allowed Values: Any single-lined string, but e-mail preferred. 579 :Child Attributes: none 580 581B_HPKG_ATTRIBUTE_ID_PACKAGE_BASE_PACKAGE ("package:base-package") 582 :Type: string 583 :Value: Name of the package that is the base package for this package. The 584 base package must also be listed as a requirement for this package (cf. 585 B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES). The package manager shall ensure that 586 this package is installed in the same installation location as its base 587 package. 588 :Allowed Values: Valid package names. 589 :Child Attributes: none 590 591B_HPKG_ATTRIBUTE_ID_PACKAGE_FLAGS ("package:flags") 592 :Type: uint 593 :Value: Set of boolean flags applying to package. 594 :Allowed Values: Any combination of the following. 595 596 = ============================== ========================================== 597 1 B_PACKAGE_FLAG_APPROVE_LICENSE this package's license requires approval 598 (i.e. must be shown to and acknowledged by 599 user before installation) 600 2 B_PACKAGE_FLAG_SYSTEM_PACKAGE this is a system package (i.e. lives under 601 /boot/system) 602 = ============================== ========================================== 603 604 :Default Value: 0 605 :Child Attributes: none 606 607B_HPKG_ATTRIBUTE_ID_PACKAGE_ARCHITECTURE ("package:architecture") 608 :Type: uint 609 :Value: System architecture this package was built for. 610 :Allowed Values: 611 612 = =============================== ========================================= 613 0 B_PACKAGE_ARCHITECTURE_ANY this package doesn't depend on the system 614 architecture 615 1 B_PACKAGE_ARCHITECTURE_X86 x86, 32-bit, built with gcc4 616 2 B_PACKAGE_ARCHITECTURE_X86_GCC2 x86, 32-bit, built with gcc2 617 3 B_PACKAGE_ARCHITECTURE_SOURCE source code, doesn't depend on the system 618 architecture 619 4 B_PACKAGE_ARCHITECTURE_X86_64 x86-64 620 5 B_PACKAGE_ARCHITECTURE_PPC PowerPC 621 6 B_PACKAGE_ARCHITECTURE_ARM ARM 622 7 B_PACKAGE_ARCHITECTURE_M68K m68k 623 = =============================== ========================================= 624 625 :Child Attributes: none 626 627B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR ("package:version.major") 628 :Type: string 629 :Value: Major (first) part of package version. 630 :Allowed Values: Any single-lined string, composed of <alphanum_underline> 631 :Child Attributes: 632 633 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR: The minor part of the package 634 version. 635 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO: The micro part of the package 636 version. 637 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_PRE_RELEASE: The pre-release part of 638 the package version. 639 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION: The revision part of the 640 package version. 641 642B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR ("package:version.minor") 643 :Type: string 644 :Value: Minor (second) part of package version. 645 :Allowed Values: Any single-lined string, composed of <alphanum_underline>. 646 :Child Attributes: none 647 648B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO ("package:version.micro") 649 :Type: string 650 :Value: Micro (third) part of package version. 651 :Allowed Values: Any single-lined string, composed of 652 <alphanum_underline_dot>. 653 :Child Attributes: none 654 655B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_PRE_RELEASE ("package:version.prerelease") 656 :Type: string 657 :Value: Pre-release (fourth) part of package version. Typically something like 658 "alpha1", "beta2", "rc3". 659 :Allowed Values: Any single-lined string, composed of 660 <alphanum_underline_dot>. 661 :Child Attributes: none 662 663B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION ("package:version.revision") 664 :Type: uint 665 :Value: Revision (fifth) part of package version. 666 :Allowed Values: Any integer greater than 0. 667 :Child Attributes: none 668 669B_HPKG_ATTRIBUTE_ID_PACKAGE_COPYRIGHT ("package:copyright") 670 :Type: string 671 :Value: Copyright applying to the software contained in this package. 672 :Allowed Values: Any (preferably single-lined) string. 673 :Child Attributes: none 674 675B_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE ("package:license") 676 :Type: string 677 :Value: Name of license applying to the software contained in this package. 678 :Allowed Values: Any single-lined string. 679 :Child Attributes: none 680 681B_HPKG_ATTRIBUTE_ID_PACKAGE_URL ("package:url") 682 :Type: string 683 :Value: URL of the packaged software's project home page. 684 :Allowed Values: A regular URL or an email-like named URL (e.g. 685 "Project Foo <http://foo.example.com>"). 686 :Child Attributes: none 687 688B_HPKG_ATTRIBUTE_ID_PACKAGE_SOURCE_URL ("package:source-url") 689 :Type: string 690 :Value: URL of the packaged software's source code or build instructions. 691 :Allowed Values: A regular URL or an email-like named URL (e.g. 692 "Project Foo <http://foo.example.com>"). 693 :Child Attributes: none 694 695B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES ("package:provides") 696 :Type: string 697 :Value: Name of a (optionally typed) entity that is being provided by this 698 package. 699 :Allowed Values: Any string matching <entity_name_char>+. 700 :Child Attributes: 701 702 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable 703 version. 704 - B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES_COMPATIBLE: The major part of the 705 resolvable compatible version. 706 707B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES_COMPATIBLE ("package:provides.compatible") 708 :Type: string 709 :Value: Major (first) part of the resolvable compatible version, structurally 710 identical to B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR. 711 :Allowed Values: Any string matching <entity_name_char>+. 712 :Child Attributes: 713 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR: The minor part of the resolvable 714 compatible version. 715 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO: The micro part of the resolvable 716 compatible version. 717 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_PRE_RELEASE: The pre-release part of 718 the resolvable compatible version. 719 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION: The revision part of the 720 resolvable compatible version. 721 722B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES ("package:requires") 723 :Type: string 724 :Value: Name of an entity that is required by this package (and hopefully 725 being provided by another). 726 :Allowed Values: Any string matching <entity_name_char>+. 727 :Child Attributes: 728 - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as 729 int. 730 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable 731 version. 732 733B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR ("package:resolvable.operator") 734 :Type: uint 735 :Value: Comparison operator for versions. 736 :Allowed Values: 737 738 = ===================================== =================================== 739 0 B_PACKAGE_RESOLVABLE_OP_LESS less than the specified version 740 1 B_PACKAGE_RESOLVABLE_OP_LESS_EQUAL less than or equal to the specified 741 version 742 2 B_PACKAGE_RESOLVABLE_OP_EQUAL equal to the specified version 743 3 B_PACKAGE_RESOLVABLE_OP_NOT_EQUAL not equal to the specified version 744 4 B_PACKAGE_RESOLVABLE_OP_GREATER_EQUAL greater than the specified version 745 5 B_PACKAGE_RESOLVABLE_OP_GREATER greater than or equal to the 746 specified version 747 = ===================================== =================================== 748 749 :Child Attributes: none 750 751B_HPKG_ATTRIBUTE_ID_PACKAGE_SUPPLEMENTS ("package:supplements") 752 :Type: string 753 :Value: Name of an entity that is supplemented by this package (i.e. this 754 package will automatically be selected for installation if the supplemented 755 resolvables are already installed). 756 :Allowed Values: Any string matching <entity_name_char>+. 757 :Child Attributes: 758 - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as 759 int. 760 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable 761 version. 762 763B_HPKG_ATTRIBUTE_ID_PACKAGE_CONFLICTS ("package:conflicts") 764 :Type: string 765 :Value: Name of an entity that this package conflicts with (i.e. only one of 766 both can be installed at any time). 767 :Allowed Values: Any string matching <entity_name_char>+. 768 :Child Attributes: 769 - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as 770 int. 771 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable 772 version. 773 774B_HPKG_ATTRIBUTE_ID_PACKAGE_FRESHENS ("package:freshens") 775 :Type: string 776 :Value: Name of an entity that is being freshened by this package (i.e. this 777 package will patch one or more files of the package that provide this 778 resolvable). 779 :Allowed Values: Any string matching <entity_name_char>+. 780 :Child Attributes: 781 - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as 782 int. 783 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable 784 version. 785 786B_HPKG_ATTRIBUTE_ID_PACKAGE_REPLACES ("package:replaces") 787 :Type: string 788 :Value: Name of an entity that is being replaced by this package (used if the 789 name of a package changes, or if a package has been split). 790 :Allowed Values: Any string matching <entity_name_char>+. 791 :Child Attributes: none 792 793B_HPKG_ATTRIBUTE_ID_PACKAGE_CHECKSUM ("package:checksum") 794 :Type: string 795 :Value: SHA256-chechsum of this package, in hexdump format. N.B.: this 796 attribute can only be found in package repository files, not in package 797 files. 798 :Allowed Values: 64-bytes of hexdump. 799 :Child Attributes: none 800 801B_HPKG_ATTRIBUTE_ID_PACKAGE_GLOBAL_WRITABLE_FILE ("package:global-writable-file") 802 :Type: string 803 :Value: Relative path of a global writable file either included in the package 804 or created by the included software. If the file is included in the package, 805 it will be installed upon activation. In this case the attribute must 806 contain a B_HPKG_ATTRIBUTE_ID_PACKAGE_WRITABLE_FILE_UPDATE_TYPE child 807 attribute. The file may actually be a directory, which is indicated by the 808 B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY child attribute. 809 :Allowed Values: Installation location relative path (e.g. "settings/..."). 810 :Child Attributes: 811 - B_HPKG_ATTRIBUTE_ID_PACKAGE_WRITABLE_FILE_UPDATE_TYPE: Specifies what to do 812 with the writable file on package update. 813 - B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY: Specifies whether the 814 file is actually a directory. 815 816B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_SETTINGS_FILE ("package:user-settings-file") 817 :Type: string 818 :Value: Relative path of a user settings file created by the included software 819 or required by the software to be created by the user. The file may actually 820 be a directory, which is indicated by the 821 B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY child attribute. 822 :Allowed Values: Installation location relative path (i.e. "settings/..."). 823 :Child Attributes: 824 - B_HPKG_ATTRIBUTE_ID_PACKAGE_SETTINGS_FILE_TEMPLATE: A template for the 825 settings file. 826 - B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY: Specifies whether the 827 file is actually a directory. 828 829B_HPKG_ATTRIBUTE_ID_PACKAGE_WRITABLE_FILE_UPDATE_TYPE ("package:writable-file-update-type") 830 :Type: uint 831 :Value: Specifies what to do on package update when the writable file provided 832 by the package has been changed by the user. 833 :Allowed Values: 834 835 = ====================================== ================================== 836 0 B_WRITABLE_FILE_UPDATE_TYPE_KEEP_OLD the old file shall be kept 837 1 B_WRITABLE_FILE_UPDATE_TYPE_MANUAL the old file needs to be updated 838 manually 839 2 B_WRITABLE_FILE_UPDATE_TYPE_AUTO_MERGE an automatic three-way merge shall 840 be attempted 841 = ====================================== ================================== 842 843 :Child Attributes: none 844 845B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY ("package:is-writable-directory") 846 :Type: uint 847 :Value: Specifies whether the parent global writable file or user settings file attribute actually refers to a directory. 848 :Allowed Values: 849 850 = =========================================== 851 0 The parent attribute refers to a file. 852 1 The parent attribute refers to a directory. 853 = =========================================== 854 855 :Child Attributes: none 856 857B_HPKG_ATTRIBUTE_ID_PACKAGE_SETTINGS_FILE_TEMPLATE ("package:settings-file-template") 858 :Type: string 859 :Value: Relative path of an included template file for the user settings file. 860 :Allowed Values: Installation location relative path of a file included in the 861 package. 862 :Child Attributes: none 863 864B_HPKG_ATTRIBUTE_ID_PACKAGE_USER ("package:user") 865 :Type: string 866 :Value: Name of a user required by the package. Upon package activation the 867 user will be created, if necessary. 868 :Allowed Values: Any valid user name, i.e. must be non-empty composed of 869 <alphanum_underline>. 870 :Child Attributes: 871 - B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_REAL_NAME: The user's real name. 872 - B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_HOME: The user's home directory. 873 - B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_SHELL: The user's shell. 874 - B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_GROUP: The user's group(s). 875 876B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_REAL_NAME ("package:user.real-name") 877 :Type: string 878 :Value: The real name of the user. 879 :Allowed Values: Any string. 880 :Default Value: The user name. 881 :Child Attributes: none 882 883B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_HOME ("package:user.home") 884 :Type: string 885 :Value: The path to the home directory of the user. 886 :Allowed Values: Any valid path. 887 :Child Attributes: none 888 889B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_SHELL ("package:user.shell") 890 :Type: string 891 :Value: The path to the shell to be used for the user. 892 :Allowed Values: Any valid path. 893 :Default Value: "/bin/bash". 894 :Child Attributes: none 895 896B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_GROUP ("package:user.group") 897 :Type: string 898 :Value: A group the user belongs to. At least one must be specified. 899 :Allowed Values: Any valid group name, i.e. must be non-empty composed of 900 <alphanum_underline>. 901 :Default Value: The default group for users. 902 :Child Attributes: none 903 904B_HPKG_ATTRIBUTE_ID_PACKAGE_GROUP ("package:group") 905 :Type: string 906 :Value: Name of a group required by the package. Upon package activation the 907 group will be created, if necessary. 908 :Allowed Values: Any valid group name, i.e. must be non-empty composed of 909 <alphanum_underline>. 910 :Child Attributes: none 911 912B_HPKG_ATTRIBUTE_ID_PACKAGE_POST_INSTALL_SCRIPT ("package:post-install-script") 913 :Type: string 914 :Value: Relative path of a script that shall be executed after package 915 activation. 916 :Allowed Values: Installation location relative path of a file included in the 917 package. 918 :Child Attributes: none 919 920Haiku Package Repository Format 921=============================== 922Very similar to the package format, there's a Haiku Package Repository (HPKR) 923file format. Such a file contains informative attributes about the package 924repository and package attributes for all packages contained in the repository. 925However, this format does not contain any files. 926 927Two stacked format layers can be identified: 928 929- A generic container format for structured data. 930- A package format, extending the archive format with attributes for package 931 management. 932 933The Data Container Format 934------------------------- 935A HPKR file consists of three sections: 936 937Header 938 Identifies the file as HPKR file and provides access to the other sections. 939 940Heap 941 Contains the next two sections. 942 943Repository Info 944 A section containing an archived BMessage of a BRepositoryInfo object. 945 946Package Attributes 947 A section just like the package attributes section of the HPKG, only that this 948 section contains the package attributes of all the packages contained in the 949 repository (not just one). 950 951The Repository Info and Package Attributes sections aren't really separate 952sections, as they are stored at the end of the heap. 953 954Header 955`````` 956The header has the following structure:: 957 958 struct hpkg_repo_header { 959 uint32 magic; 960 uint16 header_size; 961 uint16 version; 962 uint64 total_size; 963 uint16 minor_version; 964 965 // heap 966 uint16 heap_compression; 967 uint32 heap_chunk_size; 968 uint64 heap_size_compressed; 969 uint64 heap_size_uncompressed; 970 971 // repository info section 972 uint32 info_length; 973 uint32 reserved1; 974 975 // package attributes section 976 uint64 packages_length; 977 uint64 packages_strings_length; 978 uint64 packages_strings_count; 979 }; 980 981magic 982 The string 'hpkr' (B_HPKG_REPO_MAGIC). 983 984header_size 985 The size of the header. This is also the absolute offset of the heap. 986 987version 988 The version of the HPKR format the file conforms to. The current version is 989 2 (B_HPKG_REPO_VERSION). 990 991total_size 992 The total file size. 993 994minor_version 995 The minor version of the HPKR format the file conforms to. The current minor 996 version is 0 (B_HPKG_REPO_MINOR_VERSION). Additions of new attributes to the 997 attributes section shouldgenerally only increment the minor version. When a 998 file with a greater minor version is encountered, the reader should ignore 999 unknown attributes. 1000 1001.. 1002 1003heap_compression 1004 Compression format used for the heap. 1005 1006heap_chunk_size 1007 The size of the chunks the uncompressed heap data are divided into. 1008 1009heap_size_compressed 1010 The compressed size of the heap. This includes all administrative data (the 1011 chunk size array). 1012 1013heap_size_uncompressed 1014 The uncompressed size of the heap. This is only the size of the raw data 1015 (including the repository info and attributes section), not including 1016 administrative data (the chunk size array). 1017 1018.. 1019 1020info_length 1021 The uncompressed size of the repository info section. 1022 1023.. 1024 1025reserved1 1026 Reserved for later use. 1027 1028.. 1029 1030packages_length 1031 The uncompressed size of the package attributes section. 1032 1033packages_strings_length 1034 The size of the strings subsection of the package attributes section. 1035 1036packages_strings_count 1037 The number of entries in the strings subsection of the package attributes 1038 section. 1039 1040Attribute IDs 1041------------- 1042The package repository format defines only the top-level attribute ID 1043B_HPKG_ATTRIBUTE_ID_PACKAGE. An attribute with that ID represents a package. Its 1044child attributes specify the various meta information for the package as defined 1045in the `The Package Format/Attribute IDs`_ section. 1046 1047