| 1 | <!-- -*- mode: sgml; mode: fold -*- --> |
| 2 | <!doctype debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN"> |
| 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.11 2003/02/12 15:05:44 doogie 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 © 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/share/common-licenses/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 meant to be |
| 57 | used on any system other than the one it was created for. It is not meant to |
| 58 | be authoritative either, i.e. if a system crash or software failure occurs it |
| 59 | must be perfectly acceptable for the cache file to be in an inconsistent |
| 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 inexpensive 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 indexes 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 consistency 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 contained 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 version 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 | (i.e. 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 singly 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 singly linked |
| 244 | list of packages based at the hash item. The linked list contains only |
| 245 | packages that match the hashing function. |
| 246 | |
| 247 | </taglist> |
| 248 | <!-- }}} --> |
| 249 | <!-- Package {{{ --> |
| 250 | <!-- ===================================================================== --> |
| 251 | <sect>Package |
| 252 | <p> |
| 253 | This contains 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 singly 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 information 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 guaranteed 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 correspond 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 contains 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 contains the information for a single version of a package. This is a |
| 412 | single 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 existence 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 merely 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 achieved. |
| 818 | |
| 819 | <!-- }}} --> |
| 820 | |
| 821 | </book> |