README.md 10.5 KB
Newer Older
1 2 3
APT
===

4 5
apt is the main command-line package manager for Debian and its derivatives.
It provides command-line tools for searching and managing as well as querying
6 7 8 9 10 11 12 13 14 15
information about packages as well as low-level access to all features
provided by the libapt-pkg and libapt-inst libraries which higher-level
package managers can depend upon.

Included tools are:

* **apt-get** for retrieval of packages and information about them
  from authenticated sources and for installation, upgrade and
  removal of packages together with their dependencies
* **apt-cache** for querying available information about installed
16
  as well as available packages
17 18 19 20 21 22
* **apt-cdrom** to use removable media as a source for packages
* **apt-config** as an interface to the configuration settings
* **apt-key** as an interface to manage authentication keys
* **apt-extracttemplates** to be used by debconf to prompt for configuration
  questions before installation
* **apt-ftparchive** creates Packages and other index files
23
  needed to publish an archive of deb packages
24
* **apt-sortpkgs** is a Packages/Sources file normalizer
25
* **apt** is a high-level command-line interface for better interactive usage
26 27

The libraries libapt-pkg and libapt-inst are also maintained as part of this project,
28
alongside various additional binaries like the acquire methods used by them.
29 30 31
Bindings for Python ([python-apt](https://tracker.debian.org/pkg/python-apt)) and
Perl ([libapt-pkg-perl](https://tracker.debian.org/pkg/libapt-pkg-perl)) are available as separated projects.

32 33
Discussion happens mostly on [the mailing list](mailto:deity@lists.debian.org) ([archive](https://lists.debian.org/deity/)) and on [IRC](irc://irc.oftc.net/debian-apt).
Our bug tracker as well as a general overview can be found at the [Debian Tracker page](https://tracker.debian.org/pkg/apt).
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48


Contributing
------------
APT is maintained in git, the official repository being located at
[https://salsa.debian.org/apt-team/apt](https://salsa.debian.org/apt-team/apt),
but also available at other locations like [GitHub](https://github.com/Debian/apt).

The default branch is `master`, other branches targeted at different
derivatives and releases being used as needed. Various topic branches in
different stages of completion might be branched of from those, which you
are encouraged to do as well.

### Coding

49
APT uses CMake. To start building, you need to run
50 51 52 53 54 55 56 57

	cmake <path to source directory>

from a build directory. For example, if you want to build in the source tree,
run:

	cmake .

58
Then you can use make as you normally would (pass `-j <count>` to perform `<count>`
59 60
jobs in parallel).

61
You can also use the Ninja generator of CMake, to do that pass
62 63 64 65
	-G Ninja
to the cmake invocation, and then use ninja instead of make.

The source code uses in most parts a relatively uncommon indent convention,
66
namely 3 spaces with 8 space tab (see [doc/style.txt](./doc/style.txt) for more on this).
67 68 69 70 71 72 73 74 75
Adhering to it avoids unnecessary code-churn destroying history (aka: `git blame`)
and you are therefore encouraged to write patches in this style.
Your editor can surely help you with this, for vim the settings would be
`setlocal shiftwidth=3 noexpandtab tabstop=8`
(the later two are the default configuration and could therefore be omitted).

### Translations

While we welcome contributions here, we highly encourage you to contact the [Debian Internationalization (i18n) team](https://wiki.debian.org/Teams/I18n).
76 77
Various language teams have formed which can help you create, maintain
and improve a translation, while we could only do a basic syntax check of the
78 79
file format…

80
Further more, translating APT is split into two independent parts:
81
The program translation, meaning the messages printed by the tools,
82
as well as the manual pages and other documentation shipped with APT.
83 84 85

### Bug triage

86 87 88 89 90 91 92
Software tools like APT, which are used by thousands of users every
day, have a steady flow of incoming bug reports. Not all of them are really
bugs in APT: It can be packaging bugs, like failing maintainer scripts, that a
user reports against apt, because apt was the command they executed that lead
to this failure; or various wishlist items for new features. Given enough time
the occasional duplicate enters the system as well.
Our bug tracker is therefore full with open bug reports which are waiting for you! ;)
93 94 95 96 97 98 99 100 101 102 103

Testing
-------

### Manual execution

When you make changes and want to run them manually, you can just do so. CMake
automatically inserts an rpath so the binaries find the correct libraries.

Note that you have to invoke CMake with the right install prefix set (e.g.
`-DCMAKE_INSTALL_PREFIX=/usr`) to have your build find and use the right files
104
by default or alternatively set the locations at run-time via an `APT_CONFIG`
105 106 107 108
configuration file.

### Integration tests

109
There is an extensive integration test suite available which can be run via:
110 111 112 113

	$ ./test/integration/run-tests

Each test can also be run individually as well. The tests are very noisy by
114
default, especially so while running all of them; it might be beneficial to
115 116 117 118 119 120 121 122 123
enabling quiet (`-q`) or very quiet (`-qq`) mode. The tests can also be run in
parallel via `-j X` where `X` is the number of jobs to run.

While these tests are not executed at package build-time as they require
additional dependencies, the repository contains the configuration needed to
run them on [Travis CI](https://travis-ci.org/) and
[Shippable](https://shippable.com/) as well as via autopkgtests e.g. on
[Debian Continuous Integration](https://ci.debian.net/packages/a/apt/).

124
A test case here is a shell script embedded in a framework creating an environment in which
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
apt tools can be used naturally without root-rights to test every aspect of its behavior
itself as well as in conjunction with dpkg and other tools while working with packages.


### Unit tests

These tests are gtest-dev based, executed by ctest, reside in `./test/libapt`
and can be run with `make test`. They are executed at package build-time, but
not by `make`. CTest by default does not show the output of tests, even if they
failed, so to see more details you can also run them with `ctest --verbose`.

Debugging
---------

APT does many things, so there is no central debug mode which could be
140
activated. Instead, it uses various configuration options to activate debug output
141 142 143
in certain areas. The following describes some common scenarios and generally
useful options, but is in no way exhaustive.

144
Note that, to avoid accidents, you should *NEVER* use these settings as root.
145 146 147 148
Simulation mode (`-s`) is usually sufficient to help you run apt as a non-root user.

### Using different state files

149 150 151
If a dependency solver bug is reported, but can't easily be reproduced by the
triager, it is beneficial to ask the reporter for the
`/var/lib/dpkg/status` file which includes the packages installed on the
152 153
system and in which version. Such a file can then be used via the option
`dir::state::status`. Beware of different architecture settings!
154
Bug reports usually include this information in the template. Assuming you
155 156
already have the `Packages` files for the architecture (see `sources.list`
manpage for the `arch=` option) you can change to a different architecture
157
with a configuration file like:
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175

	APT::Architecture "arch1";
	#clear APT::Architectures;
	APT:: Architectures { "arch1"; "arch2"; }

If a certain mirror state is needed, see if you can reproduce it with [snapshot.debian.org](http://snapshot.debian.org/).
Your sources.list file (`dir::etc::sourcelist`) has to be correctly mention the repository,
but if it does, you can use different downloaded archive state files via `dir::state::lists`.

In case manually vs. automatically installed matters, you can ask the reporter for
the `/var/lib/apt/extended_states` file and use it with `dir::state::extended_states`.

### Dependency resolution

APT works in its internal resolver in two stages: First all packages are visited
and marked for installation, keep back or removal. Option `Debug::pkgDepCache::Marker`
shows this. This also decides which packages are to be installed to satisfy dependencies,
which can be seen by `Debug::pkgDepCache::AutoInstall`. After this is done, we might
176 177
be in a situation in which two packages want to be installed, but only one of them can be.
It is the job of the `pkgProblemResolver` to decide which of two packages 'wins' and can
178 179 180 181 182 183 184 185 186
therefore decide what has to happen. You can see the contenders as well as their fight and
the resulting resolution with `Debug::pkgProblemResolver`.

### Downloading files

Various binaries (called 'methods') are tasked with downloading files. The Acquire system
talks to them via simple text protocol. Depending on which side you want to see, either
`Debug::pkgAcquire::Worker` or `Debug::Acquire::http` (or similar) will show the messages.

187 188
The integration tests use a simple self-built web server (`webserver`) which also logs. If you find that
the http(s) methods do not behave like they should be try to implement this behavior in
189 190 191 192
webserver for simpler and more controlled testing.

### Installation order

193
Dependencies are solved, packages downloaded: Everything is ready for the installation!
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
The last step in the chain is often forgotten, but still very important:
Packages have to be installed in a particular order so that their dependencies are
satisfied, but at the same time you don't want to install very important and optional
packages at the same time if possible, so that a broken optional package does not
block the correct installation of very important packages. Which option to use depends on
if you are interested in the topology sorting (`Debug::pkgOrderList`), the dependency-aware
cycle and unconfigured prevention (`Debug::pkgPackageManager`) or the actual calls
to dpkg (`Debug::pkgDpkgPm`).


Additional documentation
------------------------

Many more things could and should be said about APT and its usage but are more
targeted at developers of related programs or only of special interest.

210 211 212
* [Protocol specification of APT's communication with external dependency solvers (EDSP)](./doc/external-dependency-solver-protocol.md)
* [Protocol specification of APT's communication with external installation planners (EIPP)](./doc/external-installation-planner-protocol.md)
* [How to use and configure APT to acquire additional files in 'update' operations](./doc/acquire-additional-files.md)
213 214 215
* [Download and package installation progress reporting details](./doc/progress-reporting.md)
* [Remarks on DNS SRV record support in APT](./doc/srv-records-support.md)
* [Protocol specification of APT interfacing with external hooks via JSON](./doc/json-hooks-protocol.md)