* merge of the debian-expermental-ma branch

  
* debian/control:
  - add dependency on zlib-dev for libapt-pkg-dev
* apt-pkg/cacheset.cc:
  - [ABI BREAK] add an ErrorType option to CacheSetHelper
* cmdline/apt-cache.cc:
  - use Notice instead of Error in the CacheSetHelper messages
    for compat reasons. Otherwise tools like sbuild blow up
  - return success in show if a virtual package was given
* debian/control:
  - remove libcurl3-gnutls-dev alternative as the package is gone
  - increase needed version of libcurl4-gnutls-dev to >= 7.19.0
    as we use CURLOPT_{ISSUERCERT,CRLFILE} (Closes: #589642)
* apt-pkg/deb/dpkgpm.cc:
  - Write architecture information to history file.
  - Add to history whether a change was automatic or not.
* apt-pkg/contrib/fileutl.cc:
  - Add FileFd::OpenDescriptor() (needed for python-apt's #383617).
* cmdline/apt-get.cc:
  - Support large filesystems by using statvfs64() instead of statvfs()
    and statfs64() instead of statfs() (Closes: #590513).
* apt-pkg/cdrom.cc:
  - Use link() instead of rename() for creating the CD database backup;
    otherwise there would be a short time without any database.
* apt-pkg/depcache.cc:
  - handle "circular" conflicts for "all" packages correctly
* cmdline/apt-cache.cc:
  - be able to omit dependency types in (r)depends (Closes: #319006)
  - show in (r)depends the canidate per default instead of newest
  - share the (r)depends code instead of codecopy
* apt-pkg/cacheset.cc:
  - move them back to the library as they look stable now
  - add a 'newest' pseudo target release as in pkg/newest
* apt-pkg/pkgcache.cc:
  - prefer non-virtual packages in FindPreferredPkg (Closes: #590041)
* test/integration/*:
  - add with bug#590041 testcase a small test "framework"
* apt-pkg/orderlist.cc:
  - try to install another or-group member in DepRemove before
    breaking the or group (Closes: #590438)
  - configure also the replacement before remove by adding Immediate flag

* apt-pkg/contrib/error.{cc,h}
  - docstring cleanup
  - add inline DumpError() to avoid subtle API break
* apt-pkg/contrib/error.{cc,h}:
  - remove constness of va_list parameter to fix build on amd64 and co
    Thanks Eric Valette! (Closes: #588610)
* apt-pkg/deb/debmetaindex.cc:
  - do not query each architecture for flat file archives
  - fix typo preventing display of architecture in Info()
* methods/bzip2.cc:
  - add a copycat of the old gzip.cc as we need it for bzip2 and lzma
* debian/rules:
  - Make DEB_BUILD_OPTIONS=noopt actually work by passing the right
    CXXFLAGS.
* apt-pkg/contrib/fileutl.{h,cc}:
  - Add support for reading of gzipped files with the new "ReadOnlyGzip"
    OpenMode. (Closes: #188407)
  - Link against zlib (in apt-pkg/makefile) and add zlib build dependency.
  - [ABI BREAK] This adds a new private member to FileFd, but its
    initialization is in the public header file.
* configure.in:
  - Check for zlib library and headers.
* apt-pkg/acquire-item.cc, apt-pkg/deb/debindexfile.cc,
  apt-pkg/deb/debrecords.cc, apt-pkg/deb/debsrcrecords.h,
  cmdline/apt-cache.cc:
  - Open Packages, Sources, and Translations indexes in "ReadOnlyGzip" mode.
* apt-pkg/deb/debindexfile.cc:
  - If we do not find uncompressed package/source/translation indexes, look
    for gzip compressed ones.
* apt-pkg/acquire-item.cc:
  - If the Acquire::GzipIndexes option is true and we download a gzipped
    index file, keep it as it is (and rename to .gz) instead of
    uncompressing it.
* doc/apt.conf.5.xml:
  - Document the new Acquire::GzipIndexes option.
* doc/po/apt-doc.pot, doc/po/de.po:
  - German translation of new Acquire::GzipIndexes option.
* Add test/test-indexes.sh:
  - Test behaviour of index retrieval and usage, in particular with
    uncompressed and gzip compressed indexes.
* methods/gzip.cc: With FileFd now being able to read gzipped files, there
  is no need for the gzip method any more to spawn an external gzip process.
  Rewrite it to use FileFd directly, which makes the code a lot simpler, and
  also using less memory and overhead.
* doc/apt.conf.5.xml:
  - add and document APT::Cache-{Start,Grow,Limit} options for mmap control
* apt-pkg/contrib/fileutl.cc:
  - do not fail von double close()
* cmdline/cacheset.cc:
  - doesn't include it in the library for now as it is too volatile
  - get the candidate either from an already built depcache
    or use the policy which is a bit faster than depcache generation
  - get packages by task^ with FromTask()
  - only print errors if all tries to get a package by string failed
  - factor out code to get a single package FromName()
  - check in Grouped* first without modifier interpretation
* cmdline/apt-get.cc:
  - use the cachsets in the install commands
  - make the specify order of packages irrelevant (Closes: #196021)
* apt-pkg/orderlist.cc:
  - untouched packages are never missing
* apt-pkg/packagemanager.cc:
  - packages that are not touched doesn't need to be unpacked
* debian/control:
  - remove intltool's dependency as it is an ubuntu artefact
* apt-pkg/depcache.cc:
  - SetCandidateVer for all pseudo packages
  - SetReInstall for the "all" package of a pseudo package
  - use the new MatchAgainstConfig for the DefaultRootSetFunc
  - always mark the all package if a pseudo package is marked for install
* apt-pkg/contrib/error.{cc,h}:
  - complete rewrite but use the same API
  - add NOTICE and DEBUG as new types of a message
  - add a simple stack handling to be able to delay error handling
* apt-pkg/aptconfiguration.cc:
  - show a deprecation notice for APT::Acquire::Translation
* apt-pkg/contrib/configuration.{cc,h}:
  - add a wrapper to match strings against configurable regex patterns
* apt-pkg/contrib/fileutl.cc:
  - show notice about ignored file instead of being always silent
  - add a Dir::Ignore-Files-Silently list option to control the notice
* apt-pkg/policy.h:
  - add another round of const& madness as the previous round accidentally
    NOT overrides the virtual GetCandidateVer() method (Closes: #587725)
* apt-pkg/pkgcachegen.{cc,h}:
  - make the used MMap moveable (and therefore dynamic resizeable) by
    applying (some) mad pointer magic (Closes: #195018)
* apt-pkg/deb/dpkgpm.cc:
  - make the apt/term.log output unbuffered (thanks to Matt Zimmerman)
* methods/ftp.h:
  - Handle different logins on the same server (Closes: #586904).
* apt-pkg/deb/deblistparser.cc:
  - Handle architecture wildcards (Closes: #547724).
* apt-pkg/versionmatch.cc:
  - Support matching pins by regular expressions or glob() like patterns,
    regular expressions have to be put between to slashes; for example,
    /.*/.
* apt-pkg/contrib/fileutl.cc:
  - Make FileFd replace files atomically in WriteTemp mode (for cache, etc).
* debian/control:
  - Set Standards-Version to 3.9.0
* apt-pkg/cachefile.h:
  - make pkgPolicy public again, libapt-pkg-perl (and probably
    others) get unhappy without that
* merge the remaining Ubuntu change:
  - on gpg verification failure warn and restore the last known
    good state
  - on failure display the IP of the server (useful for servers
    that use round robin DNS)
  - support Original-Maintainer in RewritePackageOrder
  - enable cdrom autodetection via libudev by default
  - show message about Vcs in use when apt-get source is run for
    packages maintained in a Vcs
  - better support transitional packages with mark auto-installed. 
    when the transitional package is in "oldlibs" the new package
    is not marked auto installed (same is true for section
    metapackages)
  - provide new "deb mirror://archive.foo/mirrors.list sid main"
    method expects a list of mirrors (generated on the server e.g.
    via geoip) and will use that, including cycle on failure
  - write apport crash file on package failure (disabled by default
    on debian until apport is available)
  - support mirror failure reporting (disabled by default on debian)

* apt-pkg/deb/dpkgpm.cc:
  - write Disappeared also to the history.log
  - forward manual-installed bit on package disappearance
* apt-pkg/deb/debsystem.cc:
  - add better config item for extended_states file
* apt-pkg/pkgcache.h:
  - switch {,Install-}Size to unsigned long long
* apt-pkg/depcache.cc:
  - do the autoremove mark process also for required packages to handle
    these illegally depending on lower priority packages (Closes: #583517)
  - try harder to find the other pseudo versions for autoremove multiarch
  - correct "Dangerous iterator usage" pointed out by cppcheck
  - deal with long long, not with int to remove 2GB Limit (LP: #250909)
  - deprecate AddSize with Multiplier as it is unused and switch to
    boolean instead to handle the sizes more gracefully.
  - switch i{Download,Usr}Size from double to (un)signed long long
* apt-pkg/aptconfiguration.cc:
  - remove duplicate architectures in getArchitectures()
* apt-pkg/indexrecords.{cc,h}:
  - backport forgotten Valid-Until patch from the obsolete experimental
    branch to prevent replay attacks better, thanks to Thomas Viehmann
    for the initial patch! (Closes: #499897)
  - add a constant Exists check for MetaKeys
* apt-pkg/acquire-item.cc:
  - do not try PDiff if it is not listed in the Meta file
  - sent Last-Modified header also for Translation files
* apt-pkg/cacheiterator.h:
  - let pkgCache::Iterator inherent std::iterator
* ftparchive/writer.h:
  - add a virtual destructor to FTWScanner class (for cppcheck)
* apt-pkg/cacheset.{cc,h}:
  - add simple wrapper around std::set for cache structures
  - move regex magic from apt-get to new FromRegEx method
  - move cmdline parsing from apt-cache to new FromCommandLine method
  - support special release-modifier 'installed' and 'candidate'
* apt-pkg/contrib/cmdline.cc:
  - fix segfault in SaveInConfig caused by writing over char[] sizes
* apt-pkg/pkgcache.cc:
  - get the best matching arch package from a group with FindPreferredPkg
* cmdline/apt-cache.cc:
  - make the search multiarch compatible by using GrpIterator instead
  - use pkgCacheFile and the new CacheSets all over the place
  - add --target-release option (Closes: #115520)
  - accept pkg/release and pkg=version in show and co. (Closes: #236270)
  - accept package versions in the unmet command
* cmdline/apt-get.cc:
  - use unsigned long long instead of double to store values it gets
* apt-pkg/cachefile.{cc,h}:
  - split Open() into submethods to be able to build only parts
  - make the OpProgress optional in the Cache buildprocess
  - store also the SourceList we use internally for export
* doc/apt.conf.5.xml:
  - document the new Valid-Until related options
* apt-pkg/contrib/strutl.cc:
  - split StrToTime() into HTTP1.1 and FTP date parser methods and
    use strptime() instead of some self-made scanf mangling
  - use the portable timegm shown in his manpage instead of a strange
    looking code copycat from wget
* ftparchive/writer.cc:
  - add ValidTime option to generate a Valid-Until header in Release file
* apt-pkg/policy.cc:
  - get the candidate right for a not-installed pseudo package if
    his non-pseudo friend is installed
* apt-pkg/indexcopy.cc:
  - move the gpg codecopy to a new method and use it also in methods/gpgv.cc
* cmdline/apt-get.cc:
  - rerun dpkg-source in source if --fix-broken is given (Closes: #576752)
  - don't suggest held packages as they are installed (Closes: #578135)
  - handle multiple --{tar,diff,dsc}-only options correctly
  - show at the end of the install process a list of disappeared packages
* cmdline/apt-cache.cc:
  - use GroupCount for package names in stats and add a package struct line
* methods/rred.cc:
  - use the patchfile modification time instead of the one from the
    "old" file - thanks to Philipp Weis for noticing! (Closes: #571541)
* debian/rules:
  - remove targets referring to CVS or arch as they are useless
  - use $(CURDIR) instead of $(pwd)
  - use dpkg-buildflags if available for CXXFLAGS
* README.arch:
  - remove the file completely as it has no use nowadays
* apt-pkg/depcache.cc:
  - be doublesure that the killer query is empty before starting reinstall
* methods/gpgv.cc:
  - remove the keyrings count limit by using vector magic
* contrib/mmap.cc:
  - clarify "MMap reached size limit" error message, thanks Ivan Masár!
* doc/apt.ent
  - add entities for the current oldstable/stable/testing codenames
* doc/sources.list.5.xml:
  - use stable-codename instead of stable in the examples (Closes: #531492)
* doc/apt_preferences.5.xml:
  - adapt some examples here to use current codenames as well
  - add "NotAutomatic: yes" handling, thanks Osamu Aoki (Closes: #490347)
* debian/libapt-pkg-doc.doc-base.cache:
  - remove yet another reference to the removed cache.sgml
* doc/apt-get.8.xml:
  - do not say explicit target_release_{name,version,codename}, it should
    be clear by itself and 'man' can break lines again (Closes: #566166)
  - remove the gnome-apt reference as it is removed from unstable
* apt-pkg/deb/dpkgpm.cc:
  - add 'disappear' to the known processing states, thanks Jonathan Nieder
* apt-pkg/packagemanager.h:
  - export info about disappeared packages with GetDisappearedPackages()
* methods/http.{cc,h}:
  - code cleanup, use enums instead of magic ints

* debian/rules:
  - spell out some less known options to reduce manpage consultation-rate
  - Use POSIX command substitution: $(<command sequence>)
  - Remove EOL whitespace (Closes: #577804)
* apt-pkg/acquire-item.cc:
  - Fix pkgAcqFile::Custom600Headers() to always return something.

* apt-pkg/depcache.cc:
  - rewrite the pseudo package reinstaller to be more intelligent
    in his package choices
* apt-pkg/packagemanager.cc:
  - don't try to "unpack" pseudo packages twice
* apt-pkg/contrib/fileutl.cc:
  - add a parent-guarded "mkdir -p" as CreateDirectory()
* apt-pkg/acquire.{cc,h}:
  - add a delayed constructor with Setup() for success reporting
  - check for and create directories in Setup if needed instead of
    error out unfriendly in the Constructor (Closes: #523920, #525783)
  - optional handle a lock file in Setup()
* apt-pkg/acquire-item.cc:
  - Acquire::ForceHash to force method for expected hash
* cmdline/apt-get.cc:
  - remove the lock file handling and let Acquire take care of it instead
  - display MD5Sum in --print-uris if not forced to use another method
    instead of displaying the strongest available (Closes: #576420)
  - regex for package names executed on Grp- not PkgIterator
  - show non-candidates as fallback for virtual packages (Closes: #578385)
  - set also "all" to this version for pseudo packages in TryToChangeVer
* apt-pkg/deb/dpkgpm.cc:
  - remove Chroot-Directory from files passed to install commands.
    Thanks to Kel Modderman for report & patch! (Closes: #577226)
* ftparchive/writer.cc:
  - remove 999 chars Files and Checksums rewrite limit (Closes: #577759)
* cmdline/apt-cache.cc:
  - align Installed and Candidate Version in policy so they can be compared
    easier, thanks Ralf Gesellensetter for the pointer! (Closes: #578657)
* doc/apt.ent:
  - Add a note about APT_CONFIG in the -c description (Closes: #578267)
* doc/po/de.po:
  - correct typos in german apt_preferences manpage, thanks Chris Leick!
* apt-pkg/sourcelist.cc:
  - be less strict and accept [option=value] as well
* apt-pkg/contrib/configuration.cc:
  - error out if #clear directive has no argument
* doc/files.sgml:
  - sync documentation with status quo, regarding files/directories in
    use, extended_states and uri schemes.
* doc/cache.sgml:
  - drop the file in favor of inplace documentation with doxygen
* apt-pkg/pkgcache.h:
  - enhance the Groups ABI by providing a ID as the other structs does
  - check also the size of the Group struct then checking for the others
* cmdline/apt-get.cc:
  - replace backticks with single quotes around fix-broken command
    in the broken packages message. (Closes: #577168)
* dselect/install:
  - modernize if-statements not to use 'x' (Closes: #577117)
  - replace backticks with POSIX $() (Closes: #577116)
* cmdline/apt-get.cc:
  - fix crash when pkg.VersionList() is empty
  - install html doxygen in libapt-pkg-doc 
* debian/control:
  - build-depend on doxygen
* apt-pkg/contrib/weakptr.h:
  - add a class WeakPointable which allows one to register weak pointers to
    an object which will be set to NULL when the object is deallocated.
* [ABI break] apt-pkg/acquire{-worker,-item,}.h:
  - subclass pkgAcquire::{Worker,Item,ItemDesc} from WeakPointable.
* apt-pkg/pkgcache.cc:
  - Merge fix from David to correct handling in single-arch environments.
* cmdline/apt-cache.cc:
  - Add a showauto command to apt-cache.
* cmdline/apt-get.cc:
  - Add apt-get markauto and unmarkauto commands.
* [BREAK] merge MultiArch-ABI. We don't support MultiArch,
  but we support the usage of the new ABI so libapt users
  can start to prepare for MultiArch (Closes: #536029)
* Ignore :qualifiers after package name in build dependencies
  in the library by default, but try to honour them in apt-get
  as we have some sort of MultiArch support ready (Closes: #558103)
* add translation of the manpages to PT (portuguese)
  Thanks to Américo Monteiro!
* Switch to dpkg-source 3.0 (native) format
* apt-pkg/depcache.cc:
  - remove Auto-Installed information from extended_states
    together with the package itself (Closes: #572364)
* cmdline/apt-mark:
  - don't crash if no arguments are given (Closes: #570962)
* debian/control:
  - remove some years old and obsolete Replaces
  - add automake/conf build-depends/conflicts as recommend by
    the autotools-dev README (Closes: #572615)
* apt-pkg/contrib/mmap.{h,cc}:
  - add char[] fallback for filesystems without shared writable
    mmap() like JFFS2. Thanks to Marius Vollmer for writing
    and to Loïc Minier for pointing to the patch! (Closes: #314334)
* doc/apt_preferences.5.xml:
  - fix two typos and be more verbose in the novice warning.
    Thanks to Osamu Aoki for pointing it out! (Closes: #567669)
  - fix a=sid vs. n=sid typo, thanks Ansgar Burchardt!
  - origin can be used to match a hostname (Closes: #352667)
  - remove wrong pin-priority is optional remark (Closes: #574944)
* apt-pkg/deb/dpkgpm.cc:
  - fix error message construction in OpenLog()
  - if available store the Commandline in the history
* cmdline/apt-get.cc:
  - add a --only-upgrade flag to install command (Closes: #572259)
  - fix memory leaks in error conditions in DoSource()
  - try version match in FindSrc first exact than fuzzy (LP: #551178)
* apt-pkg/contrib/cmndline.cc:
  - save Commandline in Commandline::AsString for logging
* apt-pkg/deb/debversion.cc:
  - consider absent of debian revision equivalent to 0 (Closes: #573592)
* doc/makefile, doc/*:
  - generate subdirectories for building the manpages in on the fly
    depending on the po files we have.
* apt-pkg/pkgcachegen.cc:
  - merge versions correctly even if multiple different versions
    with the same version number are available.
    Thanks to Magnus Holmgren for the patch! (Closes: #351056)
* ftparchive/writer.cc:
  - write LongDescriptions if they shouldn't be included in Packages
    file into i18n/Translation-en by default.
* doc/po/de.po:
  - correct a few typos in the german manpage translation.
    Thanks to Chris Leick and Georg Koppen! (Closes: #574962)
* apt-pkg/contrib/strutl.cc:
  - convert all toupper calls to tolower_ascii for a little speedup
* apt-pkg/contrib/strutl.cc:
  - always escape '%' (LP: #130289) (Closes: #500560)
  - unescape '%' sequence only if followed by 2 hex digit
  - username/password are urlencoded in proxy string (RFC 3986)

1 files changed, 422 insertions, 91 deletions

diff --git a/apt-pkg/pkgcache.h b/apt-pkg/pkgcache.h
index e8a3e1064..799521784 100644
--- a/apt-pkg/pkgcache.h
+++ b/apt-pkg/pkgcache.h
@@ -1,20 +1,75 @@
 // -*- mode: cpp; mode: fold -*-
 // Description								/*{{{*/
-// $Id: pkgcache.h,v 1.25 2001/07/01 22:28:24 jgg Exp $
-/* ######################################################################
-   
-   Cache - Structure definitions for the cache file
-   
-   Please see doc/apt-pkg/cache.sgml for a more detailed description of 
-   this format. Also be sure to keep that file up-to-date!!
-   
+/**\file pkgcache.h
+   \brief pkgCache - Structure definitions for the cache file
+
+   The goal of the cache file is two fold:
+   Firstly to speed loading and processing of the package file array and
+   secondly to reduce memory consumption of the package file array.
+
+   The implementation is aimed at an environment with many primary package
+   files, for instance someone that has a Package file for their CD-ROM, a
+   Package file for the latest version of the distribution on the CD-ROM and a
+   package file for the development version. Always present is the information
+   contained in the status file which might be considered a separate package
+   file.
+
+   Please understand, this is designed as a <b>Cache file</b> it is not meant to be
+   used on any system other than the one it was created for. It is not meant to
+   be authoritative either, i.e. if a system crash or software failure occurs it
+   must be perfectly acceptable for the cache file to be in an inconsistent
+   state. Furthermore at any time the cache file may be erased without losing
+   any information.
+
+   Also the structures and storage layout is optimized for use by the APT
+   and may not be suitable for all purposes. However it should be possible
+   to extend it with associate cache files that contain other information.
+
+   To keep memory use down the cache file only contains often used fields and
+   fields that are inexpensive to store, the Package file has a full list of
+   fields. Also the client may assume that all items are perfectly valid and
+   need not perform checks against their correctness. Removal of information
+   from the cache is possible, but blanks will be left in the file, and
+   unused strings will also be present. The recommended implementation is to
+   simply rebuild the cache each time any of the data files change. It is
+   possible to add a new package file to the cache without any negative side
+   effects.
+
+   <b>Note on Pointer access</b>
    Clients should always use the CacheIterators classes for access to the
-   cache. They provide a simple STL-like method for traversing the links
-   of the datastructure.
-   
-   See pkgcachegen.h for information about generating cache structures.
-   
-   ##################################################################### */
+   cache and the data in it. They also provide a simple STL-like method for
+   traversing the links of the datastructure.
+
+   Every item in every structure is stored as the index to that structure.
+   What this means is that once the files is mmaped every data access has to
+   go through a fix up stage to get a real memory pointer. This is done
+   by taking the index, multiplying it by the type size and then adding
+   it to the start address of the memory block. This sounds complex, but
+   in C it is a single array dereference. Because all items are aligned to
+   their size and indexes are stored as multiples of the size of the structure
+   the format is immediately portable to all possible architectures - BUT the
+   generated files are -NOT-.
+
+   This scheme allows code like this to be written:
+   <example>
+     void *Map = mmap(...);
+     Package *PkgList = (Package *)Map;
+     Header *Head = (Header *)Map;
+     char *Strings = (char *)Map;
+     cout << (Strings + PkgList[Head->HashTable[0]]->Name) << endl;
+   </example>
+   Notice the lack of casting or multiplication. The net result is to return
+   the name of the first package in the first hash bucket, without error
+   checks.
+
+   The generator uses allocation pools to group similarly sized structures in
+   large blocks to eliminate any alignment overhead. The generator also
+   assures that no structures overlap and all indexes are unique. Although
+   at first glance it may seem like there is the potential for two structures
+   to exist at the same point the generator never allows this to happen.
+   (See the discussion of free space pools)
+
+   See \ref pkgcachegen.h for more information about generating cache structures. */
 									/*}}}*/
 #ifndef PKGLIB_PKGCACHE_H
 #define PKGLIB_PKGCACHE_H
@@ -32,6 +87,7 @@ class pkgCache								/*{{{*/
    public:
    // Cache element predeclarations
    struct Header;
+   struct Group;
    struct Package;
    struct PackageFile;
    struct Version;
@@ -43,6 +99,8 @@ class pkgCache								/*{{{*/
    struct DescFile;
    
    // Iterators
+   template<typename Str, typename Itr> class Iterator;
+   class GrpIterator;
    class PkgIterator;
    class VerIterator;
    class DescIterator;
@@ -51,14 +109,6 @@ class pkgCache								/*{{{*/
    class PkgFileIterator;
    class VerFileIterator;
    class DescFileIterator;
-   friend class PkgIterator;
-   friend class VerIterator;
-   friend class DescInterator;
-   friend class DepIterator;
-   friend class PrvIterator;
-   friend class PkgFileIterator;
-   friend class VerFileIterator;
-   friend class DescFileIterator;
    
    class Namespace;
    
@@ -71,12 +121,20 @@ class pkgCache								/*{{{*/
    {
       enum DepType {Depends=1,PreDepends=2,Suggests=3,Recommends=4,
 	 Conflicts=5,Replaces=6,Obsoletes=7,DpkgBreaks=8,Enhances=9};
+      /** \brief available compare operators
+
+          The lower 4 bits are used to indicate what operator is being specified and
+          the upper 4 bits are flags. OR indicates that the next package is
+          or'd with the current package. */
       enum DepCompareOp {Or=0x10,NoOp=0,LessEq=0x1,GreaterEq=0x2,Less=0x3,
 	 Greater=0x4,Equals=0x5,NotEquals=0x6};
    };
    
    struct State
    {
+      /** \brief priority of a package version
+
+          Zero is used for unparsable or absent Priority fields. */
       enum VerPriority {Important=1,Required=2,Standard=3,Optional=4,Extra=5};
       enum PkgSelectedState {Unknown=0,Install=1,Hold=2,DeInstall=3,Purge=4};
       enum PkgInstState {Ok=0,ReInstReq=1,HoldInst=2,HoldReInstReq=3};
@@ -104,6 +162,7 @@ class pkgCache								/*{{{*/
    
    // Pointers to the arrays of items
    Header *HeaderP;
+   Group *GrpP;
    Package *PkgP;
    VerFile *VerFileP;
    DescFile *DescFileP;
@@ -115,7 +174,7 @@ class pkgCache								/*{{{*/
    StringItem *StringItemP;
    char *StrP;
 
-   virtual bool ReMap();
+   virtual bool ReMap(bool const &Errorchecks = true);
    inline bool Sync() {return Map.Sync();};
    inline MMap &GetMap() {return Map;};
    inline void *DataEnd() {return ((unsigned char *)Map.Data()) + Map.Size();};
@@ -124,17 +183,24 @@ class pkgCache								/*{{{*/
    inline unsigned long Hash(const string &S) const {return sHash(S);};
    inline unsigned long Hash(const char *S) const {return sHash(S);};
 
-   // Usefull transformation things
+   // Useful transformation things
    const char *Priority(unsigned char Priority);
    
    // Accessors
+   GrpIterator FindGrp(const string &Name);
    PkgIterator FindPkg(const string &Name);
+   PkgIterator FindPkg(const string &Name, const string &Arch);
+
    Header &Head() {return *HeaderP;};
+   inline GrpIterator GrpBegin();
+   inline GrpIterator GrpEnd();
    inline PkgIterator PkgBegin();
    inline PkgIterator PkgEnd();
    inline PkgFileIterator FileBegin();
    inline PkgFileIterator FileEnd();
 
+   inline bool MultiArchCache() const { return MultiArchEnabled; };
+
    // Make me a function
    pkgVersioningSystem *VS;
    
@@ -145,19 +211,40 @@ class pkgCache								/*{{{*/
    
    pkgCache(MMap *Map,bool DoMap = true);
    virtual ~pkgCache() {};
+
+private:
+   bool MultiArchEnabled;
+   PkgIterator SingleArchFindPkg(const string &Name);
 };
 									/*}}}*/
 // Header structure							/*{{{*/
 struct pkgCache::Header
 {
-   // Signature information
+   /** \brief Signature information
+
+       This must contain the hex value 0x98FE76DC which is designed to
+       verify that the system loading the image has the same byte order
+       and byte size as the system saving the image */
    unsigned long Signature;
+   /** These contain the version of the cache file */
    short MajorVersion;
    short MinorVersion;
+   /** \brief indicates if the cache should be erased
+
+       Dirty is true if the cache file was opened for reading, the client
+       expects to have written things to it and have not fully synced it.
+       The file should be erased and rebuilt if it is true. */
    bool Dirty;
-   
-   // Size of structure values
+
+   /** \brief Size of structure values
+
+       All *Sz variables contains the sizeof() that particular structure.
+       It is used as an extra consistency check on the structure of the file.
+
+       If any of the size values do not exactly match what the client expects
+       then the client should refuse the load the file. */
    unsigned short HeaderSz;
+   unsigned short GroupSz;
    unsigned short PackageSz;
    unsigned short PackageFileSz;
    unsigned short VersionSz;
@@ -166,8 +253,13 @@ struct pkgCache::Header
    unsigned short ProvidesSz;
    unsigned short VerFileSz;
    unsigned short DescFileSz;
-   
-   // Structure counts
+
+   /** \brief Structure counts
+
+       These indicate the number of each structure contained in the cache.
+       PackageCount is especially useful for generating user state structures.
+       See Package::Id for more info. */
+   unsigned long GroupCount;
    unsigned long PackageCount;
    unsigned long VersionCount;
    unsigned long DescriptionCount;
@@ -176,154 +268,393 @@ struct pkgCache::Header
    unsigned long VerFileCount;
    unsigned long DescFileCount;
    unsigned long ProvidesCount;
-   
-   // Offsets
-   map_ptrloc FileList;              // struct PackageFile
-   map_ptrloc StringList;            // struct StringItem
-   map_ptrloc VerSysName;            // StringTable
-   map_ptrloc Architecture;          // StringTable
+
+   /** \brief index of the first PackageFile structure
+
+       The PackageFile structures are singly linked lists that represent
+       all package files that have been merged into the cache. */
+   map_ptrloc FileList;
+   /** \brief index of the first StringItem structure
+
+       The cache contains a list of all the unique strings (StringItems).
+       The parser reads this list into memory so it can match strings
+       against it.*/
+   map_ptrloc StringList;
+   /** \brief String representing the version system used */
+   map_ptrloc VerSysName;
+   /** \brief Architecture(s) the cache was built against */
+   map_ptrloc Architecture;
+   /** \brief The maximum size of a raw entry from the original Package file */
    unsigned long MaxVerFileSize;
+   /** \brief The maximum size of a raw entry from the original Translation file */
    unsigned long MaxDescFileSize;
 
-   /* Allocation pools, there should be one of these for each structure
-      excluding the header */
-   DynamicMMap::Pool Pools[8];
+   /** \brief The Pool structures manage the allocation pools that the generator uses
+
+       Start indicates the first byte of the pool, Count is the number of objects
+       remaining in the pool and ItemSize is the structure size (alignment factor)
+       of the pool. An ItemSize of 0 indicates the pool is empty. There should be
+       the same number of pools as there are structure types. The generator
+       stores this information so future additions can make use of any unused pool
+       blocks. */
+   DynamicMMap::Pool Pools[9];
    
-   // Rapid package name lookup
-   map_ptrloc HashTable[2*1048];
+   /** \brief hash tables providing rapid group/package name lookup
+
+       Each group/package name is inserted into the hash table using pkgCache::Hash(const &string)
+       By iterating over each entry in the hash table it is possible to iterate over
+       the entire list of packages. Hash Collisions are handled with a singly linked
+       list of packages based at the hash item. The linked list contains only
+       packages that match the hashing function.
+       In the PkgHashTable is it possible that multiple packages have the same name -
+       these packages are stored as a sequence in the list.
+
+       Beware: The Hashmethod assumes that the hash table sizes are equal */
+   map_ptrloc PkgHashTable[2*1048];
+   map_ptrloc GrpHashTable[2*1048];
 
    bool CheckSizes(Header &Against) const;
    Header();
 };
 									/*}}}*/
-struct pkgCache::Package						/*{{{*/
+// Group structure							/*{{{*/
+/** \brief groups architecture depending packages together
+
+    On or more packages with the same name form a group, so we have
+    a simple way to access a package built for different architectures
+    Group exists in a singly linked list of group records starting at
+    the hash index of the name in the pkgCache::Header::GrpHashTable */
+struct pkgCache::Group
 {
-   // Pointers
-   map_ptrloc Name;              // Stringtable
+   /** \brief Name of the group */
+   map_ptrloc Name;		// StringItem
+
+   // Linked List
+   /** \brief Link to the first package which belongs to the group */
+   map_ptrloc FirstPackage;	// Package
+   /** \brief Link to the last package which belongs to the group */
+   map_ptrloc LastPackage;	// Package
+   /** \brief Link to the next Group */
+   map_ptrloc Next;		// Group
+   /** \brief unique sequel ID */
+   unsigned int ID;
+
+};
+									/*}}}*/
+// Package structure							/*{{{*/
+/** \brief contains information for a single unique package
+
+    There can be any number of versions of a given package.
+    Package exists in a singly linked list of package records starting at
+    the hash index of the name in the pkgCache::Header::PkgHashTable
+
+    A package can be created for every architecture so package names are
+    not unique, but it is garanteed that packages with the same name
+    are sequencel ordered in the list. Packages with the same name can be
+    accessed with the Group.
+*/
+struct pkgCache::Package
+{
+   /** \brief Name of the package */
+   map_ptrloc Name;              // StringItem
+   /** \brief Architecture of the package */
+   map_ptrloc Arch;              // StringItem
+   /** \brief Base of a singly linked list of versions
+
+       Each structure represents a unique version of the package.
+       The version structures contain links into PackageFile and the
+       original text file as well as detailed information about the size
+       and dependencies of the specific package. In this way multiple
+       versions of a package can be cleanly handled by the system.
+       Furthermore, this linked list is guaranteed to be sorted
+       from Highest version to lowest version with no duplicate entries. */
    map_ptrloc VersionList;       // Version
+   /** \brief index to the installed version */
    map_ptrloc CurrentVer;        // Version
-   map_ptrloc Section;           // StringTable (StringItem)
-      
-   // Linked list 
+   /** \brief indicates the deduced section
+
+       Should be the index to the string "Unknown" or to the section
+       of the last parsed item. */
+   map_ptrloc Section;           // StringItem
+   /** \brief index of the group this package belongs to */
+   map_ptrloc Group;             // Group the Package belongs to
+
+   // Linked list
+   /** \brief Link to the next package in the same bucket */
    map_ptrloc NextPackage;       // Package
+   /** \brief List of all dependencies on this package */
    map_ptrloc RevDepends;        // Dependency
+   /** \brief List of all "packages" this package provide */
    map_ptrloc ProvidesList;      // Provides
 
    // Install/Remove/Purge etc
+   /** \brief state that the user wishes the package to be in */
    unsigned char SelectedState;     // What
+   /** \brief installation state of the package
+
+       This should be "ok" but in case the installation failed
+       it will be different.
+   */
    unsigned char InstState;         // Flags
+   /** \brief indicates if the package is installed */
    unsigned char CurrentState;      // State
-   
+
+   /** \brief unique sequel ID
+
+       ID is a unique value from 0 to Header->PackageCount assigned by the generator.
+       This allows clients to create an array of size PackageCount and use it to store
+       state information for the package map. For instance the status file emitter uses
+       this to track which packages have been emitted already. */
    unsigned int ID;
+   /** \brief some useful indicators of the package's state */
    unsigned long Flags;
 };
 									/*}}}*/
-struct pkgCache::PackageFile						/*{{{*/
+// Package File structure						/*{{{*/
+/** \brief stores information about the files used to generate the cache
+
+    Package files are referenced by Version structures to be able to know
+    after the generation still from which Packages file includes this Version
+    as we need this information later on e.g. for pinning. */
+struct pkgCache::PackageFile
 {
-   // Names
-   map_ptrloc FileName;        // Stringtable
-   map_ptrloc Archive;         // Stringtable
-   map_ptrloc Codename;        // Stringtable
-   map_ptrloc Component;       // Stringtable
-   map_ptrloc Version;         // Stringtable
-   map_ptrloc Origin;          // Stringtable
-   map_ptrloc Label;           // Stringtable
-   map_ptrloc Architecture;    // Stringtable
-   map_ptrloc Site;            // Stringtable
-   map_ptrloc IndexType;       // Stringtable
-   unsigned long Size;            
+   /** \brief physical disk file that this PackageFile represents */
+   map_ptrloc FileName;        // StringItem
+   /** \brief the release information
+
+       Please see the files document for a description of what the
+       release information means. */
+   map_ptrloc Archive;         // StringItem
+   map_ptrloc Codename;        // StringItem
+   map_ptrloc Component;       // StringItem
+   map_ptrloc Version;         // StringItem
+   map_ptrloc Origin;          // StringItem
+   map_ptrloc Label;           // StringItem
+   map_ptrloc Architecture;    // StringItem
+   /** \brief The site the index file was fetched from */
+   map_ptrloc Site;            // StringItem
+   /** \brief indicates what sort of index file this is
+
+       @TODO enumerate at least the possible indexes */
+   map_ptrloc IndexType;       // StringItem
+   /** \brief Size of the file
+
+       Used together with the modification time as a
+       simple check to ensure that the Packages
+       file has not been altered since Cache generation. */
+   unsigned long Size;
+   /** \brief Modification time for the file */
+   time_t mtime;
+
+   /* @TODO document PackageFile::Flags */
    unsigned long Flags;
-   
+
    // Linked list
+   /** \brief Link to the next PackageFile in the Cache */
    map_ptrloc NextFile;        // PackageFile
+   /** \brief unique sequel ID */
    unsigned int ID;
-   time_t mtime;                  // Modification time for the file
 };
 									/*}}}*/
-struct pkgCache::VerFile						/*{{{*/
+// VerFile structure							/*{{{*/
+/** \brief associates a version with a PackageFile
+
+    This allows a full description of all Versions in all files
+    (and hence all sources) under consideration. */
+struct pkgCache::VerFile
 {
+   /** \brief index of the package file that this version was found in */
    map_ptrloc File;           // PackageFile
+   /** \brief next step in the linked list */
    map_ptrloc NextFile;       // PkgVerFile
+   /** \brief position in the package file */
    map_ptrloc Offset;         // File offset
+   /* @TODO document pkgCache::VerFile::Size */
    unsigned long Size;
 };
 									/*}}}*/
-struct pkgCache::DescFile						/*{{{*/
+// DescFile structure							/*{{{*/
+/** \brief associates a description with a Translation file */
+struct pkgCache::DescFile
 {
+   /** \brief index of the file that this description was found in */
    map_ptrloc File;           // PackageFile
+   /** \brief next step in the linked list */
    map_ptrloc NextFile;       // PkgVerFile
+   /** \brief position in the file */
    map_ptrloc Offset;         // File offset
+   /* @TODO document pkgCache::DescFile::Size */
    unsigned long Size;
 };
 									/*}}}*/
-struct pkgCache::Version						/*{{{*/
+// Version structure							/*{{{*/
+/** \brief information for a single version of a package
+
+    The version list is always sorted from highest version to lowest
+    version by the generator. Equal version numbers are either merged
+    or handled as separate versions based on the Hash value. */
+struct pkgCache::Version
 {
-   map_ptrloc VerStr;            // Stringtable
-   map_ptrloc Section;           // StringTable (StringItem)
-   map_ptrloc Arch;              // StringTable
-      
-   // Lists
+   /** \brief complete version string */
+   map_ptrloc VerStr;            // StringItem
+   /** \brief section this version is filled in */
+   map_ptrloc Section;           // StringItem
+   /** \brief stores the MultiArch capabilities of this version
+
+       None is the default and doesn't trigger special behaviour,
+       Foreign means that this version can fulfill dependencies even
+       if it is built for another architecture as the requester.
+       Same indicates that builds for different architectures can
+       be co-installed on the system and All is the marker for a
+       version with the Architecture: all. */
+   enum {None, All, Foreign, Same, Allowed} MultiArch;
+
+   /** \brief references all the PackageFile's that this version came from
+
+       FileList can be used to determine what distribution(s) the Version
+       applies to. If FileList is 0 then this is a blank version.
+       The structure should also have a 0 in all other fields excluding
+       pkgCache::Version::VerStr and Possibly pkgCache::Version::NextVer. */
    map_ptrloc FileList;          // VerFile
+   /** \brief next (lower or equal) version in the linked list */
    map_ptrloc NextVer;           // Version
+   /** \brief next description in the linked list */
    map_ptrloc DescriptionList;   // Description
+   /** \brief base of the dependency list */
    map_ptrloc DependsList;       // Dependency
+   /** \brief links to the owning package
+
+       This allows reverse dependencies to determine the package */
    map_ptrloc ParentPkg;         // Package
+   /** \brief list of pkgCache::Provides */
    map_ptrloc ProvidesList;      // Provides
-   
-   map_ptrloc Size;              // These are the .deb size
-   map_ptrloc InstalledSize;
+
+   /** \brief archive size for this version
+
+       For Debian this is the size of the .deb file. */
+   unsigned long long Size;      // These are the .deb size
+   /** \brief uncompressed size for this version */
+   unsigned long long InstalledSize;
+   /** \brief characteristic value representing this version
+
+       No two packages in existence should have the same VerStr
+       and Hash with different contents. */
    unsigned short Hash;
+   /** \brief unique sequel ID */
    unsigned int ID;
+   /** \brief parsed priority value */
    unsigned char Priority;
 };
 									/*}}}*/
-struct pkgCache::Description						/*{{{*/
+// Description structure						/*{{{*/
+/** \brief datamember of a linked list of available description for a version */
+struct pkgCache::Description
 {
-   // Language Code store the description translation language code. If
-   // the value has a 0 lenght then this is readed using the Package
-   // file else the Translation-CODE are used.
-   map_ptrloc language_code;     // StringTable
-   map_ptrloc md5sum;            // StringTable
+   /** \brief Language code of this description (translation)
+
+       If the value has a 0 length then this is read using the Package
+       file else the Translation-CODE file is used. */
+   map_ptrloc language_code;     // StringItem
+   /** \brief MD5sum of the original description
+
+       Used to map Translations of a description to a version
+       and to check that the Translation is up-to-date. */
+   map_ptrloc md5sum;            // StringItem
 
-   // Linked list 
+   /* @TODO document pkgCache::Description::FileList */
    map_ptrloc FileList;          // DescFile
+   /** \brief next translation for this description */
    map_ptrloc NextDesc;          // Description
+   /** \brief the text is a description of this package */
    map_ptrloc ParentPkg;         // Package
 
+   /** \brief unique sequel ID */
    unsigned int ID;
 };
 									/*}}}*/
-struct pkgCache::Dependency						/*{{{*/
+// Dependency structure							/*{{{*/
+/** \brief information for a single dependency record
+
+    The records are split up like this to ease processing by the client.
+    The base of the linked list is pkgCache::Version::DependsList.
+    All forms of dependencies are recorded here including Depends,
+    Recommends, Suggests, Enhances, Conflicts, Replaces and Breaks. */
+struct pkgCache::Dependency
 {
-   map_ptrloc Version;         // Stringtable
+   /** \brief string of the version the dependency is applied against */
+   map_ptrloc Version;         // StringItem
+   /** \brief index of the package this depends applies to
+
+       The generator will - if the package does not already exist -
+       create a blank (no version records) package. */
    map_ptrloc Package;         // Package
+   /** \brief next dependency of this version */
    map_ptrloc NextDepends;     // Dependency
+   /** \brief next reverse dependency of this package */
    map_ptrloc NextRevDepends;  // Dependency
+   /** \brief version of the package which has the reverse depends */
    map_ptrloc ParentVer;       // Version
-   
-   // Specific types of depends
-   map_ptrloc ID;   
+
+   /** \brief unique sequel ID */
+   map_ptrloc ID;
+   /** \brief Dependency type - Depends, Recommends, Conflicts, etc */
    unsigned char Type;
+   /** \brief comparison operator specified on the depends line
+
+       If the high bit is set then it is a logical OR with the previous record. */
    unsigned char CompareOp;
 };
 									/*}}}*/
-struct pkgCache::Provides						/*{{{*/
+// Provides structure							/*{{{*/
+/** \brief handles virtual packages
+
+    When a Provides: line is encountered a new provides record is added
+    associating the package with a virtual package name.
+    The provides structures are linked off the package structures.
+    This simplifies the analysis of dependencies and other aspects A provides
+    refers to a specific version of a specific package, not all versions need to
+    provide that provides.*/
+struct pkgCache::Provides
 {
-   map_ptrloc ParentPkg;        // Pacakge
+   /** \brief index of the package providing this */
+   map_ptrloc ParentPkg;        // Package
+   /** \brief index of the version this provide line applies to */
    map_ptrloc Version;          // Version
-   map_ptrloc ProvideVersion;   // Stringtable
+   /** \brief version in the provides line (if any)
+
+       This version allows dependencies to depend on specific versions of a
+       Provides, as well as allowing Provides to override existing packages.
+       This is experimental. Note that Debian doesn't allow versioned provides */
+   map_ptrloc ProvideVersion;   // StringItem
+   /** \brief next provides (based of package) */
    map_ptrloc NextProvides;     // Provides
+   /** \brief next provides (based of version) */
    map_ptrloc NextPkgProv;      // Provides
 };
 									/*}}}*/
-struct pkgCache::StringItem						/*{{{*/
+// StringItem structure							/*{{{*/
+/** \brief used for generating single instances of strings
+
+    Some things like Section Name are are useful to have as unique tags.
+    It is part of a linked list based at pkgCache::Header::StringList
+
+    All strings are simply inlined any place in the file that is natural
+    for the writer. The client should make no assumptions about the positioning
+    of strings. All StringItems should be null-terminated. */
+struct pkgCache::StringItem
 {
-   map_ptrloc String;        // Stringtable
+   /** \brief string this refers to */
+   map_ptrloc String;        // StringItem
+   /** \brief Next link in the chain */
    map_ptrloc NextItem;      // StringItem
 };
 									/*}}}*/
 #include <apt-pkg/cacheiterators.h>
 
+inline pkgCache::GrpIterator pkgCache::GrpBegin() 
+       {return GrpIterator(*this);};
+inline pkgCache::GrpIterator pkgCache::GrpEnd() 
+       {return GrpIterator(*this,GrpP);};
 inline pkgCache::PkgIterator pkgCache::PkgBegin() 
        {return PkgIterator(*this);};
 inline pkgCache::PkgIterator pkgCache::PkgEnd() 
@@ -337,7 +668,7 @@ inline pkgCache::PkgFileIterator pkgCache::FileEnd()
 class pkgCache::Namespace						/*{{{*/
 {   
    public:
-
+   typedef pkgCache::GrpIterator GrpIterator;
    typedef pkgCache::PkgIterator PkgIterator;
    typedef pkgCache::VerIterator VerIterator;
    typedef pkgCache::DescIterator DescIterator;