Commit | Line | Data |
---|---|---|
2457d184 DK |
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 | ||
2ee1a6f0 | 41 | The default branch is `master`, other branches targeted at different |
2457d184 DK |
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 its own autoconf based build system, see [README.make](http://anonscm.debian.org/gitweb/?p=apt/apt.git;a=blob;f=README.make) | |
49 | for the glory details, but to get started, just run: | |
50 | ||
51 | $ make | |
52 | ||
53 | from a fresh git checkout. | |
54 | ||
55 | The source code uses in most parts a relatively uncommon indent convention, | |
56 | 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). | |
57 | Adhering to it avoids unnecessary code-churn destroying history (aka: `git blame`) | |
58 | and you are therefore encouraged to write patches in this style. | |
59 | Your editor can surely help you with this, for vim the settings would be | |
60 | `setlocal shiftwidth=3 noexpandtab tabstop=8` | |
61 | (the later two are the default configuration and could therefore be omitted). | |
62 | ||
63 | ### Translations | |
64 | ||
65 | While we welcome contributions here, we highly encourage you to contact the [Debian Internationalization (i18n) team](https://wiki.debian.org/Teams/I18n). | |
66 | Various language teams have formed which can help you creating, maintaining | |
67 | and improving a translation, while we could only do a basic syntax check of the | |
68 | file format… | |
69 | ||
70 | Further more, Translating APT is split into two independent parts: | |
71 | The program translation, meaning the messages printed by the tools, | |
72 | as well as the manpages and other documentation shipped with APT. | |
73 | ||
74 | ### Bug triage | |
75 | ||
76 | Software tools like APT which are used by thousands of users every | |
77 | day have a steady flow of incoming bugreports. Not all of them are really | |
78 | bugs in APT: It can be packaging bugs like failing maintainer scripts a | |
79 | user reports against apt, because apt was the command he executed leading | |
80 | to this failure or various wishlist items for new features. Given enough time | |
81 | also the occasional duplicate enters the system. | |
82 | Our bugtracker is therefore full with open bugreports which are waiting for you! ;) | |
c4d749b7 MV |
83 | |
84 | Testing | |
85 | ------- | |
86 | ||
2457d184 DK |
87 | ### Manual execution |
88 | ||
89 | When you make changes and want to run them manually, make sure your | |
90 | `$LD_LIBRARY_PATH` points to the libraries you have built, e.g. via: | |
91 | ||
92 | $ export LD_LIBRARY_PATH=$(pwd)/build/bin | |
93 | $ ./build/bin/apt-get moo | |
94 | ||
95 | ||
96 | ### Integration tests | |
97 | ||
98 | There is a extensive integration testsuite available which can be run via: | |
99 | ||
100 | $ ./test/integration/run-tests | |
101 | ||
102 | While these tests are not executed at package build-time as they require additional | |
103 | dependencies, the repository contains the configuration needed to run them on [Travis CI](https://travis-ci.org/) | |
104 | as well as via autopkgtests e.g. on [Debian Continuous Integration](http://ci.debian.net/?q=apt#package/apt). | |
105 | ||
106 | A testcase here is a shellscript embedded in a framework creating an environment in which | |
107 | apt tools can be used naturally without root-rights to test every aspect of its behavior | |
108 | itself as well as in conjunction with dpkg and other tools while working with packages. | |
109 | ||
110 | ||
111 | ### Unit tests | |
112 | ||
113 | These tests are gtest-dev based, reside in `./test/libapt` and can be run with `make test`. | |
114 | They are executed at package build-time, but not by `make`. | |
115 | ||
116 | Debugging | |
117 | --------- | |
118 | ||
119 | APT does many things, so there is no central debug mode which could be | |
120 | activated. It uses instead various config-options to activate debug output | |
121 | in certain areas. The following describes some common scenarios and generally | |
122 | useful options, but is in no way exhaustive. | |
123 | ||
124 | Note that you should *NEVER* use these settings as root to avoid accidents. | |
125 | Similation mode (`-s`) is usually sufficient to help you run apt as a non-root user. | |
126 | ||
127 | ### Using different state files | |
128 | ||
129 | If a dependency solver bug is reported, but can't be reproduced by the | |
130 | triager easily, it is beneficial to ask the reporter for the | |
131 | `/var/lib/dpkg/status` file, which includes the packages installed on the | |
132 | system and in which version. Such a file can then be used via the option | |
133 | `dir::state::status`. Beware of different architecture settings! | |
134 | Bugreports usually include this information in the template. Assuming you | |
135 | already have the `Packages` files for the architecture (see `sources.list` | |
136 | manpage for the `arch=` option) you can change to a different architecture | |
137 | with a config file like: | |
138 | ||
139 | APT::Architecture "arch1"; | |
140 | #clear APT::Architectures; | |
141 | APT:: Architectures { "arch1"; "arch2"; } | |
142 | ||
143 | If a certain mirror state is needed, see if you can reproduce it with [snapshot.debian.org](http://snapshot.debian.org/). | |
144 | Your sources.list file (`dir::etc::sourcelist`) has to be correctly mention the repository, | |
145 | but if it does, you can use different downloaded archive state files via `dir::state::lists`. | |
146 | ||
147 | In case manually vs. automatically installed matters, you can ask the reporter for | |
148 | the `/var/lib/apt/extended_states` file and use it with `dir::state::extended_states`. | |
149 | ||
150 | ### Dependency resolution | |
151 | ||
152 | APT works in its internal resolver in two stages: First all packages are visited | |
153 | and marked for installation, keep back or removal. Option `Debug::pkgDepCache::Marker` | |
154 | shows this. This also decides which packages are to be installed to satisfy dependencies, | |
155 | which can be seen by `Debug::pkgDepCache::AutoInstall`. After this is done, we might | |
156 | be in a situation in which two packages want to be installed, but only on of them can be. | |
157 | It is the job of the pkgProblemResolver to decide which of two packages 'wins' and can | |
158 | therefore decide what has to happen. You can see the contenders as well as their fight and | |
159 | the resulting resolution with `Debug::pkgProblemResolver`. | |
160 | ||
161 | ### Downloading files | |
162 | ||
163 | Various binaries (called 'methods') are tasked with downloading files. The Acquire system | |
164 | talks to them via simple text protocol. Depending on which side you want to see, either | |
165 | `Debug::pkgAcquire::Worker` or `Debug::Acquire::http` (or similar) will show the messages. | |
166 | ||
167 | The integration tests use a simple self-built webserver which also logs. If you find that | |
168 | the http(s) methods do not behave like they should be try to implement this behavior in the | |
169 | webserver for simpler and more controlled testing. | |
c4d749b7 | 170 | |
2457d184 | 171 | ### Installation order |
c4d749b7 | 172 | |
2457d184 DK |
173 | Dependencies are solved, packages downloaded: Everything read for the installation! |
174 | The last step in the chain is often forgotten, but still very important: | |
175 | Packages have to be installed in a particular order so that their dependencies are | |
176 | satisfied, but at the same time you don't want to install very important and optional | |
177 | packages at the same time if possible, so that a broken optional package does not | |
178 | block the correct installation of very important packages. Which option to use depends on | |
179 | if you are interested in the topology sorting (`Debug::pkgOrderList`), the dependency-aware | |
180 | cycle and unconfigured prevention (`Debug::pkgPackageManager`) or the actual calls | |
181 | to dpkg (`Debug::pkgDpkgPm`). |