doc/cache.sgml

   1 <!doctype debiandoc system>
   2 <!-- -*- mode: sgml; mode: fold -*- -->
   3 <book>
   4 <title>APT Cache File Format</title>
   5
   6 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>
   7 <version>$Id: cache.sgml,v 1.8 2001/02/20 07:03:17 jgg Exp $</version>
   8
   9 <abstract>
  10 This document describes the complete implementation and format of the APT
  11 Cache file. The APT Cache file is a way for APT to parse and store a
  12 large number of package files for display in the UI. It's primary design
  13 goal is to make display of a single package in the tree very fast by
  14 pre-linking important things like dependencies and provides.
  15
  16 The specification doubles as documentation for one of the in-memory
  17 structures used by the package library and the APT GUI.
  18
  19 </abstract>
  20
  21 <copyright>
  22 Copyright &copy; Jason Gunthorpe, 1997-1998.
  23 <p>
  24 APT and this document are free software; you can redistribute them and/or
  25 modify them under the terms of the GNU General Public License as published
  26 by the Free Software Foundation; either version 2 of the License, or (at your
  27 option) any later version.
  28
  29 <p>
  30 For more details, on Debian GNU/Linux systems, see the file
  31 /usr/doc/copyright/GPL for the full license.
  32 </copyright>
  33
  34 <toc sect>
  35
  36 <chapt>Introduction
  37 <!-- Purpose                                                           {{{ -->
  38 <!-- ===================================================================== -->
  39 <sect>Purpose
  40
  41 <p>
  42 This document describes the implementation of an architecture
  43 dependent binary cache file. The goal of this cache file is two fold,
  44 firstly to speed loading and processing of the package file array and
  45 secondly to reduce memory consumption of the package file array.
  46
  47 <p>
  48 The implementation is aimed at an environment with many primary package
  49 files, for instance someone that has a Package file for their CD-ROM, a
  50 Package file for the latest version of the distribution on the CD-ROM and a
  51 package file for the development version. Always present is the information
  52 contained in the status file which might be considered a separate package
  53 file.
  54
  55 <p>
  56 Please understand, this is designed as a -CACHE FILE- it is not ment to be
  57 used on any system other than the one it was created for. It is not ment to
  58 be authoritative either, ie if a system crash or software failure occures it
  59 must be perfectly acceptable for the cache file to be in an inconsistant
  60 state. Furthermore at any time the cache file may be erased without losing
  61 any information.
  62
  63 <p>
  64 Also the structures and storage layout is optimized for use by the APT
  65 GUI and may not be suitable for all purposes. However it should be possible
  66 to extend it with associate cache files that contain other information.
  67
  68 <p>
  69 To keep memory use down the cache file only contains often used fields and
  70 fields that are inexepensive to store, the Package file has a full list of
  71 fields. Also the client may assume that all items are perfectly valid and
  72 need not perform checks against their correctness. Removal of information
  73 from the cache is possible, but blanks will be left in the file, and
  74 unused strings will also be present. The recommended implementation is to
  75 simply rebuild the cache each time any of the data files change. It is
  76 possible to add a new package file to the cache without any negative side
  77 effects.
  78
  79 <sect1>Note on Pointer access
  80 <p>
  81 Every item in every structure is stored as the index to that structure.
  82 What this means is that once the files is mmaped every data access has to
  83 go through a fixup stage to get a real memory pointer. This is done
  84 by taking the index, multiplying it by the type size and then adding
  85 it to the start address of the memory block. This sounds complex, but
  86 in C it is a single array dereference. Because all items are aligned to
  87 their size and indexs are stored as multiples of the size of the structure
  88 the format is immediately portable to all possible architectures - BUT the
  89 generated files are -NOT-.
  90
  91 <p>
  92 This scheme allows code like this to be written:
  93 <example>
  94   void *Map = mmap(...);
  95   Package *PkgList = (Package *)Map;
  96   Header *Head = (Header *)Map;
  97   char *Strings = (char *)Map;
  98   cout << (Strings + PkgList[Head->HashTable[0]]->Name) << endl;
  99 </example>
 100 <p>
 101 Notice the lack of casting or multiplication. The net result is to return
 102 the name of the first package in the first hash bucket, without error
 103 checks.
 104
 105 <p>
 106 The generator uses allocation pools to group similarly sized structures in
 107 large blocks to eliminate any alignment overhead. The generator also
 108 assures that no structures overlap and all indexes are unique. Although
 109 at first glance it may seem like there is the potential for two structures
 110 to exist at the same point the generator never allows this to happen.
 111 (See the discussion of free space pools)
 112                                                                   <!-- }}} -->
 113
 114 <chapt>Structures
 115 <!-- Header                                                            {{{ -->
 116 <!-- ===================================================================== -->
 117 <sect>Header
 118 <p>
 119 This is the first item in the file.
 120 <example>
 121    struct Header
 122    {
 123       // Signature information
 124       unsigned long Signature;
 125       short MajorVersion;
 126       short MinorVersion;
 127       bool Dirty;
 128
 129       // Size of structure values
 130       unsigned short HeaderSz;
 131       unsigned short PackageSz;
 132       unsigned short PackageFileSz;
 133       unsigned short VersionSz;
 134       unsigned short DependencySz;
 135       unsigned short ProvidesSz;
 136       unsigned short VerFileSz;
 137
 138       // Structure counts
 139       unsigned long PackageCount;
 140       unsigned long VersionCount;
 141       unsigned long DependsCount;
 142       unsigned long PackageFileCount;
 143
 144       // Offsets
 145       unsigned long FileList;              // PackageFile
 146       unsigned long StringList;            // StringItem
 147       unsigned long VerSysName;            // StringTable
 148       unsigned long Architecture;          // StringTable
 149       unsigned long MaxVerFileSize;
 150
 151       // Allocation pools
 152       struct
 153       {
 154          unsigned long ItemSize;
 155          unsigned long Start;
 156          unsigned long Count;
 157       } Pools[7];
 158
 159       // Package name lookup
 160       unsigned long HashTable[2*1024];        // Package
 161    };
 162 </example>
 163 <taglist>
 164 <tag>Signature<item>
 165 This must contain the hex value 0x98FE76DC which is designed to verify
 166 that the system loading the image has the same byte order and byte size as
 167 the system saving the image
 168
 169 <tag>MajorVersion
 170 <tag>MinorVersion<item>
 171 These contain the version of the cache file, currently 0.2.
 172
 173 <tag>Dirty<item>
 174 Dirty is true if the cache file was opened for reading, the client expects
 175 to have written things to it and have not fully synced it. The file should
 176 be erased and rebuilt if it is true.
 177
 178 <tag>HeaderSz
 179 <tag>PackageSz
 180 <tag>PackageFileSz
 181 <tag>VersionSz
 182 <tag>DependencySz
 183 <tag>VerFileSz
 184 <tag>ProvidesSz<item>
 185 *Sz contains the sizeof() that particular structure. It is used as an
 186 extra consistancy check on the structure of the file.
 187
 188 If any of the size values do not exactly match what the client expects then
 189 the client should refuse the load the file.
 190
 191 <tag>PackageCount
 192 <tag>VersionCount
 193 <tag>DependsCount
 194 <tag>PackageFileCount<item>
 195 These indicate the number of each structure contianed in the cache.
 196 PackageCount is especially useful for generating user state structures.
 197 See Package::Id for more info.
 198
 199 <tag>VerSysName<item>
 200 String representing the versiong system used for this cache
 201
 202 <tag>Architecture<item>
 203 Architecture the cache was built against.
 204
 205 <tag>MaxVerFileSize<item>
 206 The maximum size of a raw entry from the original Package file
 207 (ie VerFile::Size) is stored here.
 208
 209 <tag>FileList<item>
 210 This contains the index of the first PackageFile structure. The PackageFile
 211 structures are singely linked lists that represent all package files that
 212 have been merged into the cache.
 213
 214 <tag>StringList<item>
 215 This contains a list of all the unique strings (string item type strings) in
 216 the cache. The parser reads this list into memory so it can match strings
 217 against it.
 218
 219 <tag>Pools<item>
 220 The Pool structures manage the allocation pools that the generator uses.
 221 Start indicates the first byte of the pool, Count is the number of objects
 222 remaining in the pool and ItemSize is the structure size (alignment factor)
 223 of the pool. An ItemSize of 0 indicates the pool is empty. There should be
 224 the same number of pools as there are structure types. The generator
 225 stores this information so future additions can make use of any unused pool
 226 blocks.
 227
 228 <tag>HashTable<item>
 229 HashTable is a hash table that provides indexing for all of the packages.
 230 Each package name is inserted into the hash table using the following has
 231 function:
 232 <example>
 233    unsigned long Hash(string Str)
 234    {
 235       unsigned long Hash = 0;
 236       for (const char *I = Str.begin(); I != Str.end(); I++)
 237          Hash += *I * ((Str.end() - I + 1));
 238       return Hash % _count(Head.HashTable);
 239    }
 240 </example>
 241 <p>
 242 By iterating over each entry in the hash table it is possible to iterate over
 243 the entire list of packages. Hash Collisions are handled with a singely linked
 244 list of packages based at the hash item. The linked list contains only
 245 packages that macth the hashing function.
 246
 247 </taglist>
 248                                                                   <!-- }}} -->
 249 <!-- Package                                                           {{{ -->
 250 <!-- ===================================================================== -->
 251 <sect>Package
 252 <p>
 253 This contians information for a single unique package. There can be any
 254 number of versions of a given package. Package exists in a singly
 255 linked list of package records starting at the hash index of the name in
 256 the Header->HashTable.
 257 <example>
 258    struct Pacakge
 259    {
 260       // Pointers
 261       unsigned long Name;              // Stringtable
 262       unsigned long VersionList;       // Version
 263       unsigned long CurrentVer;        // Version
 264       unsigned long Section;           // StringTable (StringItem)
 265
 266       // Linked lists
 267       unsigned long NextPackage;       // Package
 268       unsigned long RevDepends;        // Dependency
 269       unsigned long ProvidesList;      // Provides
 270
 271       // Install/Remove/Purge etc
 272       unsigned char SelectedState;     // What
 273       unsigned char InstState;         // Flags
 274       unsigned char CurrentState;      // State
 275
 276       // Unique ID for this pkg
 277       unsigned short ID;
 278       unsigned long Flags;
 279    };
 280 </example>
 281
 282 <taglist>
 283 <tag>Name<item>
 284 Name of the package.
 285
 286 <tag>VersionList<item>
 287 Base of a singely linked list of version structures. Each structure
 288 represents a unique version of the package. The version structures
 289 contain links into PackageFile and the original text file as well as
 290 detailed infromation about the size and dependencies of the specific
 291 package. In this way multiple versions of a package can be cleanly handled
 292 by the system. Furthermore, this linked list is guarenteed to be sorted
 293 from Highest version to lowest version with no duplicate entries.
 294
 295 <tag>CurrentVer<item>
 296 CurrentVer is an index to the installed version, either can be
 297 0.
 298
 299 <tag>Section<item>
 300 This indicates the deduced section. It should be "Unknown" or the section
 301 of the last parsed item.
 302
 303 <tag>NextPackage<item>
 304 Next link in this hash item. This linked list is based at Header.HashTable
 305 and contains only packages with the same hash value.
 306
 307 <tag>RevDepends<item>
 308 Reverse Depends is a linked list of all dependencies linked to this package.
 309
 310 <tag>ProvidesList<item>
 311 This is a linked list of all provides for this package name.
 312
 313 <tag>SelectedState
 314 <tag>InstState
 315 <tag>CurrentState<item>
 316 These corrispond to the 3 items in the Status field found in the status
 317 file. See the section on defines for the possible values.
 318 <p>
 319 SelectedState is the state that the user wishes the package to be
 320 in.
 321 <p>
 322 InstState is the installation state of the package. This normally
 323 should be Ok, but if the installation had an accident it may be otherwise.
 324 <p>
 325 CurrentState indicates if the package is installed, partially installed or
 326 not installed.
 327
 328 <tag>ID<item>
 329 ID is a value from 0 to Header->PackageCount. It is a unique value assigned
 330 by the generator. This allows clients to create an array of size PackageCount
 331 and use it to store state information for the package map. For instance the
 332 status file emitter uses this to track which packages have been emitted
 333 already.
 334
 335 <tag>Flags<item>
 336 Flags are some useful indicators of the package's state.
 337
 338 </taglist>
 339
 340                                                                   <!-- }}} -->
 341 <!-- PackageFile                                                       {{{ -->
 342 <!-- ===================================================================== -->
 343 <sect>PackageFile
 344 <p>
 345 This contians information for a single package file. Package files are
 346 referenced by Version structures. This is a singly linked list based from
 347 Header.FileList
 348 <example>
 349    struct PackageFile
 350    {
 351       // Names
 352       unsigned long FileName;        // Stringtable
 353       unsigned long Archive;         // Stringtable
 354       unsigned long Component;       // Stringtable
 355       unsigned long Version;         // Stringtable
 356       unsigned long Origin;          // Stringtable
 357       unsigned long Label;           // Stringtable
 358       unsigned long Architecture;    // Stringtable
 359       unsigned long Site;            // Stringtable
 360       unsigned long IndexType;       // Stringtable
 361       unsigned long Size;
 362
 363       // Linked list
 364       unsigned long NextFile;        // PackageFile
 365       unsigned short ID;
 366       unsigned long Flags;
 367       time_t mtime;                  // Modification time
 368    };
 369 </example>
 370 <taglist>
 371
 372 <tag>FileName<item>
 373 Refers the the physical disk file that this PacakgeFile represents.
 374
 375 <tag>Archive
 376 <tag>Component
 377 <tag>Version
 378 <tag>Origin
 379 <tag>Label
 380 <tag>Architecture
 381 <tag>NotAutomatic<item>
 382 This is the release information. Please see the files document for a
 383 description of what the release information means.
 384
 385 <tag>Site<item>
 386 The site the index file was fetched from.
 387
 388 <tag>IndexType<item>
 389 A string indicating what sort of index file this is.
 390
 391 <tag>Size<item>
 392 Size is provided as a simple check to ensure that the package file has not
 393 been altered.
 394
 395 <tag>ID<item>
 396 See Package::ID.
 397
 398 <tag>Flags<item>
 399 Provides some flags for the PackageFile, see the section on defines.
 400
 401 <tag>mtime<item>
 402 Modification time for the file at time of cache generation.
 403
 404 </taglist>
 405
 406                                                                   <!-- }}} -->
 407 <!-- Version                                                           {{{ -->
 408 <!-- ===================================================================== -->
 409 <sect>Version
 410 <p>
 411 This contians the information for a single version of a package. This is a
 412 singley linked list based from Package.Versionlist.
 413
 414 <p>
 415 The version list is always sorted from highest version to lowest version by
 416 the generator. Also there may not be any duplicate entries in the list (same
 417 VerStr).
 418
 419 <example>
 420    struct Version
 421    {
 422       unsigned long VerStr;            // Stringtable
 423       unsigned long Section;           // StringTable (StringItem)
 424       unsigned long Arch;              // StringTable
 425
 426       // Lists
 427       unsigned long FileList;          // VerFile
 428       unsigned long NextVer;           // Version
 429       unsigned long DependsList;       // Dependency
 430       unsigned long ParentPkg;         // Package
 431       unsigned long ProvidesList;      // Provides
 432
 433       unsigned long Size;
 434       unsigned long InstalledSize;
 435       unsigned long Hash;
 436       unsigned short ID;
 437       unsigned char Priority;
 438    };
 439 </example>
 440 <taglist>
 441
 442 <tag>VerStr<item>
 443 This is the complete version string.
 444
 445 <tag>FileList<item>
 446 References the all the PackageFile's that this version came out of. FileList
 447 can be used to determine what distribution(s) the Version applies to. If
 448 FileList is 0 then this is a blank version. The structure should also have
 449 a 0 in all other fields excluding VerStr and Possibly NextVer.
 450
 451 <tag>Section<item>
 452 This string indicates which section it is part of. The string should be
 453 contained in the StringItem list.
 454
 455 <tag>Arch<item>
 456 Architecture the package was compiled for.
 457
 458 <tag>NextVer<item>
 459 Next step in the linked list.
 460
 461 <tag>DependsList<item>
 462 This is the base of the dependency list.
 463
 464 <tag>ParentPkg<item>
 465 This links the version to the owning package, allowing reverse dependencies
 466 to determine the package.
 467
 468 <tag>ProvidesList<item>
 469 Head of the linked list of Provides::NextPkgProv, forward provides.
 470
 471 <tag>Size
 472 <tag>InstalledSize<item>
 473 The archive size for this version. For debian this is the size of the .deb
 474 file. Installed size is the uncompressed size for this version
 475
 476 <tag>Hash<item>
 477 This is a characteristic value representing this package. No two packages
 478 in existance should have the same VerStr and Hash with different contents.
 479
 480 <tag>ID<item>
 481 See Package::ID.
 482
 483 <tag>Priority<item>
 484 This is the parsed priority value of the package.
 485 </taglist>
 486
 487                                                                   <!-- }}} -->
 488 <!-- Dependency                                                        {{{ -->
 489 <!-- ===================================================================== -->
 490 <sect>Dependency
 491 <p>
 492 Dependency contains the information for a single dependency record. The records
 493 are split up like this to ease processing by the client. The base of list
 494 linked list is Version.DependsList. All forms of dependencies are recorded
 495 here including Conflicts, Suggests and Recommends.
 496
 497 <p>
 498 Multiple depends on the same package must be grouped together in
 499 the Dependency lists. Clients should assume this is always true.
 500
 501 <example>
 502     struct Dependency
 503     {
 504        unsigned long Version;         // Stringtable
 505        unsigned long Package;         // Package
 506        unsigned long NextDepends;     // Dependency
 507        unsigned long NextRevDepends;  // Reverse dependency linking
 508        unsigned long ParentVer;       // Upwards parent version link
 509
 510        // Specific types of depends
 511        unsigned char Type;
 512        unsigned char CompareOp;
 513        unsigned short ID;
 514     };
 515 </example>
 516 <taglist>
 517 <tag>Version<item>
 518 The string form of the version that the dependency is applied against.
 519
 520 <tag>Package<item>
 521 The index of the package file this depends applies to. If the package file
 522 does not already exist when the dependency is inserted a blank one (no
 523 version records) should be created.
 524
 525 <tag>NextDepends<item>
 526 Linked list based off a Version structure of all the dependencies in that
 527 version.
 528
 529 <tag>NextRevDepends<item>
 530 Reverse dependency linking, based off a Package structure. This linked list
 531 is a list of all packages that have a depends line for a given package.
 532
 533 <tag>ParentVer<item>
 534 Parent version linking, allows the reverse dependency list to link
 535 back to the version and package that the dependency are for.
 536
 537 <tag>Type<item>
 538 Describes weather it is depends, predepends, recommends, suggests, etc.
 539
 540 <tag>CompareOp<item>
 541 Describes the comparison operator specified on the depends line. If the high
 542 bit is set then it is a logical or with the previous record.
 543
 544 <tag>ID<item>
 545 See Package::ID.
 546
 547 </taglist>
 548
 549                                                                   <!-- }}} -->
 550 <!-- Provides                                                          {{{ -->
 551 <!-- ===================================================================== -->
 552 <sect>Provides
 553 <p>
 554 Provides handles virtual packages. When a Provides: line is encountered
 555 a new provides record is added associating the package with a virtual
 556 package name. The provides structures are linked off the package structures.
 557 This simplifies the analysis of dependencies and other aspects A provides
 558 refers to a specific version of a specific package, not all versions need to
 559 provide that provides.
 560
 561 <p>
 562 There is a linked list of provided package names started from each
 563 version that provides packages. This is the forwards provides mechanism.
 564 <example>
 565     struct Provides
 566     {
 567        unsigned long ParentPkg;        // Package
 568        unsigned long Version;          // Version
 569        unsigned long ProvideVersion;   // Stringtable
 570        unsigned long NextProvides;     // Provides
 571        unsigned long NextPkgProv;      // Provides
 572     };
 573 </example>
 574 <taglist>
 575 <tag>ParentPkg<item>
 576 The index of the package that head of this linked list is in. ParentPkg->Name
 577 is the name of the provides.
 578
 579 <tag>Version<item>
 580 The index of the version this provide line applies to.
 581
 582 <tag>ProvideVersion<item>
 583 Each provides can specify a version in the provides line. This version allows
 584 dependencies to depend on specific versions of a Provides, as well as allowing
 585 Provides to override existing packages. This is experimental.
 586
 587 <tag>NextProvides<item>
 588 Next link in the singly linked list of provides (based off package)
 589
 590 <tag>NextPkgProv<item>
 591 Next link in the singly linked list of provides for 'Version'.
 592
 593 </taglist>
 594
 595                                                                   <!-- }}} -->
 596 <!-- VerFile                                                           {{{ -->
 597 <!-- ===================================================================== -->
 598 <sect>VerFile
 599 <p>
 600 VerFile associates a version with a PackageFile, this allows a full
 601 description of all Versions in all files (and hence all sources) under
 602 consideration.
 603
 604 <example>
 605     struct pkgCache::VerFile
 606     {
 607        unsigned long File;           // PackageFile
 608        unsigned long NextFile;       // PkgVerFile
 609        unsigned long Offset;
 610        unsigned short Size;
 611     }
 612 </example>
 613 <taglist>
 614 <tag>File<item>
 615 The index of the package file that this version was found in.
 616
 617 <tag>NextFile<item>
 618 The next step in the linked list.
 619
 620 <tag>Offset
 621 <tag>Size<item>
 622 These describe the exact position in the package file for the section from
 623 this version.
 624 </taglist>
 625
 626                                                                   <!-- }}} -->
 627 <!-- StringItem                                                        {{{ -->
 628 <!-- ===================================================================== -->
 629 <sect>StringItem
 630 <p>
 631 StringItem is used for generating single instances of strings. Some things
 632 like Section Name are are useful to have as unique tags. It is part of
 633 a linked list based at Header::StringList.
 634 <example>
 635    struct StringItem
 636    {
 637       unsigned long String;        // Stringtable
 638       unsigned long NextItem;      // StringItem
 639    };
 640 </example>
 641 <taglist>
 642 <tag>String<item>
 643 The string this refers to.
 644
 645 <tag>NextItem<item>
 646 Next link in the chain.
 647 </taglist>
 648                                                                   <!-- }}} -->
 649 <!-- StringTable                                                       {{{ -->
 650 <!-- ===================================================================== -->
 651 <sect>StringTable
 652 <p>
 653 All strings are simply inlined any place in the file that is natural for the
 654 writer. The client should make no assumptions about the positioning of
 655 strings. All stringtable values point to a byte offset from the start of the
 656 file that a null terminated string will begin.
 657                                                                   <!-- }}} -->
 658 <!-- Defines                                                           {{{ -->
 659 <!-- ===================================================================== -->
 660 <sect>Defines
 661 <p>
 662 Several structures use variables to indicate things. Here is a list of all
 663 of them.
 664
 665 <sect1>Definitions for Dependency::Type
 666 <p>
 667 <example>
 668 #define pkgDEP_Depends 1
 669 #define pkgDEP_PreDepends 2
 670 #define pkgDEP_Suggests 3
 671 #define pkgDEP_Recommends 4
 672 #define pkgDEP_Conflicts 5
 673 #define pkgDEP_Replaces 6
 674 </example>
 675 </sect1>
 676
 677 <sect1>Definitions for Dependency::CompareOp
 678 <p>
 679 <example>
 680 #define pkgOP_OR 0x10
 681 #define pkgOP_LESSEQ 0x1
 682 #define pkgOP_GREATEREQ 0x2
 683 #define pkgOP_LESS 0x3
 684 #define pkgOP_GREATER 0x4
 685 #define pkgOP_EQUALS 0x5
 686 </example>
 687 The lower 4 bits are used to indicate what operator is being specified and
 688 the upper 4 bits are flags. pkgOP_OR indicates that the next package is
 689 or'd with the current package.
 690 </sect1>
 691
 692 <sect1>Definitions for Package::SelectedState
 693 <p>
 694 <example>
 695 #define pkgSTATE_Unkown 0
 696 #define pkgSTATE_Install 1
 697 #define pkgSTATE_Hold 2
 698 #define pkgSTATE_DeInstall 3
 699 #define pkgSTATE_Purge 4
 700 </example>
 701 </sect1>
 702
 703 <sect1>Definitions for Package::InstState
 704 <p>
 705 <example>
 706 #define pkgSTATE_Ok 0
 707 #define pkgSTATE_ReInstReq 1
 708 #define pkgSTATE_Hold 2
 709 #define pkgSTATE_HoldReInstReq 3
 710 </example>
 711 </sect1>
 712
 713 <sect1>Definitions for Package::CurrentState
 714 <p>
 715 <example>
 716 #define pkgSTATE_NotInstalled 0
 717 #define pkgSTATE_UnPacked 1
 718 #define pkgSTATE_HalfConfigured 2
 719 #define pkgSTATE_UnInstalled 3
 720 #define pkgSTATE_HalfInstalled 4
 721 #define pkgSTATE_ConfigFiles 5
 722 #define pkgSTATE_Installed 6
 723 </example>
 724 </sect1>
 725
 726 <sect1>Definitions for Package::Flags
 727 <p>
 728 <example>
 729 #define pkgFLAG_Auto (1 << 0)
 730 #define pkgFLAG_New (1 << 1)
 731 #define pkgFLAG_Obsolete (1 << 2)
 732 #define pkgFLAG_Essential (1 << 3)
 733 #define pkgFLAG_ImmediateConf (1 << 4)
 734 </example>
 735 </sect1>
 736
 737 <sect1>Definitions for Version::Priority
 738 <p>
 739 Zero is used for unparsable or absent Priority fields.
 740 <example>
 741 #define pkgPRIO_Important 1
 742 #define pkgPRIO_Required 2
 743 #define pkgPRIO_Standard 3
 744 #define pkgPRIO_Optional 4
 745 #define pkgPRIO_Extra 5
 746 </example>
 747 </sect1>
 748
 749 <sect1>Definitions for PackageFile::Flags
 750 <p>
 751 <example>
 752 #define pkgFLAG_NotSource (1 << 0)
 753 #define pkgFLAG_NotAutomatic (1 << 1)
 754 </example>
 755 </sect1>
 756
 757                                                                   <!-- }}} -->
 758
 759 <chapt>Notes on the Generator
 760 <!-- Notes on the Generator                                            {{{ -->
 761 <!-- ===================================================================== -->
 762 <p>
 763 The pkgCache::MergePackageFile function is currently the only generator of
 764 the cache file. It implements a conversion from the normal textual package
 765 file into the cache file.
 766
 767 <p>
 768 The generator assumes any package declaration with a
 769 Status: line is a 'Status of the package' type of package declaration.
 770 A Package with a Target-Version field should also really have a status field.
 771 The processing of a Target-Version field can create a place-holder Version
 772 structure that is empty to refer to the specified version (See Version
 773 for info on what a empty Version looks like). The Target-Version syntax
 774 allows the specification of a specific version and a target distribution.
 775
 776 <p>
 777 Different section names on different versions is supported, but I
 778 do not expect to use it. To simplify the GUI it will mearly use the section
 779 in the Package structure. This should be okay as I hope sections do not change
 780 much.
 781
 782 <p>
 783 The generator goes through a number of post processing steps after producing
 784 a disk file. It sorts all of the version lists to be in descending order
 785 and then generates the reverse dependency lists for all of the packages.
 786 ID numbers and count values are also generated in the post processing step.
 787
 788 <p>
 789 It is possible to extend many of the structures in the cache with extra data.
 790 This is done by using the ID member. ID will be a unique number from 0 to
 791 Header->??Count. For example
 792 <example>
 793 struct MyPkgData;
 794 MyPkgData *Data = new MyPkgData[Header->PackageCount];
 795 Data[Package->ID]->Item = 0;
 796 </example>
 797 This provides a one way reference between package structures and user data. To
 798 get a two way reference would require a member inside the MyPkgData structure.
 799
 800 <p>
 801 The generators use of free space pools tend to make the package file quite
 802 large, and quite full of blank space. This could be fixed with sparse files.
 803
 804                                                                   <!-- }}} -->
 805
 806 <chapt>Future Directions
 807 <!-- Future Directions                                                 {{{ -->
 808 <!-- ===================================================================== -->
 809 <p>
 810 Some good directions to take the cache file is into a cache directory that
 811 contains many associated caches that cache other important bits of
 812 information. (/var/cache/apt, FHS2)
 813
 814 <p>
 815 Caching of the info/*.list is an excellent place to start, by generating all
 816 the list files into a tree structure and reverse linking them to the package
 817 structures in the main cache file major speed gains in dpkg might be achived.
 818
 819                                                                   <!-- }}} -->
 820
 821 </book>