1 ALPM library overview & internals
2 =================================
4 Here is a list of the main objects and files from the ALPM (i.e. Arch Linux
5 Package Management) library. This document, while not exhaustive, also
6 indicates some limitations (on purpose, or sometimes due to its poor design) of
7 the library at the present time.
9 There is one special file,"alpm.h", which is the public interface that
10 should be distributed and installed on systems with the library. Only
11 structures, data and functions declared within this file are made available to
12 the frontend. Lots of structures are of an opaque type and their fields are
13 only accessible in read-only mode, through some clearly defined functions.
15 In addition to "alpm.h", the interfaces of "alpm_list.h" have also been made
16 available to the frontend, for allowing it to manipulate the lists returned by
19 Several structures and functions have been renamed compared to pacman 2.9 code.
20 This was done at first for the sake of naming scheme consistency, and then
21 primarily because of potential namespace conflicts between library and frontend
22 spaces. Indeed, it is not possible to have two different functions with the
23 same name declared in both spaces. To avoid such conflicts, internal function
24 names have been prepended with "_alpm_".
26 In a general manner, public library functions are named "alpm_<type>_<action>"
27 (examples: alpm_trans_commit(), alpm_release(), alpm_pkg_get_name(), ...).
28 Internal (and thus private) functions should be named "_alpm_XXX" for instance
29 (examples: _alpm_needbackup(), _alpm_runscriplet(), ...). Functions defined and
30 used inside a single file should be defined as "static".
35 alpm_initialize() is used to initialize library internals and to create
36 a transparent handle object. Before its call, the library can't be used.
38 alpm_release() just does the opposite (memory used by the library, and the
39 handle is freed). After its call, the library is no longer available.
44 The library does not use any configuration file. It is up to the front end to
45 configure the library as needed; the handle holds a number of configuration
48 All of the following options have a alpm_option_get_* and alpm_option_set_*
49 function for getting and setting the value. They cannot be set before the
50 library is initialized.
52 * logcb: The callback function for "log" operations.
53 * dlcb: The callback function for download progress of each package.
54 * fetchcb: Callback for custom download function.
55 * totaldlcb: The callback function for overall download progress.
56 * eventcb: Callback for transaction messages.
57 * questioncb: Callback for selecting amongst choices.
58 * progresscb: Callback to handle display of transaction progress.
59 * gpgdir: Directory where GnuPG files are stored.
60 * arch: Allowed package architecture.
61 * deltaratio: Download deltas if possible; a ratio value.
62 * checkspace: Check disk space before installing.
63 * default_siglevel: Default signature verification level.
64 * local_file_siglevel: Signature verification level for local file upgrades.
65 * remote_file_siglevel: Signature verification level for remote file upgrades.
66 * logfile: The base path to pacman's log file (Default: /var/log/pacman.log)
67 * usesyslog: Log to syslog instead of `logfile` for file-base logging.
69 The following options also have `alpm_option_{add,remove}_*` functions, as the
70 values are list structures.
71 NOTE: The add and remove functions are NOT plural, as they are in English:
72 alpm_option_{get,set}_noupgrades -> alpm_option_{add,remove}_noupgrade.
74 * cachedirs: Paths to pacman's download caches (Default: /var/cache/pacman/pkg)
75 * noupgrades: Files which will never be touched by pacman (extracted as .pacnew)
76 * noextracts: Files which will never be extracted at all (no .pacnew file)
77 * ignorepkgs: Packages to ignore when upgrading.
78 * ignoregrps: Groups to ignore when upgrading.
80 The following options are read-only, having ONLY alpm_option_get_* functions:
82 * root: The root directory for pacman to install to
83 * dbpath: The toplevel database directory
84 * lockfile: The file used for locking the database (Default: <dbpath>/db.lck)
89 The transaction structure permits easy manipulations of several packages
90 at a time (i.e. adding, upgrade and removal operations).
92 A transaction can be initiated with a type (SYNC, UPGRADE or REMOVE),
93 and some flags (NODEPS, FORCE, CASCADE, ...).
95 Note: there can only be one type at a time: a transaction is either
96 created to add packages to the system, or either created to remove packages.
97 The frontend can't request for mixed operations: it has to run several
98 transactions, one at a time, in such a case.
100 The flags allow to tweak the library behaviour during its resolution.
101 Note, that some options of the handle can also modify the behavior of a
102 transaction (NOUPGRADE, IGNOREPKG, ...).
104 Note: once a transaction has been initiated, it is not possible anymore
105 to modify its type or its flags.
107 One can also add some targets to a transaction (alpm_trans_addtarget()).
108 These targets represent the list of packages to be handled.
110 Then, a transaction needs to be prepared (alpm_trans_prepare()). It
111 means that the various targets added, will be inspected and challenged
112 against the set of already installed packages (dependency checking, etc...)
114 Last, a callback is associated with each transaction. During the
115 transaction resolution, each time a new step is started or done (i.e
116 dependency or conflict checking, package adding or removal, ...), the
117 callback is called, allowing the frontend to be aware of the progress of
118 the resolution. Can be useful to implement a progress bar.
123 libalpm maintains two caches for each DB. One is a general package cache, the
124 other is a group cache (for package groups). These caches are loaded on demand,
125 and freed when the library is.
127 It is important to note that, as a general rule, package structures should NOT
128 be freed manually, as they SHOULD be part of the cache. The cache of a
129 database is always updated by the library after an operation changing the
130 database content (adding and/or removal of packages). Beware frontends ;)
135 The package structure maintains all information for a package. In general,
136 packages should never be freed from front-ends, as they should always be part
137 of the package cache.
139 The 'origin' data member indicates whether the package is from a file (i.e. -U
140 operations) or from the package cache. In the case of a file, all data members
141 available are present in the structure. Packages indicated as being from the
142 cache have data members filled on demand. For this reason, the alpm_pkg_get_*
143 functions will load the data from the DB as needed.
148 The library provides a global variable pm_errno.
149 It aims at being to the library what errno is for C system calls.
151 Almost all public library functions are returning an integer value: 0
152 indicating success, -1 indicating a failure.
153 If -1 is returned, the variable pm_errno is set to a meaningful value
154 Wise frontends should always care for these returned values.
156 Note: the helper function alpm_strerror() can also be used to translate one
157 specified error code into a more friendly sentence, and alpm_strerrorlast()
158 does the same for the last error encountered (represented by pm_errno).
163 The alpm_list_t structure is a doubly-linked list for use with the libalpm
164 routines. This type is provided publicly so that frontends are free to use it
165 if they have no native list type (C++, glib, python, etc all have list types).
166 See the proper man pages for alpm_list_t references.
170 PACMAN frontend overview & internals
171 ====================================
173 Here are some words about the frontend responsibilities.
174 The library can operate only a small set of well defined operations and
177 High level features are left to the frontend ;)
179 For instance, during a sysupgrade, the library returns the whole list of
180 packages to be upgraded, without any care for its content.
181 The frontend can inspect the list and perhaps notice that "pacman"
182 itself has to be upgraded. In such a case, the frontend can choose to
183 perform a special action.
186 [MAIN] (see pacman.c)
188 Calls for alpm_initialize(), and alpm_release().
189 Read the configuration file, and parse command line arguments.
190 Based on the action requested, it initiates the appropriate transactions
191 (see pacman_upgrade(), pacman_remove(), pacman_sync() in files upgrade.c,
192 remove.c and sync.c).
195 [CONFIGURATION] (see conf.h)
197 The frontend is using a configuration file, usually "/etc/pacman.conf". Some
198 of these options are only useful for the frontend only (mainly the ones used to
199 control the output like totaldownload, or the behavior with cleanmethod and
200 syncfirst). The rest is used to configure the library.
203 [UPGRADE/REMOVE/SYNC]
205 The file pacman.c has been divided into several smaller files, namely
206 upgrade.c, remove.c, sync.c and query.c, to hold the big parts: pacman_upgrade,
207 pacman_remove, pacman_sync.
209 These 3 functions have been split to ease the code reading.
213 API CHANGES BETWEEN 3.1 AND 3.2
214 ===============================
217 - alpm_db_whatprovides()
218 - alpm_splitdep (no longer public)
219 - trans->targets was removed, so alpm_trans_get_targets() as well
221 PM_ERR_OPT_*, PM_ERR_PKG_INSTALLED, PM_ERR_DLT_CORRUPTED,
222 PM_ERR_LIBARCHIVE_ERROR
223 - event: PM_TRANS_EVT_EXTRACT_DONE
224 - PM_TRANS_TYPE_ADD pmtranstype_t (add transaction)
225 - PM_TRANS_FLAG_DEPENDSONLY pmtransflag_t
228 - alpm_grp_get_pkgs returns with pmpkg_t list, not package-name list
229 - Swap parameters on PM_TRANS_CONV_INSTALL_IGNOREPKG callback function
230 - download callback API changed: alpm_cb_download, alpm_cb_totaldl split
231 (+ new alpm_option_get_totaldlcb(), alpm_option_set_totaldlcb() functions)
232 - unsigned long->off_t changes where size is used
233 - pmsyncpkg_t struct changes:
234 - pmsynctype_t and alpm_sync_get_type() were removed
235 - alpm_sync_get_data() was removed
236 - alpm_sync_get_removes() was added
239 - alpm_delta_get_from_md5sum(), alpm_delta_get_to_md5sum()
240 - alpm_miss_get_causingpkg() (new causingpkg field in pmdepmissing_t)
241 - alpm_checkdbconflicts()
242 - alpm_sync_newversion()
245 PM_ERR_DLT_INVALID, PM_ERR_LIBARCHIVE, PM_ERR_LIBDOWNLOAD and
246 PM_ERR_EXTERNAL_DOWNLOAD
248 PM_TRANS_FLAG_ALLEXPLICIT, PM_TRANS_FLAG_UNNEEDED and
249 PM_TRANS_FLAG_RECURSEALL
252 API CHANGES BETWEEN 3.2 AND 3.3
253 ===============================
256 - pmsyncpkg_t struct (pmpkg_t is used for all types of transaction targets):
257 - alpm_sync_get_pkg()
258 - alpm_sync_get_removes() (use alpm_pkg_get_removes() instead)
259 - HoldPkg handling (it is the front-end's task):
260 - alpm_option_get_holdpkgs()
261 - alpm_option_add_holdpkg()
262 - alpm_option_set_holdpkgs()
263 - alpm_option_remove_holdpkg()
264 - PM_TRANS_CONV_REMOVE_HOLDPKG conversation
265 - Print URIs feature (it is the front-end's task):
266 - flag: PM_TRANS_FLAG_PRINTURIS
267 - event: PM_TRANS_EVT_PRINTURI
268 - alpm_delta_get_from_md5sum() and alpm_delta_get_to_md5sum()
269 - alpm_sync_sysupgrade()
271 PM_ERR_TRANS_COMMITING, PM_ERR_TRANS_DOWNLOADING, PM_ERR_PKG_LOAD,
272 PM_ERR_PKG_CANT_FRESH, PM_ERR_GRP_NOT_FOUND, PM_ERR_USER_ABORT,
273 PM_ERR_INTERNAL_ERROR, PM_ERR_DB_SYNC, PM_ERR_PKG_HOLD and
277 - XferCommand support was removed, any fetch callback function can be defined:
278 - alpm_option_get_xfercommand() and alpm_option_set_xfercommand() were removed
279 - alpm_option_get_fetchcb() and alpm_option_set_fetchcb() were added
281 - alpm_db_getpkgcache() -> alpm_db_get_pkgcache()
282 - alpm_db_getgrpcache() -> alpm_db_get_grpcache()
283 - alpm_dep_get_string() -> alpm_dep_compute_string()
284 - alpm_get_md5sum() -> alpm_compute_md5sum()
285 - alpm_checkdbconflicts() -> alpm_checkconflicts()
286 - alpm_trans_sysupgrade() has a new enable_downgrade parameter
287 - alpm_checkdeps() and alpm_checkconflicts() require local package list instead
289 - the to-be-upgraded package is passed to the callback function with
290 PM_TRANS_EVT_UPGRADE_START (as the second parameter)
291 - the "requiredby" package is never passed to the callback function with
292 PM_TRANS_CONV_INSTALL_IGNOREPKG (the second parameter is always NULL)
296 - alpm_pkg_get_removes()
297 - conversation: PM_TRANS_CONV_REMOVE_PKGS (remove unresolvable targets)
298 - flag: PM_TRANS_FLAG_NOLOCK (do not lock database)
300 PM_ERR_SERVER_NONE, PM_ERR_TRANS_NOT_LOCKED, PM_ERR_PKG_IGNORED and
304 API CHANGES BETWEEN 3.3 AND 3.4
305 ===============================
308 - pmtranstype_t struct (transaction type), alpm_trans_get_type()
309 - alpm_option_get_nopassiveftp(), alpm_option_set_nopassiveftp()
312 - interface for target loading:
313 - alpm_trans_addtarget() and alpm_trans_sysupgrade() were removed
314 - alpm_sync_target() and alpm_sync_dbtarget() can be used to add a sync target
315 - alpm_sync_sysupgrade() can be used to add outdated packages (for sysupgrade)
316 - alpm_add_target() can be used to add an add/upgrade target
317 - alpm_remove_target() can be used to add a remove target
318 - interface for target listing:
319 - alpm_trans_get_pkgs() was removed
320 - alpm_pkg_get_removes() was removed
321 - alpm_trans_get_add() can be used to list add/upgrade/sync targets
322 - alpm_trans_get_remove() can be used to list to-be-removed packages
323 - the type parameter of alpm_trans_init() was removed
324 - the type of alpm_db_fetch callback function: mtimeold and mtimenew parameters
325 were replaced by force parameter
326 - unsigned short -> int changes for Boolean variables
329 - alpm_db_set_pkgreason()
330 - alpm_option_get_arch(), alpm_option_set_arch()
331 - alpm_option_get_usedelta()
332 - alpm_pkg_unused_deltas()
333 - alpm_conflict_get_reason()
334 - error code: PM_ERR_PKG_INVALID_ARCH
337 API CHANGES BETWEEN 3.4 AND 3.5
338 ===============================
341 - alpm_db_register_local()
342 - alpm_pkg_has_force()
346 - alpm_trans_cb_progress type had some types changed from int to size_t
347 - alpm_cb_log format string is now const char *
348 - the interface to add/remove targets:
349 - functions take pmpkg_t * rather than char *.
350 - alpm_sync_target() and alpm_sync_dbtarget() are replaced by alpm_add_pkg()
351 - alpm_add_target() is replaced by alpm_add_pkg()
352 - alpm_remove_target() is replaced by alpm_remove_pkg()
353 - packages can come from:
354 - alpm_db_get_pkg() for normal targets
355 - alpm_find_dbs_satisfier() for versioned provisions
356 - alpm_find_grp_pkgs() for groups
357 - alpm_deptest() is replaced by the more flexibile alpm_find_satisfier()
358 - size_t used for alpm_list_t sizes
359 - return type for alpm_list_count()
360 - parameter type in alpm_list_msort() and alpm_list_nth()
363 - alpm_option_get_checkspace(), alpm_option_set_checkspace()
364 - alpm_find_grp_pkgs()
365 - alpm_trans_get_flags()
367 PM_ERR_DISK_SPACE, PM_ERR_WRITE
369 PM_TRANS_FLAG_NODEPVERSION, PM_TRANS_EVT_DISKSPACE_START,
370 PM_TRANS_EVT_DISKSPACE_DONE, PM_TRANS_CONV_SELECT_PROVIDER,
371 PM_TRANS_PROGRESS_DISKSPACE_START, PM_TRANS_PROGRESS_INTEGRITY_START
374 API CHANGES BETWEEN 3.5 AND 4.0
375 ===============================
379 PM_ERR_LIBFETCH, PM_ERR_WRITE
380 - alpm_option_set_root(), alpm_option_set_dbpath()
382 - alpm_grp_get_name(), alpm_grp_get_pkgs()
383 - alpm_delta_get_from(), alpm_delta_get_to(), alpm_delta_get_filename(),
384 alpm_delta_get_md5sum(), alpm_delta_get_size()
385 - alpm_miss_get_target(), alpm_miss_get_dep(), alpm_miss_get_causingpkg()
386 - alpm_dep_get_mod(), alpm_dep_get_name(), alpm_dep_get_version()
387 - alpm_conflict_get_package1(), alpm_conflict_get_package2(),
388 alpm_conflict_get_reason()
389 - alpm_fileconflict_get_target(), alpm_fileconflict_get_type(),
390 alpm_fileconflict_get_file(), alpm_fileconflict_get_ctarget()
394 - PM_ prefixes for enum values are now ALPM_
395 - pm prefixes for structs and enums are now alpm_
396 - alpm_initialize now has parameters: char *root, char *dbpath,
397 alpm_errno_t *err and returns an alpm_handle_t struct.
398 - alpm_release now takes an alpm_handle_t *.
399 - alpm_db_register_sync() now requires a extra parameter of a alpm_siglevel_t.
400 - alpm_pkg_load() now requires an extra parameter of an alpm_siglevel_t
401 - alpm_db_setserver() replaced by alpm_db_set_servers(), alpm_db_add_server(),
402 alpm_db_remove_server()
403 - alpm_trans_init() no longer takes callbacks, set those using
404 alpm_option_set_*cb() functions
405 - many functions now require a first parameter of an alpm_handle_t *:
409 - alpm_option_remove_*
412 - alpm_checkconflicts
414 - alpm_db_register_sync
415 - alpm_db_set_pkgreason
416 - alpm_db_unregister_all
418 - alpm_find_dbs_satisfier
423 - alpm_sync_sysupgrade
424 - several structs are no longer opaque
430 - alpm_fileconflict_t
436 alpm_{get,set}_eventcb(), alpm_option_{get,set}_convcb(),
437 alpm_option_{get,set}_progresscb()
438 - package signing functions:
439 alpm_option_get_default_siglevel(), alpm_option_set_default_siglevel(),
440 alpm_option_get_gpgdir(), alpm_option_set_gpgdir(), alpm_db_get_siglevel(),
441 alpm_siglist_cleanup(), alpm_db_check_pgp_signature(), alpm_pkg_check_pgp_signature(),
442 alpm_pkg_get_origin(), alpm_pkg_get_sha256sum(), alpm_pkg_get_base64_sig()
444 alpm_list_to_array(), alpm_list_previous()
446 alpm_backup_t, alpm_file_t, alpm_filelist_t
448 alpm_siglevel_t, alpm_sigstatus_t, alpm_sigvalidity_t, alpm_pkgfrom_t
450 ALPM_ERR_DB_INVALID, ALPM_ERR_DB_INVALID_SIG, ALPM_ERR_GPGME,
451 ALPM_ERR_PKG_INVALID_CHECKSUM, ALPM_ERR_PKG_INVALID_SIG, ALPM_ERR_SIG_INVALID,
455 API CHANGES BETWEEN 4.0 AND 4.1
456 ===============================
459 - alpm_list_getdata()
462 - alpm_pkgfrom_t members are now prefixed with ALPM_
463 - alpm_siglevel_t - added members ALPM_SIG_PACKAGE_SET, ALPM_SIG_PACKAGE_TRUST_SET
464 - alpm_depend_t - additional desc member
465 - alpm_filelist_t - additional resolved_path member
466 - alpm_pgpkey_t - added members length, revoked, pubkey_algo
467 - alpm_logaction - added caller identifier argument
469 - alpm_option_get_localdb -> alpm_get_localdb
470 - alpm_option_get_syncdbs -> alpm_get_syncdbs
471 - alpm_db_register_sync -> alpm_register_syncdb
472 - alpm_db_unregister_all -> alpm_unregister_all_syncdbs
473 - alpm_db_readgroup -> alpm_db_get_group
474 - alpm_db_set_pkgreason -> alpm_pkg_set_reason (handle parameter removed)
475 - alpm_time_t typedef used for all times
476 - members of alpm_pgpkey_t
477 - return types of alpm_pkg_get_builddate and alpm_pkg_get_installdate
478 - delta options now use required ratio rather than on/off
479 - alpm_option_get_usedelta -> alpm_option_get_deltaratio
480 - alpm_option_set_usedelta -> alpm_option_set_deltaratio
483 - tracking of how a package was validated:
484 - alpm_pkgvalidation_t
485 - alpm_pkg_get_validation()
486 - adjustable signature verification levels for upgrade operations:
487 - alpm_option_get_local_file_siglevel()
488 - alpm_option_set_local_file_siglevel()
489 - alpm_option_get_remote_file_siglevel()
490 - alpm_option_set_remote_file_siglevel()
491 - sync database usage functions:
493 - alpm_db_set_usage()
494 - alpm_db_get_usage()
495 - wrapper functions for reading mtree files
496 - alpm_pkg_mtree_open()
497 - alpm_pkg_mtree_next()
498 - alpm_pkg_mtree_close()
501 - alpm_pkg_compute_optionalfor()
502 - alpm_filelist_contains()
507 ALPM_EVENT_OPTDEP_REQUIRED, ALPM_EVENT_DATABASE_MISSING,
508 ALPM_EVENT_KEYRING_START, ALPM_EVENT_KEYRING_DONE, ALPM_EVENT_KEY_DOWNLOAD_START,
509 ALPM_EVENT_KEY_DOWNLOAD_DONE, ALPM_PROGRESS_KEYRING_START