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.

README.md 8.7 KiB

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