removed "^M" symbols at end of lines

1 files changed, 270 insertions, 270 deletions

diff --git a/README b/README
index b9a627c7..8cb6c179 100644
--- a/README
+++ b/README
@@ -1,270 +1,270 @@
-==========================================================================

-README:

-

-Overview and internals of the ALPM library and the PACMAN 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 "ORE" was added in various places in the code, each time a point

-remains unclear or is not yet implemented.

-

-==========================================================================

-

-

-ALPM library overview & internals

-=================================

-

-Here is a list of the main objects and files from the ALPM (i.e. Arch

-Linux 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 ("alpm.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

-"_alpm_".

-In a general manner, public library functions are named

-"alpm_<type>_<action>" (examples: alpm_trans_commit(),

-alpm_lib_release(), alpm_pkg_getinfo(), ...).

-Internal (and thus private) functions should be named "_alpm_XXX" for

-instance (examples: _alpm_needbackup(), _alpm_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 (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.

-

-Last, but not least, the handle holds a _unique_ transaction object.

-

-

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

-

-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),

-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 behavior 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 (alpm_trans_addtarget()).

-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,

-

-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

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

-

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

-

-

-[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 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)

-

-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

-====================================

-

-Here are some words about the frontend responsibilities.

-The library can operate only a small set of well defined operations and

-dumy 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"

-itself has to be upgraded. In such a case, the frontend can choose to

-perform a special action.

-

-

-[MAIN] (see pacman.c)

-

-Calls for alpm_lib_init(), and alpm_lib_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.conf".

-Part of these options are only usefull 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 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.

-

+==========================================================================
+README:
+
+Overview and internals of the ALPM library and the PACMAN 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 "ORE" was added in various places in the code, each time a point
+remains unclear or is not yet implemented.
+
+==========================================================================
+
+
+ALPM library overview & internals
+=================================
+
+Here is a list of the main objects and files from the ALPM (i.e. Arch
+Linux 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 ("alpm.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
+"_alpm_".
+In a general manner, public library functions are named
+"alpm_<type>_<action>" (examples: alpm_trans_commit(),
+alpm_lib_release(), alpm_pkg_getinfo(), ...).
+Internal (and thus private) functions should be named "_alpm_XXX" for
+instance (examples: _alpm_needbackup(), _alpm_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 (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.
+
+Last, but not least, the handle holds a _unique_ transaction object.
+
+
+[TRANSACTION] (see trans.c, and also alpm.c)
+
+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),
+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 behavior 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 (alpm_trans_addtarget()).
+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,
+
+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
+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).
+
+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 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.
+
+
+[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 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)
+
+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
+====================================
+
+Here are some words about the frontend responsibilities.
+The library can operate only a small set of well defined operations and
+dumy 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"
+itself has to be upgraded. In such a case, the frontend can choose to
+perform a special action.
+
+
+[MAIN] (see pacman.c)
+
+Calls for alpm_lib_init(), and alpm_lib_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.conf".
+Part of these options are only usefull 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 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.
+