- use automake defined pkgdata dir for lua script dir instead of hardcoded
[apt.git] / doc / cache.sgml
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 &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/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>