removed "^M" symbols at end of lines
This commit is contained in:
Aurelien Foret
parent
1c9041814b
commit
9b5b86a14e
1 changed files with 270 additions and 270 deletions
540
README
540
README
|
|
@ -1,270 +1,270 @@
|
||||||
==========================================================================
|
==========================================================================
|
||||||
README:
|
README:
|
||||||
|
|
||||||
Overview and internals of the ALPM library and the PACMAN frontend.
|
Overview and internals of the ALPM library and the PACMAN frontend.
|
||||||
|
|
||||||
This document describes the state of the implementation before its CVS
|
This document describes the state of the implementation before its CVS
|
||||||
import.
|
import.
|
||||||
At this stage, the code is in pre-alpha state, but the design should not
|
At this stage, the code is in pre-alpha state, but the design should not
|
||||||
change that much.
|
change that much.
|
||||||
There's still need for some work to get the current code properly working.
|
There's still need for some work to get the current code properly working.
|
||||||
The tag "ORE" was added in various places in the code, each time a point
|
The tag "ORE" was added in various places in the code, each time a point
|
||||||
remains unclear or is not yet implemented.
|
remains unclear or is not yet implemented.
|
||||||
|
|
||||||
==========================================================================
|
==========================================================================
|
||||||
|
|
||||||
|
|
||||||
ALPM library overview & internals
|
ALPM library overview & internals
|
||||||
=================================
|
=================================
|
||||||
|
|
||||||
Here is a list of the main objects and files from the ALPM (i.e. Arch
|
Here is a list of the main objects and files from the ALPM (i.e. Arch
|
||||||
Linux Package Management) library.
|
Linux Package Management) library.
|
||||||
This document, whilst not exhaustive, also indicates some limitations
|
This document, whilst not exhaustive, also indicates some limitations
|
||||||
(on purpose, or sometimes due to its poor design) of the library at the
|
(on purpose, or sometimes due to its poor design) of the library at the
|
||||||
present time.
|
present time.
|
||||||
|
|
||||||
Note: there is one special file ("alpm.h") which is the public interface
|
Note: there is one special file ("alpm.h") which is the public interface
|
||||||
that should be distributed and installed on systems with the library.
|
that should be distributed and installed on systems with the library.
|
||||||
Only structures, data and functions declared within this file are made
|
Only structures, data and functions declared within this file are made
|
||||||
available to the frontend.
|
available to the frontend.
|
||||||
Lots of structures are of an opaque type and their fields are only
|
Lots of structures are of an opaque type and their fields are only
|
||||||
accessible in read-only mode, through some clearly defined functions.
|
accessible in read-only mode, through some clearly defined functions.
|
||||||
|
|
||||||
Note: several structures and functions have been renamed compared to
|
Note: several structures and functions have been renamed compared to
|
||||||
pacman 2.9 code.
|
pacman 2.9 code.
|
||||||
This was done at first for the sake of naming scheme consistency, and
|
This was done at first for the sake of naming scheme consistency, and
|
||||||
then primarily because of potential namespace conflicts between library
|
then primarily because of potential namespace conflicts between library
|
||||||
and frontend spaces.
|
and frontend spaces.
|
||||||
Indeed, it is not possible to have two different functions with the same
|
Indeed, it is not possible to have two different functions with the same
|
||||||
name declared in both spaces.
|
name declared in both spaces.
|
||||||
To avoid such conflicts, some function names have been prepended with
|
To avoid such conflicts, some function names have been prepended with
|
||||||
"_alpm_".
|
"_alpm_".
|
||||||
In a general manner, public library functions are named
|
In a general manner, public library functions are named
|
||||||
"alpm_<type>_<action>" (examples: alpm_trans_commit(),
|
"alpm_<type>_<action>" (examples: alpm_trans_commit(),
|
||||||
alpm_lib_release(), alpm_pkg_getinfo(), ...).
|
alpm_lib_release(), alpm_pkg_getinfo(), ...).
|
||||||
Internal (and thus private) functions should be named "_alpm_XXX" for
|
Internal (and thus private) functions should be named "_alpm_XXX" for
|
||||||
instance (examples: _alpm_needbackup(), _alpm_runscriplet(), ...).
|
instance (examples: _alpm_needbackup(), _alpm_runscriplet(), ...).
|
||||||
As of now, this scheme is only applied to most sensitive functions
|
As of now, this scheme is only applied to most sensitive functions
|
||||||
(mainly the ones from util.c), which have generic names, and thus, which
|
(mainly the ones from util.c), which have generic names, and thus, which
|
||||||
are likely to be redefined in the frontend.
|
are likely to be redefined in the frontend.
|
||||||
One can consider that the frontend should have the priority in function
|
One can consider that the frontend should have the priority in function
|
||||||
names choice, and that it is up to the library to hide its symbols to
|
names choice, and that it is up to the library to hide its symbols to
|
||||||
avoid conflicts with the frontend ones.
|
avoid conflicts with the frontend ones.
|
||||||
Finally, functions defined and used inside a single file should be
|
Finally, functions defined and used inside a single file should be
|
||||||
defined as "static".
|
defined as "static".
|
||||||
|
|
||||||
|
|
||||||
[HANDLE] (see handle.c)
|
[HANDLE] (see handle.c)
|
||||||
|
|
||||||
The "handle" object is the heart of the library. It is a global
|
The "handle" object is the heart of the library. It is a global
|
||||||
structure available from almost all other objects (althought some very
|
structure available from almost all other objects (althought some very
|
||||||
low level objects should not be aware of the handle object, like chained
|
low level objects should not be aware of the handle object, like chained
|
||||||
list, package or groups structures.
|
list, package or groups structures.
|
||||||
|
|
||||||
There is only one instance, created by the frontend upon
|
There is only one instance, created by the frontend upon
|
||||||
"alpm_lib_init()" call, and destroyed upon "alpm_lib_release()" call.
|
"alpm_lib_init()" call, and destroyed upon "alpm_lib_release()" call.
|
||||||
|
|
||||||
alpm_lib_init() is used to initialize library internals and to create
|
alpm_lib_init() is used to initialize library internals and to create
|
||||||
the handle object (handle != NULL).
|
the handle object (handle != NULL).
|
||||||
Before its call, the library can't be used.
|
Before its call, the library can't be used.
|
||||||
alpm_lib_release() just does the opposite (memory used by the library is
|
alpm_lib_release() just does the opposite (memory used by the library is
|
||||||
freed, and handle is set to NULL).
|
freed, and handle is set to NULL).
|
||||||
After its call, the library is no more available.
|
After its call, the library is no more available.
|
||||||
|
|
||||||
The aim of the handle is to provide a central placeholder for essential
|
The aim of the handle is to provide a central placeholder for essential
|
||||||
library parameters (filesystem root, pointers to database objects,
|
library parameters (filesystem root, pointers to database objects,
|
||||||
configuration parameters, ...)
|
configuration parameters, ...)
|
||||||
|
|
||||||
The handle also allows to register a log callback usable by the frontend
|
The handle also allows to register a log callback usable by the frontend
|
||||||
to catch all sort of notifications from the library.
|
to catch all sort of notifications from the library.
|
||||||
The frontend can choose the level of verbosity (i.e. the mask), or can
|
The frontend can choose the level of verbosity (i.e. the mask), or can
|
||||||
simply choose to not use the log callback.
|
simply choose to not use the log callback.
|
||||||
A friendly frontend should care at least for WARNING and ERROR
|
A friendly frontend should care at least for WARNING and ERROR
|
||||||
notifications.
|
notifications.
|
||||||
Other notifications can safely be ignored and are mainly available for
|
Other notifications can safely be ignored and are mainly available for
|
||||||
troubleshooting purpose.
|
troubleshooting purpose.
|
||||||
|
|
||||||
Last, but not least, the handle holds a _unique_ transaction object.
|
Last, but not least, the handle holds a _unique_ transaction object.
|
||||||
|
|
||||||
|
|
||||||
[TRANSACTION] (see trans.c, and also alpm.c)
|
[TRANSACTION] (see trans.c, and also alpm.c)
|
||||||
|
|
||||||
The transaction sturcture permits easy manipulations of several packages
|
The transaction sturcture permits easy manipulations of several packages
|
||||||
at a time (i.e. adding, upgrade and removal operations).
|
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 initiatied with a type (ADD, UPGRADE or REMOVE),
|
||||||
and some flags (NODEPS, FORCE, CASCADE, ...).
|
and some flags (NODEPS, FORCE, CASCADE, ...).
|
||||||
|
|
||||||
Note: there can only be one type at a time: a transaction is either
|
Note: there can only be one type at a time: a transaction is either
|
||||||
created to add packages to the system, or either created to remove packages.
|
created to add packages to the system, or either created to remove packages.
|
||||||
The frontend can't request for mixed operations: it has to run several
|
The frontend can't request for mixed operations: it has to run several
|
||||||
transactions, one at a time, in such a case.
|
transactions, one at a time, in such a case.
|
||||||
|
|
||||||
The flags allow to tweak the library behaviour during its resolution.
|
The flags allow to tweak the library behaviour during its resolution.
|
||||||
Note, that some options of the handle can also modify the behavior of a
|
Note, that some options of the handle can also modify the behavior of a
|
||||||
transaction (NOUPGRADE, IGNOREPKG, ...).
|
transaction (NOUPGRADE, IGNOREPKG, ...).
|
||||||
|
|
||||||
Note: once a transaction has been initiated, it is not possible anymore
|
Note: once a transaction has been initiated, it is not possible anymore
|
||||||
to modify its type or its flags.
|
to modify its type or its flags.
|
||||||
|
|
||||||
One can also add some targets to a transaction (alpm_trans_addtarget()).
|
One can also add some targets to a transaction (alpm_trans_addtarget()).
|
||||||
These targets represent the list of packages to be handled.
|
These targets represent the list of packages to be handled.
|
||||||
|
|
||||||
Then, a transaction needs to be prepared (alpm_trans_prepare()). It
|
Then, a transaction needs to be prepared (alpm_trans_prepare()). It
|
||||||
means that the various targets added, will be inspected and challenged
|
means that the various targets added, will be inspected and challenged
|
||||||
against the set of alreayd installed packages (dependency checkings,
|
against the set of alreayd installed packages (dependency checkings,
|
||||||
|
|
||||||
Last, a callback is associated with each transaction. During the
|
Last, a callback is associated with each transaction. During the
|
||||||
transaction resolution, each time a new step is started or done (i.e
|
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 checkings, package adding or removal, ...), the
|
||||||
callback is called, allowing the frontend to be aware of the progress of
|
callback is called, allowing the frontend to be aware of the progress of
|
||||||
the resolution. Can be useful to implement a progress bar.
|
the resolution. Can be useful to implement a progress bar.
|
||||||
|
|
||||||
|
|
||||||
[CONFIGURATION/OPTIONS] (see handle.c)
|
[CONFIGURATION/OPTIONS] (see handle.c)
|
||||||
|
|
||||||
The library does not use any configuration file. The handle holds a
|
The library does not use any configuration file. The handle holds a
|
||||||
number of configuration options instead (IGNOREPKG, SYSLOG usage,
|
number of configuration options instead (IGNOREPKG, SYSLOG usage,
|
||||||
log file name, registered databases, ...).
|
log file name, registered databases, ...).
|
||||||
It is up to the frontend to set the options of the library.
|
It is up to the frontend to set the options of the library.
|
||||||
Options can be manipulated using calls to
|
Options can be manipulated using calls to
|
||||||
alpm_set_option()/alpm_get_option().
|
alpm_set_option()/alpm_get_option().
|
||||||
|
|
||||||
Note: the file system root is a special option which can only be defined
|
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.
|
when calling alpm_lib_init(). It can't be modified afterwards.
|
||||||
|
|
||||||
|
|
||||||
[CACHE] (see cache.c)
|
[CACHE] (see cache.c)
|
||||||
|
|
||||||
Compared to pacman 2.9, there is now one cache object connected to each
|
Compared to pacman 2.9, there is now one cache object connected to each
|
||||||
database object.
|
database object.
|
||||||
There are both a package and a group cache.
|
There are both a package and a group cache.
|
||||||
The cache is loaded only on demand (i.e the cache is loaded the first
|
The cache is loaded only on demand (i.e the cache is loaded the first
|
||||||
time data from it should be used).
|
time data from it should be used).
|
||||||
|
|
||||||
Note: the cache of a database is always updated by the library after
|
Note: the cache of a database is always updated by the library after
|
||||||
an operation changing the database content (adding and/or removal of
|
an operation changing the database content (adding and/or removal of
|
||||||
packages).
|
packages).
|
||||||
Beware frontends ;)
|
Beware frontends ;)
|
||||||
|
|
||||||
|
|
||||||
[PACKAGE] (see package.c, and also db.c)
|
[PACKAGE] (see package.c, and also db.c)
|
||||||
|
|
||||||
The package structure is using three new fields, namely: origin, data,
|
The package structure is using three new fields, namely: origin, data,
|
||||||
infolevel.
|
infolevel.
|
||||||
The purpose of these fields is to know some extra info about data stored
|
The purpose of these fields is to know some extra info about data stored
|
||||||
in package structures.
|
in package structures.
|
||||||
|
|
||||||
For instance, where is the package coming from (i.e origin)?
|
For instance, where is the package coming from (i.e origin)?
|
||||||
Was it loaded from a file or loaded from the cache?
|
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
|
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
|
name of the file, and infolevel is set to the highest possible value
|
||||||
(all package fields are reputed to be known).
|
(all package fields are reputed to be known).
|
||||||
Otherwise, if the package comes from a database, data is a pointer to
|
Otherwise, if the package comes from a database, data is a pointer to
|
||||||
the database structure hosting the package, and infolevel is set
|
the database structure hosting the package, and infolevel is set
|
||||||
according to the db_read() infolevel parameter (it is possible using
|
according to the db_read() infolevel parameter (it is possible using
|
||||||
db_read() to only read a part of the package datas).
|
db_read() to only read a part of the package datas).
|
||||||
|
|
||||||
Indeed, to reduce database access, all packages data requested by the
|
Indeed, to reduce database access, all packages data requested by the
|
||||||
frontend are comming from the cache. As a consequence, the library needs
|
frontend are comming from the cache. As a consequence, the library needs
|
||||||
to know exactly the level of information about packages it holds, and
|
to know exactly the level of information about packages it holds, and
|
||||||
then decide if more data needs to be fetched from the database.
|
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
|
In file alpm.c, have a look at alpm_pkg_getinfo() function to get an
|
||||||
overview.
|
overview.
|
||||||
|
|
||||||
|
|
||||||
[ERRORS] (error.c)
|
[ERRORS] (error.c)
|
||||||
|
|
||||||
The library provides a global variable pm_errno.
|
The library provides a global variable pm_errno.
|
||||||
It aims at being to the library what errno is for C system calls.
|
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
|
Almost all public library functions are returning an integer value: 0
|
||||||
indicating success, whereas -1 would indicate a failure.
|
indicating success, whereas -1 would indicate a failure.
|
||||||
If -1 is returned, the variable pm_errno is set to a meaningful value
|
If -1 is returned, the variable pm_errno is set to a meaningful value
|
||||||
(not always yet, but it should improve ;).
|
(not always yet, but it should improve ;).
|
||||||
Wise frontends should always care for these returned values.
|
Wise frontends should always care for these returned values.
|
||||||
|
|
||||||
Note: the helper function alpm_strerror() can also be used to translate
|
Note: the helper function alpm_strerror() can also be used to translate
|
||||||
the error code into a more friendly sentence.
|
the error code into a more friendly sentence.
|
||||||
|
|
||||||
|
|
||||||
[LIST] (see list.c, and especially list wrappers in alpm.c)
|
[LIST] (see list.c, and especially list wrappers in alpm.c)
|
||||||
|
|
||||||
It is a double chained list structure, use only for the internal needs
|
It is a double chained list structure, use only for the internal needs
|
||||||
of the library.
|
of the library.
|
||||||
A frontend should be free to use its own data structures to manipulate
|
A frontend should be free to use its own data structures to manipulate
|
||||||
packages.
|
packages.
|
||||||
For instance, consider a graphical frontend using the gtk toolkit (and
|
For instance, consider a graphical frontend using the gtk toolkit (and
|
||||||
as a consequence the glib library). The frontend will make use of the
|
as a consequence the glib library). The frontend will make use of the
|
||||||
glib chained lists or trees.
|
glib chained lists or trees.
|
||||||
As a consequence, the library only provides a simple and very small
|
As a consequence, the library only provides a simple and very small
|
||||||
interface to retrieve pointers to its internal data (see functions
|
interface to retrieve pointers to its internal data (see functions
|
||||||
alpm_list_first(), alpm_list_next() and alpm_list_getdata()), giving to
|
alpm_list_first(), alpm_list_next() and alpm_list_getdata()), giving to
|
||||||
the frontend the responsibility to copy and store the data retrieved
|
the frontend the responsibility to copy and store the data retrieved
|
||||||
from the library in its own data structures.
|
from the library in its own data structures.
|
||||||
|
|
||||||
|
|
||||||
PACMAN frontend overview & internals
|
PACMAN frontend overview & internals
|
||||||
====================================
|
====================================
|
||||||
|
|
||||||
Here are some words about the frontend responsibilities.
|
Here are some words about the frontend responsibilities.
|
||||||
The library can operate only a small set of well defined operations and
|
The library can operate only a small set of well defined operations and
|
||||||
dumy operations.
|
dumy operations.
|
||||||
|
|
||||||
High level features are left to the frontend ;)
|
High level features are left to the frontend ;)
|
||||||
|
|
||||||
For instance, during a sysupgrade, the library returns the whole list of
|
For instance, during a sysupgrade, the library returns the whole list of
|
||||||
packages to be upgraded, without any care for its content.
|
packages to be upgraded, without any care for its content.
|
||||||
The frontend can inspect the list and perhaps notice that "pacman"
|
The frontend can inspect the list and perhaps notice that "pacman"
|
||||||
itself has to be upgraded. In such a case, the frontend can choose to
|
itself has to be upgraded. In such a case, the frontend can choose to
|
||||||
perform a special action.
|
perform a special action.
|
||||||
|
|
||||||
|
|
||||||
[MAIN] (see pacman.c)
|
[MAIN] (see pacman.c)
|
||||||
|
|
||||||
Calls for alpm_lib_init(), and alpm_lib_release().
|
Calls for alpm_lib_init(), and alpm_lib_release().
|
||||||
Read the configuration file, and parse command line arguments.
|
Read the configuration file, and parse command line arguments.
|
||||||
Based on the action requested, it initiates the appropriate transactions
|
Based on the action requested, it initiates the appropriate transactions
|
||||||
(see pacman_add(), pacman_remove(), pacman_sync() in files add.c,
|
(see pacman_add(), pacman_remove(), pacman_sync() in files add.c,
|
||||||
remove.c and sync.c).
|
remove.c and sync.c).
|
||||||
|
|
||||||
|
|
||||||
[CONFIGURATION] (see conf.c)
|
[CONFIGURATION] (see conf.c)
|
||||||
|
|
||||||
The frontend is using a configuration file, usually "/etc/pacman.conf".
|
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 usefull for the frontend only (mainly,
|
||||||
the download stuffs, and some options like HOLDPKG).
|
the download stuffs, and some options like HOLDPKG).
|
||||||
The rest is used to configure the library.
|
The rest is used to configure the library.
|
||||||
|
|
||||||
|
|
||||||
[ADD/UPGRADE/REMOVE/SYNC]
|
[ADD/UPGRADE/REMOVE/SYNC]
|
||||||
|
|
||||||
Nothing new here, excepted some reorganization.
|
Nothing new here, excepted some reorganization.
|
||||||
|
|
||||||
The file pacman.c has been divided into several smaller files, namely
|
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,
|
add.c, remove.c, sync.c and query.c, to hold the big parts: pacman_add,
|
||||||
pacman_remove, pacman_sync.
|
pacman_remove, pacman_sync.
|
||||||
These 3 functions have been splitted too to ease the code reading.
|
These 3 functions have been splitted too to ease the code reading.
|
||||||
|
|
||||||
|
|
||||||
[DONWLOAD] (see download.c)
|
[DONWLOAD] (see download.c)
|
||||||
|
|
||||||
The library is not providing download facilities. As a consequence, it
|
The library is not providing download facilities. As a consequence, it
|
||||||
is up the the frontend to retrieve packages from Arch Linux servers.
|
is up the the frontend to retrieve packages from Arch Linux servers.
|
||||||
To do so, pacman is linked against an improved version of libftp
|
To do so, pacman is linked against an improved version of libftp
|
||||||
supporting both http and ftp donwloads.
|
supporting both http and ftp donwloads.
|
||||||
As a consequence, the frontend is repsonsible for the directory
|
As a consequence, the frontend is repsonsible for the directory
|
||||||
/var/cache/pacman/pkgs.
|
/var/cache/pacman/pkgs.
|
||||||
One can consider that this cache is a facility provided by pacman.
|
One can consider that this cache is a facility provided by pacman.
|
||||||
|
|
||||||
Note: other frontends have to download packages by themselves too,
|
Note: other frontends have to download packages by themselves too,
|
||||||
although the cache directory can be shared by several frontends.
|
although the cache directory can be shared by several frontends.
|
||||||
|
|
||||||
|
|
||||||
[LIST] (see list.c)
|
[LIST] (see list.c)
|
||||||
|
|
||||||
Single chained list.
|
Single chained list.
|
||||||
A minimalistic chained list implementation to store options from the
|
A minimalistic chained list implementation to store options from the
|
||||||
configuration file, and targets passed to pacman on the command line.
|
configuration file, and targets passed to pacman on the command line.
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue