README.md

   1 APT
   2 ===
   3
   4 apt is the main commandline package manager for Debian and its derivatives.
   5 It provides commandline tools for searching and managing as well as querying
   6 information about packages as well as low-level access to all features
   7 provided by the libapt-pkg and libapt-inst libraries which higher-level
   8 package managers can depend upon.
   9
  10 Included tools are:
  11
  12 * apt-get for retrieval of packages and information about them
  13   from authenticated sources and for installation, upgrade and
  14   removal of packages together with their dependencies
  15 * apt-cache for querying available information about installed
  16   as well as installable packages
  17 * apt-cdrom to use removable media as a source for packages
  18 * apt-config as an interface to the configuration settings
  19 * apt-key as an interface to manage authentication keys
  20 * apt-extracttemplates to be used by debconf to prompt for configuration
  21   questions before installation.
  22 * apt-ftparchive creates Packages and other index files
  23   needed to publish an archive of debian packages
  24 * apt-sortpkgs is a Packages/Sources file normalizer.
  25
  26 The libraries libapt-pkg and libapt-inst are also maintained as part of this project,
  27 alongside various additional binaries like the acquire-methods used by them.
  28 Bindings for Python ([python-apt](https://tracker.debian.org/pkg/python-apt)) and
  29 Perl ([libapt-pkg-perl](https://tracker.debian.org/pkg/libapt-pkg-perl)) are available as separated projects.
  30
  31 Discussion happens mostly on [the mailinglist](mailto:deity@lists.debian.org) ([archive](https://lists.debian.org/deity/)) and on [IRC](irc://irc.oftc.net/debian-apt).
  32 Our bugtracker as well as a general overview can be found at the [Debian Tracker page](https://tracker.debian.org/pkg/apt).
  33
  34
  35 Contributing
  36 ------------
  37 APT is maintained in git, the official repository being located at
  38 `git://anonscm.debian.org/apt/apt.git` ([webgit](http://anonscm.debian.org/gitweb/?p=apt/apt.git)),
  39 but also available at other locations like [GitHub](https://github.com/Debian/apt).
  40
  41 The default branch is `master`, other branches targeted at different
  42 derivatives and releases being used as needed. Various topic branches in
  43 different stages of completion might be branched of from those, which you
  44 are encouraged to do as well.
  45
  46 ### Coding
  47
  48 APT uses cmake. To start building, you need to run
  49
  50   cmake <path to source directory>
  51
  52 from a build directory. For example, if you want to build in the source tree,
  53 run:
  54
  55   cmake .
  56
  57 Then you can use make as you normally would (pass -j <count> to perform <count>
  58 jobs in parallel).
  59
  60 You can also use the Ninja generator of cmake, to do that pass
  61   -G Ninja
  62 to the cmake invocation, and then use ninja instead of make.
  63
  64 The source code uses in most parts a relatively uncommon indent convention,
  65 namely 3 spaces with 8 space tab (see [doc/style.txt](http://anonscm.debian.org/gitweb/?p=apt/apt.git;a=blob;f=doc/style.txt) for more on this).
  66 Adhering to it avoids unnecessary code-churn destroying history (aka: `git blame`)
  67 and you are therefore encouraged to write patches in this style.
  68 Your editor can surely help you with this, for vim the settings would be
  69 `setlocal shiftwidth=3 noexpandtab tabstop=8`
  70 (the later two are the default configuration and could therefore be omitted).
  71
  72 ### Translations
  73
  74 While we welcome contributions here, we highly encourage you to contact the [Debian Internationalization (i18n) team](https://wiki.debian.org/Teams/I18n).
  75 Various language teams have formed which can help you creating, maintaining
  76 and improving a translation, while we could only do a basic syntax check of the
  77 file format…
  78
  79 Further more, Translating APT is split into two independent parts:
  80 The program translation, meaning the messages printed by the tools,
  81 as well as the manpages and other documentation shipped with APT.
  82
  83 ### Bug triage
  84
  85 Software tools like APT which are used by thousands of users every
  86 day have a steady flow of incoming bugreports. Not all of them are really
  87 bugs in APT: It can be packaging bugs like failing maintainer scripts a
  88 user reports against apt, because apt was the command he executed leading
  89 to this failure or various wishlist items for new features. Given enough time
  90 also the occasional duplicate enters the system.
  91 Our bugtracker is therefore full with open bugreports which are waiting for you! ;)
  92
  93 Testing
  94 -------
  95
  96 ### Manual execution
  97
  98 When you make changes and want to run them manually, you can just do so. CMake
  99 automatically inserts an rpath so the binaries find the correct libraries.
 100
 101 ### Integration tests
 102
 103 There is a extensive integration testsuite available which can be run via:
 104
 105         $ ./test/integration/run-tests
 106
 107 While these tests are not executed at package build-time as they require additional
 108 dependencies, the repository contains the configuration needed to run them on [Travis CI](https://travis-ci.org/)
 109 as well as via autopkgtests e.g. on [Debian Continuous Integration](http://ci.debian.net/?q=apt#package/apt).
 110
 111 A testcase here is a shellscript embedded in a framework creating an environment in which
 112 apt tools can be used naturally without root-rights to test every aspect of its behavior
 113 itself as well as in conjunction with dpkg and other tools while working with packages.
 114
 115
 116 ### Unit tests
 117
 118 These tests are gtest-dev based, reside in `./test/libapt` and can be run with `make test`.
 119 They are executed at package build-time, but not by `make`.
 120
 121 Debugging
 122 ---------
 123
 124 APT does many things, so there is no central debug mode which could be
 125 activated. It uses instead various config-options to activate debug output
 126 in certain areas. The following describes some common scenarios and generally
 127 useful options, but is in no way exhaustive.
 128
 129 Note that you should *NEVER* use these settings as root to avoid accidents.
 130 Similation mode (`-s`) is usually sufficient to help you run apt as a non-root user.
 131
 132 ### Using different state files
 133
 134 If a dependency solver bug is reported, but can't be reproduced by the
 135 triager easily, it is beneficial to ask the reporter for the
 136 `/var/lib/dpkg/status` file, which includes the packages installed on the
 137 system and in which version. Such a file can then be used via the option
 138 `dir::state::status`. Beware of different architecture settings!
 139 Bugreports usually include this information in the template. Assuming you
 140 already have the `Packages` files for the architecture (see `sources.list`
 141 manpage for the `arch=` option) you can change to a different architecture
 142 with a config file like:
 143
 144         APT::Architecture "arch1";
 145         #clear APT::Architectures;
 146         APT:: Architectures { "arch1"; "arch2"; }
 147
 148 If a certain mirror state is needed, see if you can reproduce it with [snapshot.debian.org](http://snapshot.debian.org/).
 149 Your sources.list file (`dir::etc::sourcelist`) has to be correctly mention the repository,
 150 but if it does, you can use different downloaded archive state files via `dir::state::lists`.
 151
 152 In case manually vs. automatically installed matters, you can ask the reporter for
 153 the `/var/lib/apt/extended_states` file and use it with `dir::state::extended_states`.
 154
 155 ### Dependency resolution
 156
 157 APT works in its internal resolver in two stages: First all packages are visited
 158 and marked for installation, keep back or removal. Option `Debug::pkgDepCache::Marker`
 159 shows this. This also decides which packages are to be installed to satisfy dependencies,
 160 which can be seen by `Debug::pkgDepCache::AutoInstall`. After this is done, we might
 161 be in a situation in which two packages want to be installed, but only on of them can be.
 162 It is the job of the pkgProblemResolver to decide which of two packages 'wins' and can
 163 therefore decide what has to happen. You can see the contenders as well as their fight and
 164 the resulting resolution with `Debug::pkgProblemResolver`.
 165
 166 ### Downloading files
 167
 168 Various binaries (called 'methods') are tasked with downloading files. The Acquire system
 169 talks to them via simple text protocol. Depending on which side you want to see, either
 170 `Debug::pkgAcquire::Worker` or `Debug::Acquire::http` (or similar) will show the messages.
 171
 172 The integration tests use a simple self-built webserver which also logs. If you find that
 173 the http(s) methods do not behave like they should be try to implement this behavior in the
 174 webserver for simpler and more controlled testing.
 175
 176 ### Installation order
 177
 178 Dependencies are solved, packages downloaded: Everything read for the installation!
 179 The last step in the chain is often forgotten, but still very important:
 180 Packages have to be installed in a particular order so that their dependencies are
 181 satisfied, but at the same time you don't want to install very important and optional
 182 packages at the same time if possible, so that a broken optional package does not
 183 block the correct installation of very important packages. Which option to use depends on
 184 if you are interested in the topology sorting (`Debug::pkgOrderList`), the dependency-aware
 185 cycle and unconfigured prevention (`Debug::pkgPackageManager`) or the actual calls
 186 to dpkg (`Debug::pkgDpkgPm`).