Date: Sunday, February 11, 2007 @ 23:45:22 Author: aaron Path: /home/cvs-pacman/pacman-lib Modified: README (1.9 -> 1.10) lib/libalpm/alpm.c (1.116 -> 1.117) lib/libalpm/alpm.h (1.75 -> 1.76) lib/libalpm/handle.c (1.31 -> 1.32) lib/libalpm/handle.h (1.14 -> 1.15) src/pacman/query.c (1.24 -> 1.25) src/pacman/sync.c (1.108 -> 1.109) * Updated the README file * Removed the handle->needles param. It's not needed not that alpm_list_t is public ----------------------+ README | 200 +++++++++++++++++++------------------------------ lib/libalpm/alpm.c | 6 - lib/libalpm/alpm.h | 2 lib/libalpm/handle.c | 11 -- lib/libalpm/handle.h | 1 src/pacman/query.c | 5 - src/pacman/sync.c | 6 - 7 files changed, 84 insertions(+), 147 deletions(-) Index: pacman-lib/README diff -u pacman-lib/README:1.9 pacman-lib/README:1.10 --- pacman-lib/README:1.9 Thu Feb 8 00:58:11 2007 +++ pacman-lib/README Sun Feb 11 23:45:21 2007 @@ -15,7 +15,7 @@ In addition to "alpm.h", the interfaces of "alpm_list.h" have also been made available to the frontend. It is not a requirement for the frontend to use these list functions; however, it prevents frontends from having to reimplement -possibly useful functions. +a list data structure. Several structures and functions have been renamed compared to pacman 2.9 code. This was done at first for the sake of naming scheme consistency, and then @@ -25,53 +25,68 @@ names have been prepended with "_alpm_". In a general manner, public library functions are named "alpm_<type>_<action>" -(examples: alpm_trans_commit(), alpm_lib_release(), alpm_pkg_getinfo(), ...). +(examples: alpm_trans_commit(), alpm_release(), alpm_pkg_getinfo(), ...). 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". -NOTE: The below descriptions may be severely outdated. Yes it needs updating, -but it may be better done by doxygen comments and generated documentation. -[HANDLE] (see handle.c) +[Initialization] -The "handle" object is the heart of the library. It is a global -structure available from almost all other objects (althought some very -low level objects should not be aware of the handle object, like chained -list, package or groups structures. - -There is only one instance, created by the frontend upon -"alpm_lib_init()" call, and destroyed upon "alpm_lib_release()" call. - -alpm_lib_init() is used to initialize library internals and to create -the handle object (handle != NULL). -Before its call, the library can't be used. -alpm_lib_release() just does the opposite (memory used by the library is -freed, and handle is set to NULL). -After its call, the library is no more available. - -The aim of the handle is to provide a central placeholder for essential -library parameters (filesystem root, pointers to database objects, -configuration parameters, ...) - -The handle also allows to register a log callback usable by the frontend -to catch all sort of notifications from the library. -The frontend can choose the level of verbosity (i.e. the mask), or can -simply choose to not use the log callback. -A friendly frontend should care at least for WARNING and ERROR -notifications. -Other notifications can safely be ignored and are mainly available for -troubleshooting purpose. +alpm_init() is used to initialize library internals and to create +a transparent handle object. Before its call, the library can't be used. -Last, but not least, the handle holds a _unique_ transaction object. +alpm_lib_release() just does the opposite (memory used by the library, and the +handle is freed). After its call, the library is no longer available. -[TRANSACTION] (see trans.c, and also alpm.c) +[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, ...). + +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 +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) +* usesyslog: Log to syslog instead of `logfile` for file-base logging. +* upgradedelay: The time span to wait before listing a package as an upgrade (Default: 0) +* xfercommand: The command to use for downloading instead of pacman's internal + 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). + +* 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. + +The following options are read-only, having ONLY alpm_option_get_* functions: + +* localdb: A pmdb_t structure for the local (installed) database +* syncdbs: A list of pmdb_t structures to which pacman can sync from. + + +[Transactions] The transaction sturcture permits easy manipulations of several packages at a time (i.e. adding, upgrade and removal operations). -A transaction can be initiatied with a type (ADD, UPGRADE or REMOVE), +A transaction can be initiated with a type (ADD, UPGRADE or REMOVE), and some flags (NODEPS, FORCE, CASCADE, ...). Note: there can only be one type at a time: a transaction is either @@ -91,97 +106,60 @@ 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 alreayd installed packages (dependency checkings, +against the set of already installed packages (dependency checkings, Last, a callback is associated with each transaction. During the transaction resolution, each time a new step is started or done (i.e -dependency or conflict checkings, package adding or removal, ...), the +dependency or conflict checking, package adding or removal, ...), the callback is called, allowing the frontend to be aware of the progress of the resolution. Can be useful to implement a progress bar. -[CONFIGURATION/OPTIONS] (see handle.c) - -The library does not use any configuration file. The handle holds a -number of configuration options instead (IGNOREPKG, SYSLOG usage, -log file name, registered databases, ...). -It is up to the frontend to set the options of the library. -Options can be manipulated using calls to -alpm_set_option()/alpm_get_option(). - -Note: the file system root is a special option which can only be defined -when calling alpm_lib_init(). It can't be modified afterwards. +[Package Cache] - -[CACHE] (see cache.c) - -Compared to pacman 2.9, there is now one cache object connected to each -database object. -There are both a package and a group cache. -The cache is loaded only on demand (i.e the cache is loaded the first -time data from it should be used). - -Note: the cache of a database is always updated by the library after +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 ;) +packages). Beware frontends ;) -[PACKAGE] (see package.c, and also db.c) +[Package] -The package structure is using three new fields, namely: origin, data, -infolevel. -The purpose of these fields is to know some extra info about data stored -in package structures. +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. -For instance, where is the package coming from (i.e origin)? -Was it loaded from a file or loaded from the cache? -If it's coming from a file, then the field data holds the full path and -name of the file, and infolevel is set to the highest possible value -(all package fields are reputed to be known). -Otherwise, if the package comes from a database, data is a pointer to -the database structure hosting the package, and infolevel is set -according to the db_read() infolevel parameter (it is possible using -db_read() to only read a part of the package datas). +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. -Indeed, to reduce database access, all packages data requested by the -frontend are comming from the cache. As a consequence, the library needs -to know exactly the level of information about packages it holds, and -then decide if more data needs to be fetched from the database. -In file alpm.c, have a look at alpm_pkg_getinfo() function to get an -overview. - - -[ERRORS] (error.c) +[Errors] The library provides a global variable pm_errno. It aims at being to the library what errno is for C system calls. Almost all public library functions are returning an integer value: 0 -indicating success, whereas -1 would indicate a failure. +indicating success, -1 indicating a failure. If -1 is returned, the variable pm_errno is set to a meaningful value -(not always yet, but it should improve ;). 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. -[LIST] (see list.c, and especially list wrappers in alpm.c) +[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 +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. -It is a double chained list structure, use only for the internal needs -of the library. -A frontend should be free to use its own data structures to manipulate -packages. -For instance, consider a graphical frontend using the gtk toolkit (and -as a consequence the glib library). The frontend will make use of the -glib chained lists or trees. -As a consequence, the library only provides a simple and very small -interface to retrieve pointers to its internal data (see functions -alpm_list_first(), alpm_list_next() and alpm_list_getdata()), giving to -the frontend the responsibility to copy and store the data retrieved -from the library in its own data structures. PACMAN frontend overview & internals @@ -189,7 +167,7 @@ Here are some words about the frontend responsibilities. The library can operate only a small set of well defined operations and -dumy operations. +dummy operations. High level features are left to the frontend ;) @@ -212,7 +190,7 @@ [CONFIGURATION] (see conf.c) The frontend is using a configuration file, usually "/etc/pacman.conf". -Part of these options are only usefull for the frontend only (mainly, +Part of these options are only useful for the frontend only (mainly, the download stuffs, and some options like HOLDPKG). The rest is used to configure the library. @@ -224,28 +202,8 @@ 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, pacman_remove, pacman_sync. -These 3 functions have been splitted too to ease the code reading. - - -[DONWLOAD] (see download.c) - -The library is not providing download facilities. As a consequence, it -is up the the frontend to retrieve packages from Arch Linux servers. -To do so, pacman is linked against an improved version of libftp -supporting both http and ftp donwloads. -As a consequence, the frontend is repsonsible for the directory -/var/cache/pacman/pkgs. -One can consider that this cache is a facility provided by pacman. - -Note: other frontends have to download packages by themselves too, -although the cache directory can be shared by several frontends. - - -[LIST] (see list.c) -Single chained list. -A minimalistic chained list implementation to store options from the -configuration file, and targets passed to pacman on the command line. +These 3 functions have been split to ease the code reading. LIMITATIONS/BEHAVIOR CHANGES COMPARED TO PACMAN 2.9 Index: pacman-lib/lib/libalpm/alpm.c diff -u pacman-lib/lib/libalpm/alpm.c:1.116 pacman-lib/lib/libalpm/alpm.c:1.117 --- pacman-lib/lib/libalpm/alpm.c:1.116 Sat Feb 10 04:36:36 2007 +++ pacman-lib/lib/libalpm/alpm.c Sun Feb 11 23:45:21 2007 @@ -615,17 +615,15 @@ * @param db pointer to the package database to search in * @return the list of packages on success, NULL on error */ -alpm_list_t SYMEXPORT *alpm_db_search(pmdb_t *db) +alpm_list_t SYMEXPORT *alpm_db_search(pmdb_t *db, alpm_list_t* needles) { ALPM_LOG_FUNC; /* Sanity checks */ ASSERT(handle != NULL, return(NULL)); - ASSERT(handle->needles != NULL, return(NULL)); - ASSERT(handle->needles->data != NULL, return(NULL)); ASSERT(db != NULL, return(NULL)); - return(_alpm_db_search(db, handle->needles)); + return(_alpm_db_search(db, needles)); } /** @} */ Index: pacman-lib/lib/libalpm/alpm.h diff -u pacman-lib/lib/libalpm/alpm.h:1.75 pacman-lib/lib/libalpm/alpm.h:1.76 --- pacman-lib/lib/libalpm/alpm.h:1.75 Fri Feb 9 16:08:10 2007 +++ pacman-lib/lib/libalpm/alpm.h Sun Feb 11 23:45:22 2007 @@ -179,7 +179,7 @@ pmgrp_t *alpm_db_readgrp(pmdb_t *db, char *name); alpm_list_t *alpm_db_getgrpcache(pmdb_t *db); -alpm_list_t *alpm_db_search(pmdb_t *db); +alpm_list_t *alpm_db_search(pmdb_t *db, alpm_list_t* needles); /* * Packages Index: pacman-lib/lib/libalpm/handle.c diff -u pacman-lib/lib/libalpm/handle.c:1.31 pacman-lib/lib/libalpm/handle.c:1.32 --- pacman-lib/lib/libalpm/handle.c:1.31 Wed Jan 31 01:10:21 2007 +++ pacman-lib/lib/libalpm/handle.c Sun Feb 11 23:45:22 2007 @@ -113,7 +113,6 @@ FREELIST(handle->noextract); FREELIST(handle->ignorepkg); FREELIST(handle->holdpkg); - FREELIST(handle->needles); FREE(handle); return(0); @@ -135,7 +134,6 @@ const char *alpm_option_get_xfercommand() { return handle->xfercommand; } unsigned short alpm_option_get_nopassiveftp() { return handle->nopassiveftp; } unsigned short SYMEXPORT alpm_option_get_chomp() { return handle->chomp; } -alpm_list_t *alpm_option_get_needles() { return handle->needles; } unsigned short alpm_option_get_usecolor() { return handle->use_color; } pmdb_t *alpm_option_get_localdb() { return handle->db_local; } @@ -249,15 +247,6 @@ void alpm_option_set_chomp(unsigned short chomp) { handle->chomp = chomp; } -void SYMEXPORT alpm_option_add_needle(char *needle) -{ - handle->needles = alpm_list_add(handle->needles, strdup(needle)); -} -void alpm_option_set_needles(alpm_list_t *needles) -{ - if(handle->needles) FREELIST(handle->needles); - if(needles) handle->needles = needles; -} void alpm_option_set_usecolor(unsigned short usecolor) { handle->use_color = usecolor; Index: pacman-lib/lib/libalpm/handle.h diff -u pacman-lib/lib/libalpm/handle.h:1.14 pacman-lib/lib/libalpm/handle.h:1.15 --- pacman-lib/lib/libalpm/handle.h:1.14 Tue Jan 23 22:02:54 2007 +++ pacman-lib/lib/libalpm/handle.h Sun Feb 11 23:45:22 2007 @@ -62,7 +62,6 @@ char *xfercommand; /* External download command */ unsigned short nopassiveftp; /* Don't use PASV ftp connections */ unsigned short chomp; /* I Love Candy! */ - alpm_list_t *needles; /* needles for searching */ /* TODO why is this here? */ unsigned short use_color; /* enable colorful output */ } pmhandle_t; Index: pacman-lib/src/pacman/query.c diff -u pacman-lib/src/pacman/query.c:1.24 pacman-lib/src/pacman/query.c:1.25 --- pacman-lib/src/pacman/query.c:1.24 Wed Feb 7 00:25:45 2007 +++ pacman-lib/src/pacman/query.c Sun Feb 11 23:45:22 2007 @@ -87,10 +87,7 @@ int done = 0; if(config->op_q_search) { - for(i = targets; i; i = alpm_list_next(i)) { - alpm_option_add_needle(alpm_list_getdata(i)); - } - alpm_list_t *ret = alpm_db_search(db_local); + alpm_list_t *ret = alpm_db_search(db_local, targets); if(ret == NULL) { return(1); } Index: pacman-lib/src/pacman/sync.c diff -u pacman-lib/src/pacman/sync.c:1.108 pacman-lib/src/pacman/sync.c:1.109 --- pacman-lib/src/pacman/sync.c:1.108 Sat Feb 3 20:36:45 2007 +++ pacman-lib/src/pacman/sync.c Sun Feb 11 23:45:22 2007 @@ -236,14 +236,10 @@ { alpm_list_t *i, *j, *ret; - for(i = targets; i; i = alpm_list_next(i)) { - alpm_option_add_needle(alpm_list_getdata(i)); - } - for(i = syncs; i; i = alpm_list_next(i)) { pmdb_t *db = (pmdb_t *)alpm_list_getdata(i); if(targets) { - ret = alpm_db_search(db); + ret = alpm_db_search(db, targets); if(ret == NULL) { continue; }