Re: [pacman-dev] [PATCH 2/2] makepkg: add CRC checksums and set these to be the default

[Allan McRae]

On 25/1/20 12:19 am, Giancarlo Razzolini wrote:
> Em janeiro 24, 2020 1:56 Allan McRae escreveu:
>>
>> Well...  we hope that no-one will ever use this algorithm!
>>
> 
> Then why waste everyone's time going through this process of adding it?

Because I consider people to be delusional who use "makepkg -g" and
think their checksums are fine.  I find trust on first use ignorant in
terms of software downloads.  That is reflected in my decision to
include CRC and add it as the default, so PKGBUILDs from people who add
checksums without thinking will be visible.

Even then, the CRC checksum will only be used by "makepkg -g" if there
is no other checksums in a PKGBUILD.  So only a portion of the blind
trust will be visible.

Allan

[pacman-dev] [PATCH 2/2] Docs docs docs and more docs

[morganamilo]

Write docs for every public alpm member and expand on the existing
documentation for other members.

---

The entire .h file has basically been restructed. The best way to see
the end result is either to read the generated man pages or enabled html
and view the generated html.

Also note alpm_list is still not documented.
---
 lib/libalpm/alpm.h  | 1546 ++-
 lib/libalpm/alpm_list.h |   14 +-
 lib/libalpm/version.c   |2 +-
 3 files changed, 1200 insertions(+), 362 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 4a2d2fc1..51e9e5b4 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -20,6 +20,16 @@
  *  You should have received a copy of the GNU General Public License
  *  along with this program.  If not, see .
  */
+
+/**
+ * @file alpm.h
+ * @author Pacman Development Team
+ * @date 26 Jan 2020
+ * @brief Arch Linux Package Manager Library
+ *
+ * bork
+ */
+
 #ifndef ALPM_H
 #define ALPM_H
 
@@ -38,267 +48,313 @@ extern "C" {
 #include 
 
 /*
- * Arch Linux Package Management library
+ * Opaque Structures
  */
 
-/*
- * Opaque Structures
+/** The libalpm context handle.
+ *
+ * This struct represents an instance of libalpm.
  */
 typedef struct __alpm_handle_t alpm_handle_t;
+
+/** A database.
+ *
+ * A database is a container that stores metadata about packages.
+ *
+ * A database can be located on the local filesystem or on a remote server.
+ *
+ * To use a database, it must first be registered via \link 
alpm_register_syncdb \endlink.
+ * If the database is already preasant in the dbpath then it will be usable. 
Otherwise,
+ * the database needs to be downloaded using \link alpm_db_update \endlink. 
Even if the
+ * source of the database is the local filesystem.
+ *
+ * After this, the database can be used to query packages and groups. Any 
packages or groups
+ * from the database will continue to be owned by the database and do not need 
to be freed by
+ * the user. They will be freed when the database is unregistered.
+ *
+ * Databases are automatically unregistered when the \link alpm_handle_t 
\endlink is released.
+ */
 typedef struct __alpm_db_t alpm_db_t;
+
+/** A package
+ *
+ * A package can be loaded from disk via \link alpm_pkg_load \endlink or 
retrieved from a database.
+ * Packages from databases are automatically freed when the database is 
unregistered. Packages loaded
+ * from a file must be freed manually.
+ *
+ * Packages can then be queried for metadata or added to a \link alpm_trans_t 
transaction \endlink
+ * to be added or removed from the system.
+ */
 typedef struct __alpm_pkg_t alpm_pkg_t;
+
+/** Transaction structure used internally by libalpm */
 typedef struct __alpm_trans_t alpm_trans_t;
 
-/** @addtogroup alpm_api_errors Error Codes
+/** @addtogroup alpm_api ALPM
+ * @brief The libalpm Public API
+ * @{
+ */
+
+/** @addtogroup alpm_errors Error Codes
+ * @brief The error codes used by libalpm
  * @{
  */
+
+/** libalpm's error type */
 typedef enum _alpm_errno_t {
+   /** No error */
ALPM_ERR_OK = 0,
+   /** Failed to allocate memory */
ALPM_ERR_MEMORY,
+   /** A system error occurred */
ALPM_ERR_SYSTEM,
+   /** Permmision denied */
ALPM_ERR_BADPERMS,
+   /** Should be a file */
ALPM_ERR_NOT_A_FILE,
+   /** Should be a directory */
ALPM_ERR_NOT_A_DIR,
+   /** Function was called with invalid arguments */
ALPM_ERR_WRONG_ARGS,
+   /** Insufficient disk space */
ALPM_ERR_DISK_SPACE,
/* Interface */
+   /** Handle should be null */
ALPM_ERR_HANDLE_NULL,
+   /** Handle should not be null */
ALPM_ERR_HANDLE_NOT_NULL,
+   /** Failed to acquire lock */
ALPM_ERR_HANDLE_LOCK,
/* Databases */
+   /** Failed to open database */
ALPM_ERR_DB_OPEN,
+   /** Failed to create database */
ALPM_ERR_DB_CREATE,
+   /** Database should not be null */
ALPM_ERR_DB_NULL,
+   /** Database should be null */
ALPM_ERR_DB_NOT_NULL,
+   /** The database could not be found */
ALPM_ERR_DB_NOT_FOUND,
+   /** Database is invalid */
ALPM_ERR_DB_INVALID,
+   /** Database has an invalid signature */
ALPM_ERR_DB_INVALID_SIG,
+   /** The localdb is in a newer/older format than libalpm expects */
ALPM_ERR_DB_VERSION,
+   /** Fauked to write to the database */
ALPM_ERR_DB_WRITE,
+   /** Fauked to remove entry from database */
ALPM_ERR_DB_REMOVE,
/* Servers */
+   /** Server URL is in an invalid format */
ALPM_ERR_SERVER_BAD_URL,
+   /** The database has no configured servers */
ALPM_ERR_SERVER_NONE,
/* Transactions */
+   /** A transaction is already initialized */
ALPM_ERR_TRANS_NOT_NULL,
+   /** A transaction has not been initialized */
ALPM_ERR_TRANS_NULL,
+   /** Duplicate ta

[pacman-dev] [PATCH 1/2] Docs docs docs

[morganamilo]

libalpm: move docs from .c files into alpm.h And fix/expand some
along the way.
---
 lib/libalpm/add.c  |   1 -
 lib/libalpm/alpm.c |  33 --
 lib/libalpm/alpm.h | 247 -
 lib/libalpm/be_sync.c  |  35 --
 lib/libalpm/conflict.c |  14 ---
 lib/libalpm/db.c   |  34 --
 lib/libalpm/deps.c |  32 --
 lib/libalpm/dload.c|   1 -
 lib/libalpm/handle.c   |   6 -
 lib/libalpm/log.c  |  13 ---
 lib/libalpm/package.c  |  28 -
 lib/libalpm/remove.c   |   8 --
 lib/libalpm/signing.c  |  34 --
 lib/libalpm/sync.c |  17 ---
 lib/libalpm/trans.c|  12 --
 lib/libalpm/util.c |  10 --
 lib/libalpm/version.c  |  14 ---
 17 files changed, 241 insertions(+), 298 deletions(-)

diff --git a/lib/libalpm/add.c b/lib/libalpm/add.c
index b949976d..2cfb3974 100644
--- a/lib/libalpm/add.c
+++ b/lib/libalpm/add.c
@@ -47,7 +47,6 @@
 #include "remove.h"
 #include "handle.h"
 
-/** Add a package to the transaction. */
 int SYMEXPORT alpm_add_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg)
 {
const char *pkgname, *pkgver;
diff --git a/lib/libalpm/alpm.c b/lib/libalpm/alpm.c
index 1a378db9..cb2ab795 100644
--- a/lib/libalpm/alpm.c
+++ b/lib/libalpm/alpm.c
@@ -32,19 +32,6 @@
 #include "log.h"
 #include "util.h"
 
-/** \addtogroup alpm_interface Interface Functions
- * @brief Functions to initialize and release libalpm
- * @{
- */
-
-/** Initializes the library.
- * Creates handle, connects to database and creates lockfile.
- * This must be called before any other functions are called.
- * @param root the root path for all filesystem operations
- * @param dbpath the absolute path to the libalpm database
- * @param err an optional variable to hold any error return codes
- * @return a context handle on success, NULL on error, err will be set if 
provided
- */
 alpm_handle_t SYMEXPORT *alpm_initialize(const char *root, const char *dbpath,
alpm_errno_t *err)
 {
@@ -99,14 +86,6 @@ cleanup:
return NULL;
 }
 
-/** Release the library.
- * Disconnects from the database, removes handle and lockfile
- * This should be the last alpm call you make.
- * After this returns, handle should be considered invalid and cannot be reused
- * in any way.
- * @param myhandle the context handle
- * @return 0 on success, -1 on error
- */
 int SYMEXPORT alpm_release(alpm_handle_t *myhandle)
 {
int ret = 0;
@@ -135,23 +114,11 @@ int SYMEXPORT alpm_release(alpm_handle_t *myhandle)
return ret;
 }
 
-/** @} */
-
-/** @defgroup alpm_misc Miscellaneous Functions
- * @brief Various libalpm functions
- */
-
-/** Get the version of library.
- * @return the library version, e.g. "6.0.4"
- * */
 const char SYMEXPORT *alpm_version(void)
 {
return LIB_VERSION;
 }
 
-/** Get the capabilities of the library.
- * @return a bitmask of the capabilities
- * */
 int SYMEXPORT alpm_capabilities(void)
 {
return 0
diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 956284bd..4a2d2fc1 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -335,6 +335,11 @@ typedef enum _alpm_hook_when_t {
  * Logging facilities
  */
 
+/** \addtogroup alpm_log Logging Functions
+ * @brief Functions to log using libalpm
+ * @{
+ */
+
 /** Logging Levels */
 typedef enum _alpm_loglevel_t {
ALPM_LOG_ERROR= 1,
@@ -345,9 +350,17 @@ typedef enum _alpm_loglevel_t {
 
 typedef void (*alpm_cb_log)(alpm_loglevel_t, const char *, va_list);
 
+/** A printf-like function for logging.
+ * @param handle the context handle
+ * @param prefix caller-specific prefix for the log
+ * @param fmt output format
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_logaction(alpm_handle_t *handle, const char *prefix,
const char *fmt, ...) __attribute__((format(printf, 3, 4)));
 
+/** @} */
+
 /**
  * Type of events.
  */
@@ -960,12 +973,71 @@ int alpm_db_get_valid(alpm_db_t *db);
 /** @name Accessors to the list of servers for a database.
  * @{
  */
+
+/** Get the list of servers assigned to this db.
+ * @param db pointer to the database to get the servers from
+ * @return a char* list of servers
+ */
 alpm_list_t *alpm_db_get_servers(const alpm_db_t *db);
+
+/** Sets the list of servers for the database to use.
+ * @param db the database to set the servers
+ * @param a char* list of servers. Note: the database will
+ * take ownership of the list and it should no longer be
+ * freed by the caller
+ */
 int alpm_db_set_servers(alpm_db_t *db, alpm_list_t *servers);
+
+/** Add a download server to a database.
+ * @param db database pointer
+ * @param url url of the server
+ * @return 0 on success, -1 on error (pm_errno is set accordingly)
+ */
 int alpm_db_add_server(alpm_db_t *db, const char *url);
+
+/** Remove a download server from a database.
+ * @param db database pointer
+ * @param url url of the server
+ * @return 0 on success, 1 on server not present,
+ * -1 on error (pm_errno is set accordingly)
+ */