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.6 1999/02/01 02:22:11 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       unsigned long MaxVerFileSize;
 144
 145       // Offsets
 146       unsigned long FileList;              // PackageFile
 147       unsigned long StringList;            // StringItem
 148
 149       // Allocation pools
 150       struct
 151       {
 152          unsigned long ItemSize;
 153          unsigned long Start;
 154          unsigned long Count;
 155       } Pools[7];
 156
 157       // Package name lookup
 158       unsigned long HashTable[512];        // Package
 159    };
 160 </example>
 161 <taglist>
 162 <tag>Signature<item>
 163 This must contain the hex value 0x98FE76DC which is designed to verify
 164 that the system loading the image has the same byte order and byte size as
 165 the system saving the image
 166
 167 <tag>MajorVersion
 168 <tag>MinorVersion<item>
 169 These contain the version of the cache file, currently 0.2.
 170
 171 <tag>Dirty<item>
 172 Dirty is true if the cache file was opened for reading, the client expects
 173 to have written things to it and have not fully synced it. The file should
 174 be erased and rebuilt if it is true.
 175
 176 <tag>HeaderSz
 177 <tag>PackageSz
 178 <tag>PackageFileSz
 179 <tag>VersionSz
 180 <tag>DependencySz
 181 <tag>VerFileSz
 182 <tag>ProvidesSz<item>
 183 *Sz contains the sizeof() that particular structure. It is used as an
 184 extra consistancy check on the structure of the file.
 185
 186 If any of the size values do not exactly match what the client expects then
 187 the client should refuse the load the file.
 188
 189 <tag>PackageCount
 190 <tag>VersionCount
 191 <tag>DependsCount
 192 <tag>PackageFileCount<item>
 193 These indicate the number of each structure contianed in the cache.
 194 PackageCount is especially usefull for generating user state structures.
 195 See Package::Id for more info.
 196
 197 <tag>MaxVerFileSize<item>
 198 The maximum size of a raw entry from the original Package file
 199 (ie VerFile::Size) is stored here.
 200
 201 <tag>FileList<item>
 202 This contains the index of the first PackageFile structure. The PackageFile
 203 structures are singely linked lists that represent all package files that
 204 have been merged into the cache.
 205
 206 <tag>StringList<item>
 207 This contains a list of all the unique strings (string item type strings) in
 208 the cache. The parser reads this list into memory so it can match strings
 209 against it.
 210
 211 <tag>Pools<item>
 212 The Pool structures manage the allocation pools that the generator uses.
 213 Start indicates the first byte of the pool, Count is the number of objects
 214 remaining in the pool and ItemSize is the structure size (alignment factor)
 215 of the pool. An ItemSize of 0 indicates the pool is empty. There should be
 216 the same number of pools as there are structure types. The generator
 217 stores this information so future additions can make use of any unused pool
 218 blocks.
 219
 220 <tag>HashTable<item>
 221 HashTable is a hash table that provides indexing for all of the packages.
 222 Each package name is inserted into the hash table using the following has
 223 function:
 224 <example>
 225    unsigned long Hash(string Str)
 226    {
 227       unsigned long Hash = 0;
 228       for (const char *I = Str.begin(); I != Str.end(); I++)
 229          Hash += *I * ((Str.end() - I + 1));
 230       return Hash % _count(Head.HashTable);
 231    }
 232 </example>
 233 <p>
 234 By iterating over each entry in the hash table it is possible to iterate over
 235 the entire list of packages. Hash Collisions are handled with a singely linked
 236 list of packages based at the hash item. The linked list contains only
 237 packages that macth the hashing function.
 238
 239 </taglist>
 240                                                                   <!-- }}} -->
 241 <!-- Package                                                           {{{ -->
 242 <!-- ===================================================================== -->
 243 <sect>Package
 244 <p>
 245 This contians information for a single unique package. There can be any
 246 number of versions of a given package. Package exists in a singly
 247 linked list of package records starting at the hash index of the name in
 248 the Header->HashTable.
 249 <example>
 250    struct Pacakge
 251    {
 252       // Pointers
 253       unsigned long Name;              // Stringtable
 254       unsigned long VersionList;       // Version
 255       unsigned long TargetVer;         // Version
 256       unsigned long CurrentVer;        // Version
 257       unsigned long TargetDist;        // StringTable (StringItem)
 258       unsigned long Section;           // StringTable (StringItem)
 259
 260       // Linked lists
 261       unsigned long NextPackage;       // Package
 262       unsigned long RevDepends;        // Dependency
 263       unsigned long ProvidesList;      // Provides
 264
 265       // Install/Remove/Purge etc
 266       unsigned char SelectedState;     // What
 267       unsigned char InstState;         // Flags
 268       unsigned char CurrentState;      // State
 269
 270       // Unique ID for this pkg
 271       unsigned short ID;
 272       unsigned long Flags;
 273    };
 274 </example>
 275
 276 <taglist>
 277 <tag>Name<item>
 278 Name of the package.
 279
 280 <tag>VersionList<item>
 281 Base of a singely linked list of version structures. Each structure
 282 represents a unique version of the package. The version structures
 283 contain links into PackageFile and the original text file as well as
 284 detailed infromation about the size and dependencies of the specific
 285 package. In this way multiple versions of a package can be cleanly handled
 286 by the system. Furthermore, this linked list is guarenteed to be sorted
 287 from Highest version to lowest version with no duplicate entries.
 288
 289 <tag>TargetVer
 290 <tag>CurrentVer<item>
 291 This is an index (pointer) to the sub version that is being targeted for
 292 upgrading. CurrentVer is an index to the installed version, either can be
 293 0.
 294
 295 <tag>TargetDist<item>
 296 This indicates the target distribution. Automatic upgrades should not go
 297 outside of the specified dist. If it is 0 then the global target dist should
 298 be used. The string should be contained in the StringItem list.
 299
 300 <tag>Section<item>
 301 This indicates the deduced section. It should be "Unknown" or the section
 302 of the last parsed item.
 303
 304 <tag>NextPackage<item>
 305 Next link in this hash item. This linked list is based at Header.HashTable
 306 and contains only packages with the same hash value.
 307
 308 <tag>RevDepends<item>
 309 Reverse Depends is a linked list of all dependencies linked to this package.
 310
 311 <tag>ProvidesList<item>
 312 This is a linked list of all provides for this package name.
 313
 314 <tag>SelectedState
 315 <tag>InstState
 316 <tag>CurrentState<item>
 317 These corrispond to the 3 items in the Status field found in the status
 318 file. See the section on defines for the possible values.
 319 <p>
 320 SelectedState is the state that the user wishes the package to be
 321 in.
 322 <p>
 323 InstState is the installation state of the package. This normally
 324 should be Ok, but if the installation had an accident it may be otherwise.
 325 <p>
 326 CurrentState indicates if the package is installed, partially installed or
 327 not installed.
 328
 329 <tag>ID<item>
 330 ID is a value from 0 to Header->PackageCount. It is a unique value assigned
 331 by the generator. This allows clients to create an array of size PackageCount
 332 and use it to store state information for the package map. For instance the
 333 status file emitter uses this to track which packages have been emitted
 334 already.
 335
 336 <tag>Flags<item>
 337 Flags are some usefull indicators of the package's state.
 338
 339 </taglist>
 340
 341                                                                   <!-- }}} -->
 342 <!-- PackageFile                                                       {{{ -->
 343 <!-- ===================================================================== -->
 344 <sect>PackageFile
 345 <p>
 346 This contians information for a single package file. Package files are
 347 referenced by Version structures. This is a singly linked list based from
 348 Header.FileList
 349 <example>
 350    struct PackageFile
 351    {
 352       // Names
 353       unsigned long FileName;        // Stringtable
 354       unsigned long Archive;         // Stringtable
 355       unsigned long Component;       // Stringtable
 356       unsigned long Version;         // Stringtable
 357       unsigned long Origin;          // Stringtable
 358       unsigned long Label;           // Stringtable
 359       unsigned long Architecture;    // Stringtable
 360       unsigned long Size;
 361
 362       // Linked list
 363       unsigned long NextFile;        // PackageFile
 364       unsigned short ID;
 365       unsigned long Flags;
 366       time_t mtime;                  // Modification time
 367    };
 368 </example>
 369 <taglist>
 370
 371 <tag>FileName<item>
 372 Refers the the physical disk file that this PacakgeFile represents.
 373
 374 <tag>Archive
 375 <tag>Component
 376 <tag>Version
 377 <tag>Origin
 378 <tag>Label
 379 <tag>Architecture
 380 <tag>NotAutomatic<item>
 381 This is the release information. Please see the files document for a
 382 description of what the release information means.
 383
 384 <tag>Size<item>
 385 Size is provided as a simple check to ensure that the package file has not
 386 been altered.
 387
 388 <tag>ID<item>
 389 See Package::ID.
 390
 391 <tag>Flags<item>
 392 Provides some flags for the PackageFile, see the section on defines.
 393
 394 <tag>mtime<item>
 395 Modification time for the file at time of cache generation.
 396
 397 </taglist>
 398
 399                                                                   <!-- }}} -->
 400 <!-- Version                                                           {{{ -->
 401 <!-- ===================================================================== -->
 402 <sect>Version
 403 <p>
 404 This contians the information for a single version of a package. This is a
 405 singley linked list based from Package.Versionlist.
 406
 407 <p>
 408 The version list is always sorted from highest version to lowest version by
 409 the generator. Also there may not be any duplicate entries in the list (same
 410 VerStr).
 411
 412 <example>
 413    struct Version
 414    {
 415       unsigned long VerStr;            // Stringtable
 416       unsigned long Section;           // StringTable (StringItem)
 417       unsigned long Arch;              // StringTable
 418
 419       // Lists
 420       unsigned long FileList;          // VerFile
 421       unsigned long NextVer;           // Version
 422       unsigned long DependsList;       // Dependency
 423       unsigned long ParentPkg;         // Package
 424       unsigned long ProvidesList;      // Provides
 425
 426       unsigned long Size;
 427       unsigned long InstalledSize;
 428       unsigned short ID;
 429       unsigned char Priority;
 430    };
 431 </example>
 432 <taglist>
 433
 434 <tag>VerStr<item>
 435 This is the complete version string.
 436
 437 <tag>FileList<item>
 438 References the all the PackageFile's that this version came out of. FileList
 439 can be used to determine what distribution(s) the Version applies to. If
 440 FileList is 0 then this is a blank version. The structure should also have
 441 a 0 in all other fields excluding VerStr and Possibly NextVer.
 442
 443 <tag>Section<item>
 444 This string indicates which section it is part of. The string should be
 445 contained in the StringItem list.
 446
 447 <tag>Arch<item>
 448 Architecture the package was compiled for.
 449
 450 <tag>NextVer<item>
 451 Next step in the linked list.
 452
 453 <tag>DependsList<item>
 454 This is the base of the dependency list.
 455
 456 <tag>ParentPkg<item>
 457 This links the version to the owning package, allowing reverse dependencies
 458 to determine the package.
 459
 460 <tag>ProvidesList<item>
 461 Head of the linked list of Provides::NextPkgProv, forward provides.
 462
 463 <tag>Size
 464 <tag>InstalledSize<item>
 465 The archive size for this version. For debian this is the size of the .deb
 466 file. Installed size is the uncompressed size for this version
 467
 468 <tag>ID<item>
 469 See Package::ID.
 470
 471 <tag>Priority<item>
 472 This is the parsed priority value of the package.
 473 </taglist>
 474
 475                                                                   <!-- }}} -->
 476 <!-- Dependency                                                        {{{ -->
 477 <!-- ===================================================================== -->
 478 <sect>Dependency
 479 <p>
 480 Dependency contains the information for a single dependency record. The records
 481 are split up like this to ease processing by the client. The base of list
 482 linked list is Version.DependsList. All forms of dependencies are recorded
 483 here including Conflicts, Suggests and Recommends.
 484
 485 <p>
 486 Multiple depends on the same package must be grouped together in
 487 the Dependency lists. Clients should assume this is always true.
 488
 489 <example>
 490     struct Dependency
 491     {
 492        unsigned long Version;         // Stringtable
 493        unsigned long Package;         // Package
 494        unsigned long NextDepends;     // Dependency
 495        unsigned long NextRevDepends;  // Reverse dependency linking
 496        unsigned long ParentVer;       // Upwards parent version link
 497
 498        // Specific types of depends
 499        unsigned char Type;
 500        unsigned char CompareOp;
 501        unsigned short ID;
 502     };
 503 </example>
 504 <taglist>
 505 <tag>Version<item>
 506 The string form of the version that the dependency is applied against.
 507
 508 <tag>Package<item>
 509 The index of the package file this depends applies to. If the package file
 510 does not already exist when the dependency is inserted a blank one (no
 511 version records) should be created.
 512
 513 <tag>NextDepends<item>
 514 Linked list based off a Version structure of all the dependencies in that
 515 version.
 516
 517 <tag>NextRevDepends<item>
 518 Reverse dependency linking, based off a Package structure. This linked list
 519 is a list of all packages that have a depends line for a given package.
 520
 521 <tag>ParentVer<item>
 522 Parent version linking, allows the reverse dependency list to link
 523 back to the version and package that the dependency are for.
 524
 525 <tag>Type<item>
 526 Describes weather it is depends, predepends, recommends, suggests, etc.
 527
 528 <tag>CompareOp<item>
 529 Describes the comparison operator specified on the depends line. If the high
 530 bit is set then it is a logical or with the previous record.
 531
 532 <tag>ID<item>
 533 See Package::ID.
 534
 535 </taglist>
 536
 537                                                                   <!-- }}} -->
 538 <!-- Provides                                                          {{{ -->
 539 <!-- ===================================================================== -->
 540 <sect>Provides
 541 <p>
 542 Provides handles virtual packages. When a Provides: line is encountered
 543 a new provides record is added associating the package with a virtual
 544 package name. The provides structures are linked off the package structures.
 545 This simplifies the analysis of dependencies and other aspects A provides
 546 refers to a specific version of a specific package, not all versions need to
 547 provide that provides.
 548
 549 <p>
 550 There is a linked list of provided package names started from each
 551 version that provides packages. This is the forwards provides mechanism.
 552 <example>
 553     struct Provides
 554     {
 555        unsigned long ParentPkg;        // Package
 556        unsigned long Version;          // Version
 557        unsigned long ProvideVersion;   // Stringtable
 558        unsigned long NextProvides;     // Provides
 559        unsigned long NextPkgProv;      // Provides
 560     };
 561 </example>
 562 <taglist>
 563 <tag>ParentPkg<item>
 564 The index of the package that head of this linked list is in. ParentPkg->Name
 565 is the name of the provides.
 566
 567 <tag>Version<item>
 568 The index of the version this provide line applies to.
 569
 570 <tag>ProvideVersion<item>
 571 Each provides can specify a version in the provides line. This version allows
 572 dependencies to depend on specific versions of a Provides, as well as allowing
 573 Provides to override existing packages. This is experimental.
 574
 575 <tag>NextProvides<item>
 576 Next link in the singly linked list of provides (based off package)
 577
 578 <tag>NextPkgProv<item>
 579 Next link in the singly linked list of provides for 'Version'.
 580
 581 </taglist>
 582
 583                                                                   <!-- }}} -->
 584 <!-- VerFile                                                           {{{ -->
 585 <!-- ===================================================================== -->
 586 <sect>VerFile
 587 <p>
 588 VerFile associates a version with a PackageFile, this allows a full
 589 description of all Versions in all files (and hence all sources) under
 590 consideration.
 591
 592 <example>
 593     struct pkgCache::VerFile
 594     {
 595        unsigned long File;           // PackageFile
 596        unsigned long NextFile;       // PkgVerFile
 597        unsigned long Offset;
 598        unsigned short Size;
 599     }
 600 </example>
 601 <taglist>
 602 <tag>File<item>
 603 The index of the package file that this version was found in.
 604
 605 <tag>NextFile<item>
 606 The next step in the linked list.
 607
 608 <tag>Offset
 609 <tag>Size<item>
 610 These describe the exact position in the package file for the section from
 611 this version.
 612 </taglist>
 613
 614                                                                   <!-- }}} -->
 615 <!-- StringItem                                                        {{{ -->
 616 <!-- ===================================================================== -->
 617 <sect>StringItem
 618 <p>
 619 StringItem is used for generating single instances of strings. Some things
 620 like Section Name are are usefull to have as unique tags. It is part of
 621 a linked list based at Header::StringList.
 622 <example>
 623    struct StringItem
 624    {
 625       unsigned long String;        // Stringtable
 626       unsigned long NextItem;      // StringItem
 627    };
 628 </example>
 629 <taglist>
 630 <tag>String<item>
 631 The string this refers to.
 632
 633 <tag>NextItem<item>
 634 Next link in the chain.
 635 </taglist>
 636                                                                   <!-- }}} -->
 637 <!-- StringTable                                                       {{{ -->
 638 <!-- ===================================================================== -->
 639 <sect>StringTable
 640 <p>
 641 All strings are simply inlined any place in the file that is natural for the
 642 writer. The client should make no assumptions about the positioning of
 643 strings. All stringtable values point to a byte offset from the start of the
 644 file that a null terminated string will begin.
 645                                                                   <!-- }}} -->
 646 <!-- Defines                                                           {{{ -->
 647 <!-- ===================================================================== -->
 648 <sect>Defines
 649 <p>
 650 Several structures use variables to indicate things. Here is a list of all
 651 of them.
 652
 653 <sect1>Definitions for Dependency::Type
 654 <p>
 655 <example>
 656 #define pkgDEP_Depends 1
 657 #define pkgDEP_PreDepends 2
 658 #define pkgDEP_Suggests 3
 659 #define pkgDEP_Recommends 4
 660 #define pkgDEP_Conflicts 5
 661 #define pkgDEP_Replaces 6
 662 </example>
 663 </sect1>
 664
 665 <sect1>Definitions for Dependency::CompareOp
 666 <p>
 667 <example>
 668 #define pkgOP_OR 0x10
 669 #define pkgOP_LESSEQ 0x1
 670 #define pkgOP_GREATEREQ 0x2
 671 #define pkgOP_LESS 0x3
 672 #define pkgOP_GREATER 0x4
 673 #define pkgOP_EQUALS 0x5
 674 </example>
 675 The lower 4 bits are used to indicate what operator is being specified and
 676 the upper 4 bits are flags. pkgOP_OR indicates that the next package is
 677 or'd with the current package.
 678 </sect1>
 679
 680 <sect1>Definitions for Package::SelectedState
 681 <p>
 682 <example>
 683 #define pkgSTATE_Unkown 0
 684 #define pkgSTATE_Install 1
 685 #define pkgSTATE_Hold 2
 686 #define pkgSTATE_DeInstall 3
 687 #define pkgSTATE_Purge 4
 688 </example>
 689 </sect1>
 690
 691 <sect1>Definitions for Package::InstState
 692 <p>
 693 <example>
 694 #define pkgSTATE_Ok 0
 695 #define pkgSTATE_ReInstReq 1
 696 #define pkgSTATE_Hold 2
 697 #define pkgSTATE_HoldReInstReq 3
 698 </example>
 699 </sect1>
 700
 701 <sect1>Definitions for Package::CurrentState
 702 <p>
 703 <example>
 704 #define pkgSTATE_NotInstalled 0
 705 #define pkgSTATE_UnPacked 1
 706 #define pkgSTATE_HalfConfigured 2
 707 #define pkgSTATE_UnInstalled 3
 708 #define pkgSTATE_HalfInstalled 4
 709 #define pkgSTATE_ConfigFiles 5
 710 #define pkgSTATE_Installed 6
 711 </example>
 712 </sect1>
 713
 714 <sect1>Definitions for Package::Flags
 715 <p>
 716 <example>
 717 #define pkgFLAG_Auto (1 << 0)
 718 #define pkgFLAG_New (1 << 1)
 719 #define pkgFLAG_Obsolete (1 << 2)
 720 #define pkgFLAG_Essential (1 << 3)
 721 #define pkgFLAG_ImmediateConf (1 << 4)
 722 </example>
 723 </sect1>
 724
 725 <sect1>Definitions for Version::Priority
 726 <p>
 727 Zero is used for unparsable or absent Priority fields.
 728 <example>
 729 #define pkgPRIO_Important 1
 730 #define pkgPRIO_Required 2
 731 #define pkgPRIO_Standard 3
 732 #define pkgPRIO_Optional 4
 733 #define pkgPRIO_Extra 5
 734 </example>
 735 </sect1>
 736
 737 <sect1>Definitions for PackageFile::Flags
 738 <p>
 739 <example>
 740 #define pkgFLAG_NotSource (1 << 0)
 741 #define pkgFLAG_NotAutomatic (1 << 1)
 742 </example>
 743 </sect1>
 744
 745                                                                   <!-- }}} -->
 746
 747 <chapt>Notes on the Generator
 748 <!-- Notes on the Generator                                            {{{ -->
 749 <!-- ===================================================================== -->
 750 <p>
 751 The pkgCache::MergePackageFile function is currently the only generator of
 752 the cache file. It implements a conversion from the normal textual package
 753 file into the cache file.
 754
 755 <p>
 756 The generator assumes any package declaration with a
 757 Status: line is a 'Status of the package' type of package declaration.
 758 A Package with a Target-Version field should also really have a status field.
 759 The processing of a Target-Version field can create a place-holder Version
 760 structure that is empty to refer to the specified version (See Version
 761 for info on what a empty Version looks like). The Target-Version syntax
 762 allows the specification of a specific version and a target distribution.
 763
 764 <p>
 765 Different section names on different versions is supported, but I
 766 do not expect to use it. To simplify the GUI it will mearly use the section
 767 in the Package structure. This should be okay as I hope sections do not change
 768 much.
 769
 770 <p>
 771 The generator goes through a number of post processing steps after producing
 772 a disk file. It sorts all of the version lists to be in descending order
 773 and then generates the reverse dependency lists for all of the packages.
 774 ID numbers and count values are also generated in the post processing step.
 775
 776 <p>
 777 It is possible to extend many of the structures in the cache with extra data.
 778 This is done by using the ID member. ID will be a unique number from 0 to
 779 Header->??Count. For example
 780 <example>
 781 struct MyPkgData;
 782 MyPkgData *Data = new MyPkgData[Header->PackageCount];
 783 Data[Package->ID]->Item = 0;
 784 </example>
 785 This provides a one way reference between package structures and user data. To
 786 get a two way reference would require a member inside the MyPkgData structure.
 787
 788 <p>
 789 The generators use of free space pools tend to make the package file quite
 790 large, and quite full of blank space. This could be fixed with sparse files.
 791
 792                                                                   <!-- }}} -->
 793
 794 <chapt>Future Directions
 795 <!-- Future Directions                                                 {{{ -->
 796 <!-- ===================================================================== -->
 797 <p>
 798 Some good directions to take the cache file is into a cache directory that
 799 contains many associated caches that cache other important bits of
 800 information. (/var/cache/apt, FHS2)
 801
 802 <p>
 803 Caching of the info/*.list is an excellent place to start, by generating all
 804 the list files into a tree structure and reverse linking them to the package
 805 structures in the main cache file major speed gains in dpkg might be achived.
 806
 807                                                                   <!-- }}} -->
 808
 809 </book>