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