From: Xavier Chantry Date: Fri, 25 Jul 2008 22:28:28 +0000 (+0200) Subject: Update README file. X-Git-Url: http://shining.toofishes.net/gitweb/gitweb.cgi?p=pacman.git;a=commitdiff_plain;h=ca2ad482a825fd9bbaa9f15d7d3a3d70125c9504 Update README file. Several information were outdated for the 3.2 release. Add a section for the API changes between 3.1 and 3.2. Signed-off-by: Xavier Chantry --- diff --git a/README b/README index 46b5bb2..4485507 100644 --- a/README +++ b/README @@ -25,7 +25,7 @@ same name declared in both spaces. To avoid such conflicts, internal function names have been prepended with "_alpm_". In a general manner, public library functions are named "alpm__" -(examples: alpm_trans_commit(), alpm_release(), alpm_pkg_getinfo(), ...). +(examples: alpm_trans_commit(), alpm_release(), alpm_pkg_get_name(), ...). Internal (and thus private) functions should be named "_alpm_XXX" for instance (examples: _alpm_needbackup(), _alpm_runscriplet(), ...). Functions defined and used inside a single file should be defined as "static". @@ -33,59 +33,61 @@ used inside a single file should be defined as "static". [Initialization] -alpm_init() is used to initialize library internals and to create +alpm_initialize() is used to initialize library internals and to create a transparent handle object. Before its call, the library can't be used. -alpm_lib_release() just does the opposite (memory used by the library, and the +alpm_release() just does the opposite (memory used by the library, and the handle is freed). After its call, the library is no longer available. [Options] -In the future, the library will not use any configuration file. It will be up -to the front end to The handle holds a -number of configuration options instead (IGNOREPKG, SYSLOG usage, -log file name, registered databases, ...). +The library does not use any configuration file. It is up to the front end to do so. +The handle holds a number of configuration options instead. All of the following options have a alpm_option_get_* and alpm_option_set_* -function for getting and setting the value. The cannot be set before the +function for getting and setting the value. They cannot be set before the library is initialized. * logcb: The callback function for "log" operations. -* dlcb: The callback function for download progress. -* logmask: The logging mask for which level of output is sent to the logcb. -* root: The root directory on which pacman operates (Default: /) -* dbpath: The base path to pacman's databases (Default: var/lib/pacman) -* cachedir: The base path to pacman's download cache (Default: var/cache/pacman) -* logfile: The base path to pacman's log file (Default: var/log/pacman.log) +* dlcb: The callback function for download progress of each package. +* totaldlcb: The callback function for overall download progress. +* root: The root directory for pacman to install to (Default: /) +* dbpath: The toplevel database directory (Default: /var/lib/pacman) +* logfile: The base path to pacman's log file (Default: /var/log/pacman.log) * usesyslog: Log to syslog instead of `logfile` for file-base logging. * xfercommand: The command to use for downloading instead of pacman's internal - downloading functionality. + downloading functionality. * nopassiveftp: Do not use passive FTP commands for ftp connections. -* chomp: No way, easter eggs are secret! -* usecolor: Unimplemented, but for the future. You can assume what it means. -The following options also have a `alpm_option_add_*` function, as the values -are list structures (NOTE: The add functions are NOT plural, as they're in -english: alpm_option_get_noupgrades -> alpm_option_add_noupgrade). +The following options also have `alpm_option_{add,remove}_*` functions, as the +values are list structures. +NOTE: The add and remove functions are NOT plural, as they're in english: +alpm_option_{get,set}_noupgrades -> alpm_option_{add,remove}_noupgrade. +* cachedirs: Paths to pacman's download caches (Default: /var/cache/pacman/pkg) * noupgrades: Files which will never be touched by pacman (extracted as .pacnew) * noextracts: Files which will never be extracted at all (no .pacnew file) * ignorepkgs: Packages to ignore when upgrading. -* holdpkgs: Packages which must be upgraded before continuing. +* ignoregrps: Groups to ignore when upgrading. +* holdpkgs: Important packages which need a confirmation before being removed. The following options are read-only, having ONLY alpm_option_get_* functions: +* lockfile: The file used for locking the database (Default: /var/lib/pacman/db.lck) * localdb: A pmdb_t structure for the local (installed) database * syncdbs: A list of pmdb_t structures to which pacman can sync from. +The following options are write-only, having ONLY alpm_option_set_* functions: + +* usedelta: Download delta files instead of complete packages if possible. [Transactions] -The transaction sturcture permits easy manipulations of several packages +The transaction structure permits easy manipulations of several packages at a time (i.e. adding, upgrade and removal operations). -A transaction can be initiated with a type (ADD, UPGRADE or REMOVE), +A transaction can be initiated with a type (SYNC, UPGRADE or REMOVE), and some flags (NODEPS, FORCE, CASCADE, ...). Note: there can only be one type at a time: a transaction is either @@ -105,7 +107,7 @@ These targets represent the list of packages to be handled. Then, a transaction needs to be prepared (alpm_trans_prepare()). It means that the various targets added, will be inspected and challenged -against the set of already installed packages (dependency checkings, +against the set of already installed packages (dependency checkings, etc...) Last, a callback is associated with each transaction. During the transaction resolution, each time a new step is started or done (i.e @@ -116,27 +118,27 @@ the resolution. Can be useful to implement a progress bar. [Package Cache] -libalpm maintains two caches for each DB. One is a general package cache, the -other is a group cache (for package groups). These caches are loaded on demand, +libalpm maintains two caches for each DB. One is a general package cache, the +other is a group cache (for package groups). These caches are loaded on demand, and freed when the libary is. -It is important to note tha, as a general rule, package structures should NOT be -freed manually, as they SHOULD be part of the cache. -The cache of a database is always updated by the library after -an operation changing the database content (adding and/or removal of -packages). Beware frontends ;) +It is important to note that, as a general rule, package structures should NOT +be freed manually, as they SHOULD be part of the cache. +The cache of a database is always updated by the library after an operation +changing the database content (adding and/or removal of packages). +Beware frontends ;) [Package] -The package structure maintains all information for a package. In general, -packages should never be freed from front-ends, as they should always be part of -the package cache. +The package structure maintains all information for a package. In general, +packages should never be freed from front-ends, as they should always be part +of the package cache. -The 'origin' data member indicates whether the package is from a file -(i.e. -U operations) or from the package cache. In the case of a file, all data -members available are present in the structure. Packages indicated as being -from the cache have data members filled on demand. For this reason, the -alpm_pkg_get_* functions will load the data from the DB as needed. +The 'origin' data member indicates whether the package is from a file (i.e. -U +operations) or from the package cache. In the case of a file, all data members +available are present in the structure. Packages indicated as being from the +cache have data members filled on demand. For this reason, the alpm_pkg_get_* +functions will load the data from the DB as needed. [Errors] @@ -149,13 +151,14 @@ indicating success, -1 indicating a failure. If -1 is returned, the variable pm_errno is set to a meaningful value Wise frontends should always care for these returned values. -Note: the helper function alpm_strerror() can also be used to translate -the error code into a more friendly sentence. +Note: the helper function alpm_strerror() can also be used to translate one +specified error code into a more friendly sentence, and alpm_strerrorlast() +does the same for the last error encountered (represented by pm_errno). [List - alpm_list_t] The alpm_list_t structure is a doubly-linked list for use with the libalpm -routines. This type is provided publicly so that frontends are free to use it +routines. This type is provided publicly so that frontends are free to use it if they have no native list type (C++, glib, python, etc all have list types). See the proper man pages for alpm_list_t references. @@ -179,41 +182,65 @@ perform a special action. [MAIN] (see pacman.c) -Calls for alpm_lib_init(), and alpm_lib_release(). +Calls for alpm_initialize(), and alpm_release(). Read the configuration file, and parse command line arguments. Based on the action requested, it initiates the appropriate transactions -(see pacman_add(), pacman_remove(), pacman_sync() in files add.c, +(see pacman_upgrade(), pacman_remove(), pacman_sync() in files upgrade.c, remove.c and sync.c). -[CONFIGURATION] (see conf.c) +[CONFIGURATION] (see conf.h) The frontend is using a configuration file, usually "/etc/pacman.conf". -Part of these options are only useful for the frontend only (mainly, -the download stuffs, and some options like HOLDPKG). +Part of these options are only useful for the frontend only (mainly the ones +used to control the output like showsize or totaldownload, or the behavior with +cleanmethod and syncfirst). The rest is used to configure the library. -[ADD/UPGRADE/REMOVE/SYNC] - -Nothing new here, excepted some reorganization. +[UPGRADE/REMOVE/SYNC] The file pacman.c has been divided into several smaller files, namely -add.c, remove.c, sync.c and query.c, to hold the big parts: pacman_add, +upgrade.c, remove.c, sync.c and query.c, to hold the big parts: pacman_upgrade, pacman_remove, pacman_sync. These 3 functions have been split to ease the code reading. -LIMITATIONS/BEHAVIOR CHANGES COMPARED TO PACMAN 2.9 +API CHANGES BETWEEN 3.1 AND 3.2 =================================================== -Excepted missing features still needing to be implemented, one can -notice the following limitations: - -- If pacman is out of date, the frontend displays a warning and recommends -to give up the on-going transanction. The frontend does not allow to -upgrade pacman itself on-the-fly, and thus it should be restarted with -only "pacman" as a target. - -- ... +[REMOVED] +-alpm_db_whatprovides() +-alpm_splitdep (no longer public) +-trans->targets was removed, so alpm_trans_get_targets() as well +-error codes: +PM_ERR_OPT_*, PM_ERR_PKG_INSTALLED, PM_ERR_DLT_CORRUPTED, +PM_ERR_LIBARCHIVE_ERROR +-event: PM_TRANS_EVT_EXTRACT_DONE +-PM_TRANS_TYPE_ADD pmtranstype_t (add transaction) +-PM_TRANS_FLAG_DEPENDSONLY pmtransflag_t + + +[CHANGED] +- alpm_grp_get_pkgs returns with pmpkg_t list, not package-name list +- Swap parameters on PM_TRANS_CONV_INSTALL_IGNOREPKG callback function +-download callback API changed: alpm_cb_download, alpm_cb_totaldl split + (+ new alpm_option_get_totaldlcb(), alpm_option_set_totaldlcb() functions) +-unsigned long->off_t changes where size is used +-pmsyncpkg_t struct changes: + -pmsynctype_t and alpm_sync_get_type() were removed + -alpm_sync_get_data() was removed + -alpm_sync_get_removes() was added + +[ADDED] +-alpm_delta_get_from_md5sum(), alpm_delta_get_to_md5sum() +-alpm_miss_get_causingpkg() (new causingpkg field in pmdepmissing_t) +-alpm_checkdbconflicts() +-alpm_sync_newversion() +-alpm_deptest() +-error codes : +PM_ERR_DLT_INVALID, PM_ERR_LIBARCHIVE, PM_ERR_LIBDOWNLOAD, +PM_ERR_EXTERNAL_DOWNLOAD +-flags: +PM_TRANS_FLAG_ALLEXPLICIT, PM_TRANS_FLAG_UNNEEDED and PM_TRANS_FLAG_RECURSEALL