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 1 (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 8 B_PACKAGE_ARCHITECTURE_SPARC sparc 624 = =============================== ========================================= 625 626 :Child Attributes: none 627 628B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR ("package:version.major") 629 :Type: string 630 :Value: Major (first) part of package version. 631 :Allowed Values: Any single-lined string, composed of <alphanum_underline> 632 :Child Attributes: 633 634 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR: The minor part of the package 635 version. 636 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO: The micro part of the package 637 version. 638 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_PRE_RELEASE: The pre-release part of 639 the package version. 640 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION: The revision part of the 641 package version. 642 643B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR ("package:version.minor") 644 :Type: string 645 :Value: Minor (second) part of package version. 646 :Allowed Values: Any single-lined string, composed of <alphanum_underline>. 647 :Child Attributes: none 648 649B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO ("package:version.micro") 650 :Type: string 651 :Value: Micro (third) part of package version. 652 :Allowed Values: Any single-lined string, composed of 653 <alphanum_underline_dot>. 654 :Child Attributes: none 655 656B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_PRE_RELEASE ("package:version.prerelease") 657 :Type: string 658 :Value: Pre-release (fourth) part of package version. Typically something like 659 "alpha1", "beta2", "rc3". 660 :Allowed Values: Any single-lined string, composed of 661 <alphanum_underline_dot>. 662 :Child Attributes: none 663 664B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION ("package:version.revision") 665 :Type: uint 666 :Value: Revision (fifth) part of package version. 667 :Allowed Values: Any integer greater than 0. 668 :Child Attributes: none 669 670B_HPKG_ATTRIBUTE_ID_PACKAGE_COPYRIGHT ("package:copyright") 671 :Type: string 672 :Value: Copyright applying to the software contained in this package. 673 :Allowed Values: Any (preferably single-lined) string. 674 :Child Attributes: none 675 676B_HPKG_ATTRIBUTE_ID_PACKAGE_LICENSE ("package:license") 677 :Type: string 678 :Value: Name of license applying to the software contained in this package. 679 :Allowed Values: Any single-lined string. 680 :Child Attributes: none 681 682B_HPKG_ATTRIBUTE_ID_PACKAGE_URL ("package:url") 683 :Type: string 684 :Value: URL of the packaged software's project home page. 685 :Allowed Values: A regular URL or an email-like named URL (e.g. 686 "Project Foo <http://foo.example.com>"). 687 :Child Attributes: none 688 689B_HPKG_ATTRIBUTE_ID_PACKAGE_SOURCE_URL ("package:source-url") 690 :Type: string 691 :Value: URL of the packaged software's source code or build instructions. 692 :Allowed Values: A regular URL or an email-like named URL (e.g. 693 "Project Foo <http://foo.example.com>"). 694 :Child Attributes: none 695 696B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES ("package:provides") 697 :Type: string 698 :Value: Name of a (optionally typed) entity that is being provided by this 699 package. 700 :Allowed Values: Any string matching <entity_name_char>+. 701 :Child Attributes: 702 703 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable 704 version. 705 - B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES_COMPATIBLE: The major part of the 706 resolvable compatible version. 707 708B_HPKG_ATTRIBUTE_ID_PACKAGE_PROVIDES_COMPATIBLE ("package:provides.compatible") 709 :Type: string 710 :Value: Major (first) part of the resolvable compatible version, structurally 711 identical to B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR. 712 :Allowed Values: Any string matching <entity_name_char>+. 713 :Child Attributes: 714 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MINOR: The minor part of the resolvable 715 compatible version. 716 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MICRO: The micro part of the resolvable 717 compatible version. 718 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_PRE_RELEASE: The pre-release part of 719 the resolvable compatible version. 720 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_REVISION: The revision part of the 721 resolvable compatible version. 722 723B_HPKG_ATTRIBUTE_ID_PACKAGE_REQUIRES ("package:requires") 724 :Type: string 725 :Value: Name of an entity that is required by this package (and hopefully 726 being provided by another). 727 :Allowed Values: Any string matching <entity_name_char>+. 728 :Child Attributes: 729 - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as 730 int. 731 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable 732 version. 733 734B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR ("package:resolvable.operator") 735 :Type: uint 736 :Value: Comparison operator for versions. 737 :Allowed Values: 738 739 = ===================================== =================================== 740 0 B_PACKAGE_RESOLVABLE_OP_LESS less than the specified version 741 1 B_PACKAGE_RESOLVABLE_OP_LESS_EQUAL less than or equal to the specified 742 version 743 2 B_PACKAGE_RESOLVABLE_OP_EQUAL equal to the specified version 744 3 B_PACKAGE_RESOLVABLE_OP_NOT_EQUAL not equal to the specified version 745 4 B_PACKAGE_RESOLVABLE_OP_GREATER_EQUAL greater than the specified version 746 5 B_PACKAGE_RESOLVABLE_OP_GREATER greater than or equal to the 747 specified version 748 = ===================================== =================================== 749 750 :Child Attributes: none 751 752B_HPKG_ATTRIBUTE_ID_PACKAGE_SUPPLEMENTS ("package:supplements") 753 :Type: string 754 :Value: Name of an entity that is supplemented by this package (i.e. this 755 package will automatically be selected for installation if the supplemented 756 resolvables are already installed). 757 :Allowed Values: Any string matching <entity_name_char>+. 758 :Child Attributes: 759 - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as 760 int. 761 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable 762 version. 763 764B_HPKG_ATTRIBUTE_ID_PACKAGE_CONFLICTS ("package:conflicts") 765 :Type: string 766 :Value: Name of an entity that this package conflicts with (i.e. only one of 767 both can be installed at any time). 768 :Allowed Values: Any string matching <entity_name_char>+. 769 :Child Attributes: 770 - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as 771 int. 772 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable 773 version. 774 775B_HPKG_ATTRIBUTE_ID_PACKAGE_FRESHENS ("package:freshens") 776 :Type: string 777 :Value: Name of an entity that is being freshened by this package (i.e. this 778 package will patch one or more files of the package that provide this 779 resolvable). 780 :Allowed Values: Any string matching <entity_name_char>+. 781 :Child Attributes: 782 - B_HPKG_ATTRIBUTE_ID_PACKAGE_RESOLVABLE_OPERATOR: The resolvable operator as 783 int. 784 - B_HPKG_ATTRIBUTE_ID_PACKAGE_VERSION_MAJOR: The major part of the resolvable 785 version. 786 787B_HPKG_ATTRIBUTE_ID_PACKAGE_REPLACES ("package:replaces") 788 :Type: string 789 :Value: Name of an entity that is being replaced by this package (used if the 790 name of a package changes, or if a package has been split). 791 :Allowed Values: Any string matching <entity_name_char>+. 792 :Child Attributes: none 793 794B_HPKG_ATTRIBUTE_ID_PACKAGE_CHECKSUM ("package:checksum") 795 :Type: string 796 :Value: SHA256-chechsum of this package, in hexdump format. N.B.: this 797 attribute can only be found in package repository files, not in package 798 files. 799 :Allowed Values: 64-bytes of hexdump. 800 :Child Attributes: none 801 802B_HPKG_ATTRIBUTE_ID_PACKAGE_GLOBAL_WRITABLE_FILE ("package:global-writable-file") 803 :Type: string 804 :Value: Relative path of a global writable file either included in the package 805 or created by the included software. If the file is included in the package, 806 it will be installed upon activation. In this case the attribute must 807 contain a B_HPKG_ATTRIBUTE_ID_PACKAGE_WRITABLE_FILE_UPDATE_TYPE child 808 attribute. The file may actually be a directory, which is indicated by the 809 B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY child attribute. 810 :Allowed Values: Installation location relative path (e.g. "settings/..."). 811 :Child Attributes: 812 - B_HPKG_ATTRIBUTE_ID_PACKAGE_WRITABLE_FILE_UPDATE_TYPE: Specifies what to do 813 with the writable file on package update. 814 - B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY: Specifies whether the 815 file is actually a directory. 816 817B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_SETTINGS_FILE ("package:user-settings-file") 818 :Type: string 819 :Value: Relative path of a user settings file created by the included software 820 or required by the software to be created by the user. The file may actually 821 be a directory, which is indicated by the 822 B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY child attribute. 823 :Allowed Values: Installation location relative path (i.e. "settings/..."). 824 :Child Attributes: 825 - B_HPKG_ATTRIBUTE_ID_PACKAGE_SETTINGS_FILE_TEMPLATE: A template for the 826 settings file. 827 - B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY: Specifies whether the 828 file is actually a directory. 829 830B_HPKG_ATTRIBUTE_ID_PACKAGE_WRITABLE_FILE_UPDATE_TYPE ("package:writable-file-update-type") 831 :Type: uint 832 :Value: Specifies what to do on package update when the writable file provided 833 by the package has been changed by the user. 834 :Allowed Values: 835 836 = ====================================== ================================== 837 0 B_WRITABLE_FILE_UPDATE_TYPE_KEEP_OLD the old file shall be kept 838 1 B_WRITABLE_FILE_UPDATE_TYPE_MANUAL the old file needs to be updated 839 manually 840 2 B_WRITABLE_FILE_UPDATE_TYPE_AUTO_MERGE an automatic three-way merge shall 841 be attempted 842 = ====================================== ================================== 843 844 :Child Attributes: none 845 846B_HPKG_ATTRIBUTE_ID_PACKAGE_IS_WRITABLE_DIRECTORY ("package:is-writable-directory") 847 :Type: uint 848 :Value: Specifies whether the parent global writable file or user settings file attribute actually refers to a directory. 849 :Allowed Values: 850 851 = =========================================== 852 0 The parent attribute refers to a file. 853 1 The parent attribute refers to a directory. 854 = =========================================== 855 856 :Child Attributes: none 857 858B_HPKG_ATTRIBUTE_ID_PACKAGE_SETTINGS_FILE_TEMPLATE ("package:settings-file-template") 859 :Type: string 860 :Value: Relative path of an included template file for the user settings file. 861 :Allowed Values: Installation location relative path of a file included in the 862 package. 863 :Child Attributes: none 864 865B_HPKG_ATTRIBUTE_ID_PACKAGE_USER ("package:user") 866 :Type: string 867 :Value: Name of a user required by the package. Upon package activation the 868 user will be created, if necessary. 869 :Allowed Values: Any valid user name, i.e. must be non-empty composed of 870 <alphanum_underline>. 871 :Child Attributes: 872 - B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_REAL_NAME: The user's real name. 873 - B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_HOME: The user's home directory. 874 - B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_SHELL: The user's shell. 875 - B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_GROUP: The user's group(s). 876 877B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_REAL_NAME ("package:user.real-name") 878 :Type: string 879 :Value: The real name of the user. 880 :Allowed Values: Any string. 881 :Default Value: The user name. 882 :Child Attributes: none 883 884B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_HOME ("package:user.home") 885 :Type: string 886 :Value: The path to the home directory of the user. 887 :Allowed Values: Any valid path. 888 :Child Attributes: none 889 890B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_SHELL ("package:user.shell") 891 :Type: string 892 :Value: The path to the shell to be used for the user. 893 :Allowed Values: Any valid path. 894 :Default Value: "/bin/bash". 895 :Child Attributes: none 896 897B_HPKG_ATTRIBUTE_ID_PACKAGE_USER_GROUP ("package:user.group") 898 :Type: string 899 :Value: A group the user belongs to. At least one must be specified. 900 :Allowed Values: Any valid group name, i.e. must be non-empty composed of 901 <alphanum_underline>. 902 :Default Value: The default group for users. 903 :Child Attributes: none 904 905B_HPKG_ATTRIBUTE_ID_PACKAGE_GROUP ("package:group") 906 :Type: string 907 :Value: Name of a group required by the package. Upon package activation the 908 group will be created, if necessary. 909 :Allowed Values: Any valid group name, i.e. must be non-empty composed of 910 <alphanum_underline>. 911 :Child Attributes: none 912 913B_HPKG_ATTRIBUTE_ID_PACKAGE_POST_INSTALL_SCRIPT ("package:post-install-script") 914 :Type: string 915 :Value: Relative path of a script that shall be executed after package 916 activation. 917 :Allowed Values: Installation location relative path of a file included in the 918 package. Must start with "boot/post-install/", so besides being run after 919 package installation, it also gets run on the first boot after the OS is 920 installed. 921 :Child Attributes: none 922 923B_HPKG_ATTRIBUTE_ID_PACKAGE_PRE_UNINSTALL_SCRIPT ("package:pre-uninstall-script") 924 :Type: string 925 :Value: Relative path of a script that shall be executed before package 926 deactivation. 927 :Allowed Values: Installation location relative path of a file included in 928 the package. For consistency, it is recommended to start with 929 "boot/pre-uninstall/". 930 :Child Attributes: none 931 932Haiku Package Repository Format 933=============================== 934Very similar to the package format, there's a Haiku Package Repository (HPKR) 935file format. Such a file contains informative attributes about the package 936repository and package attributes for all packages contained in the repository. 937However, this format does not contain any files. 938 939Two stacked format layers can be identified: 940 941- A generic container format for structured data. 942- A package format, extending the archive format with attributes for package 943 management. 944 945The Data Container Format 946------------------------- 947A HPKR file consists of three sections: 948 949Header 950 Identifies the file as HPKR file and provides access to the other sections. 951 952Heap 953 Contains the next two sections. 954 955Repository Info 956 A section containing an archived BMessage of a BRepositoryInfo object. 957 958Package Attributes 959 A section just like the package attributes section of the HPKG, only that this 960 section contains the package attributes of all the packages contained in the 961 repository (not just one). 962 963The Repository Info and Package Attributes sections aren't really separate 964sections, as they are stored at the end of the heap. 965 966Header 967`````` 968The header has the following structure:: 969 970 struct hpkg_repo_header { 971 uint32 magic; 972 uint16 header_size; 973 uint16 version; 974 uint64 total_size; 975 uint16 minor_version; 976 977 // heap 978 uint16 heap_compression; 979 uint32 heap_chunk_size; 980 uint64 heap_size_compressed; 981 uint64 heap_size_uncompressed; 982 983 // repository info section 984 uint32 info_length; 985 uint32 reserved1; 986 987 // package attributes section 988 uint64 packages_length; 989 uint64 packages_strings_length; 990 uint64 packages_strings_count; 991 }; 992 993magic 994 The string 'hpkr' (B_HPKG_REPO_MAGIC). 995 996header_size 997 The size of the header. This is also the absolute offset of the heap. 998 999version 1000 The version of the HPKR format the file conforms to. The current version is 1001 2 (B_HPKG_REPO_VERSION). 1002 1003total_size 1004 The total file size. 1005 1006minor_version 1007 The minor version of the HPKR format the file conforms to. The current minor 1008 version is 1 (B_HPKG_REPO_MINOR_VERSION). Additions of new attributes to the 1009 attributes section should generally only increment the minor version. When a 1010 file with a greater minor version is encountered, the reader should ignore 1011 unknown attributes. 1012 1013.. 1014 1015heap_compression 1016 Compression format used for the heap. 1017 1018heap_chunk_size 1019 The size of the chunks the uncompressed heap data are divided into. 1020 1021heap_size_compressed 1022 The compressed size of the heap. This includes all administrative data (the 1023 chunk size array). 1024 1025heap_size_uncompressed 1026 The uncompressed size of the heap. This is only the size of the raw data 1027 (including the repository info and attributes section), not including 1028 administrative data (the chunk size array). 1029 1030.. 1031 1032info_length 1033 The uncompressed size of the repository info section. 1034 1035.. 1036 1037reserved1 1038 Reserved for later use. 1039 1040.. 1041 1042packages_length 1043 The uncompressed size of the package attributes section. 1044 1045packages_strings_length 1046 The size of the strings subsection of the package attributes section. 1047 1048packages_strings_count 1049 The number of entries in the strings subsection of the package attributes 1050 section. 1051 1052Attribute IDs 1053------------- 1054The package repository format defines only the top-level attribute ID 1055B_HPKG_ATTRIBUTE_ID_PACKAGE. An attribute with that ID represents a package. Its 1056child attributes specify the various meta information for the package as defined 1057in the `The Package Format/Attribute IDs`_ section. 1058 1059