moparisthebest/pacman
1
0
Fork 0
mirror of https://github.com/moparisthebest/pacman synced 2025-02-28 09:21:53 -05:00
Code Issues Releases Wiki Activity

* Updated the README file

Browse Source 
* Removed the handle->needles param.  It's not needed not that alpm_list_t is
  public
This commit is contained in:
Aaron Griffin 2007-02-12 04:45:21 +00:00
parent 9803ec3066
commit dfb1f1e237
7 changed files with 84 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

200
README
View File

@ -15,7 +15,7 @@ only accessible in read-only mode, through some clearly defined functions.
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 @@ 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_<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.
alpm_init() is used to initialize library internals and to create
a transparent handle object. Before its call, the library can't be used.
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.
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 @@ 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 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)
[Package Cache]
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.
[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).
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.
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] (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 @@ PACMAN frontend overview & internals
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 @@ remove.c and sync.c).
[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 @@ Nothing new here, excepted some reorganization.
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

6
lib/libalpm/alpm.c
View File

@ -615,17 +615,15 @@ char SYMEXPORT *alpm_pkg_name_hasarch(char *pkgname)
* @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));
}
/** @} */

2
lib/libalpm/alpm.h
View File

@ -179,7 +179,7 @@ alpm_list_t *alpm_db_whatprovides(pmdb_t *db, char *name);
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

11
lib/libalpm/handle.c
View File

@ -113,7 +113,6 @@ int _alpm_handle_free(pmhandle_t *handle)
FREELIST(handle->noextract);
FREELIST(handle->ignorepkg);
FREELIST(handle->holdpkg);
FREELIST(handle->needles);
FREE(handle);
return(0);
@ -135,7 +134,6 @@ time_t alpm_option_get_upgradedelay() { return handle->upgradedelay; }
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_nopassiveftp(unsigned short nopasv)
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;

1
lib/libalpm/handle.h
View File

@ -62,7 +62,6 @@ typedef struct _pmhandle_t {
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;

5
src/pacman/query.c
View File

@ -87,10 +87,7 @@ int pacman_query(alpm_list_t *targets)
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);
}

6
src/pacman/sync.c
View File

@ -236,14 +236,10 @@ static int sync_search(alpm_list_t *syncs, alpm_list_t *targets)
{
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;
}