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;
}