diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 192 |
1 files changed, 75 insertions, 117 deletions
@@ -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_release() just does the opposite (memory used by the library, and the +handle is freed). After its call, the library is no longer available. -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, ...) +[Options] -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. +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. -Last, but not least, the handle holds a _unique_ transaction object. +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. -[TRANSACTION] (see trans.c, and also alpm.c) + +[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) - -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). +[Package Cache] -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 @@ 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 |