==========================================================================
README:

Overview and internals of the PACMAN library and the PACMAN-G2 frontend.

This document describes the state of the implementation before its CVS
import.
At this stage, the code is in pre-alpha state, but the design should not
change that much.
There's still need for some work to get the current code properly working.
The tag "TODO" was added in various places in the code, each time a point
remains unclear or is not yet implemented.

==========================================================================

The "Second Generation" project
===============================

Pacman-G2 is a fork of the not-yet-released cvs version of the complete rewrite
of pacman by Aurelien Foret (the old monolithic pacman is written by Judd
Vinet).

So it provides a library interface to create real front-ends (not just
wrappers) to this great package management tool.

Some features that pacman-g2 has over pacman: (September 2007)

1) It provides C#, Java, Perl and Python bindings for libpacman.
2) libpacman provides a configuration file parser (for pacman-g2.conf).
3) It provides support for subpackages, i.e. creating more than one binary
package using a single build script.
4) Localized manpages.
5) Stable library API. This means that we care about keeping the API
backwards-compatible. (Changes like
http://www.archlinux.org/pipermail/pacman-dev/2007-November/009886.html[this]
are
http://www.archlinux.org/pipermail/pacman-dev/2007-November/009893.html[applied]
without any problem by the pacman developers and we don't do so.)

Using patches to provide this features modify enough pacman to change its name.
Additionally the maintainers of pacman asked us to do so and they have reason.

Patches to port features or bugfixes from pacman are welcome, but in fact we
differed too much to regularly sync the common codebase between the two
projects.

Of course we would like to thank the original pacman developers for all their
effort till we worked together before the fork.

The current homepage of the fork can be found at:

http://ftp.frugalware.org/pub/other/pacman-g2/

The project uses the "pacman-g2" name instead of the "pacman" one, so that
users won't be confused.

If you are interested in developing pacman-g2, please subscribe to the
frugalware-devel@frugalware.org mailing list.

Also please note that the library shipped with pacman-g2 is called libpacman,
not libalpm. This is because libpacman is no longer meant to be specific
Archlinux, the distribution created by Judd Vinet, the original pacman author.

PACMAN library overview & internals
=================================

Here is a list of the main objects and files from the PACMAN (i.e. Package
Management) library.
This document, whilst not exhaustive, also indicates some limitations
(on purpose, or sometimes due to its poor design) of the library at the
present time.

Note: there is one special file ("pacman.h") which is the public interface
that should be distributed and installed on systems with the library.
Only structures, data and functions declared within this file are made
available to the frontend.
Lots of structures are of an opaque type and their fields are only
accessible in read-only mode, through some clearly defined functions.

Note: 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 primarily because of potential namespace conflicts between library
and frontend spaces.
Indeed, it is not possible to have two different functions with the same
name declared in both spaces.
To avoid such conflicts, some function names have been prepended with
"_pacman_".
In a general manner, public library functions are named
"pacman_<type>_<action>" (examples: pacman_trans_commit(),
pacman_release(), pacman_pkg_getinfo(), ...).
Internal (and thus private) functions should be named "_pacman_XXX" for
instance (examples: _pacman_needbackup(), _pacman_runscriplet(), ...).
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
are likely to be redefined in the frontend.
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
avoid conflicts with the frontend ones.
Finally, functions defined and used inside a single file should be
defined as "static".


[HANDLE] (see handle.c)

The "handle" object is the heart of the library. It is a global
structure available from almost all other objects (although 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
"pacman_init()" call, and destroyed upon "pacman_release()" call.

pacman_init() is used to initialize library internals and to create
the handle object (handle != NULL).
Before its call, the library can't be used.
pacman_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 place holder 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.


[TRANSACTION] (see trans.c, and also pacman.c)

The transaction structure permits easy manipulations of several packages
at a time (i.e. adding, upgrade and removal operations).

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
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
transactions, one at a time, in such a case.

The flags allow to tweak the library behaviour during its resolution.
Note, that some options of the handle can also modify the behaviour of a
transaction (NOUPGRADE, IGNOREPKG, ...).

Note: once a transaction has been initiated, it is not possible anymore
to modify its type or its flags.

One can also add some targets to a transaction (pacman_trans_addtarget()).
These targets represent the list of packages to be handled.

Then, a transaction needs to be prepared (pacman_trans_prepare()). It
means that the various targets added, will be inspected and challenged
against the set of already installed packages (dependency checks,

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 checks, 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
pacman_set_option()/pacman_get_option().

Note: the file system root is a special option which can only be defined
when calling pacman_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
an operation changing the database content (adding and/or removal of
packages).
Beware frontends ;)


[PACKAGE] (see package.c, and also db.c)

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.

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 data).

Indeed, to reduce database access, all packages data requested by the
frontend are coming 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 pacman.c, have a look at pacman_pkg_getinfo() function to get an
overview.

Also note that the whole database consists of plain text files. If there is
something wrong, all you need is to delete the corrupted directory and
reinstall the given package using --force. No more messages like:

----
bdb_db_open: Database cannot be opened, err 22. Restore from backup!
----

[ERRORS] (error.c)

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.
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 pacman_strerror() can also be used to translate
the error code into a more friendly sentence.


[LIST] (see list.c, and especially list wrappers in pacman.c)

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
pacman_list_first(), pacman_list_next() and pacman_list_getdata()), giving to
the frontend the responsibility to copy and store the data retrieved
from the library in its own data structures.


PACMAN-G2 frontend overview & internals
====================================

Here are some words about the frontend responsibilities.
The library can operate only a small set of well defined operations and
dummy operations.

High level features are left to the frontend ;)

For instance, during a sysupgrade, the library returns the whole list of
packages to be upgraded, without any care for its content.
The frontend can inspect the list and perhaps notice that "pacman-g2"
itself has to be upgraded. In such a case, the frontend can choose to
perform a special action.


[MAIN] (see pacman-g2.c)

Calls for pacman_init(), and pacman_release().
Read the configuration file, and parse command line arguments.
Based on the action requested, it initiates the appropriate transactions
(see pacman_add(), pacman_remove(), pacman_sync() in files add.c,
remove.c and sync.c).


[CONFIGURATION] (see conf.c)

The frontend is using a configuration file, usually "/etc/pacman-g2.conf".
Part of these options are useful for the frontend only (mainly,
the download stuffs, and some options like HOLDPKG).
The rest is used to configure the library.


[ADD/UPGRADE/REMOVE/SYNC]

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 in order to ease the code reading.


[DOWNLOAD] (see download.c)

The library is providing download facilities. As a consequence, it is no longer
up to the frontend to retrieve packages from FTP servers.  To do so, libpacman
is linked against an improved version of libftp supporting both http and ftp
downloads.  As a consequence, the library is responsible for the directory
/var/cache/pacman-g2/pkgs.  One can consider that this cache is a facility
provided by the library.


[LIST] (see list.c)

Single chained list.
A minimalistic chained list implementation to store options from the
configuration file, and targets passed to pacman-g2 on the command line.