You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

825 lines
28 KiB

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