[pacman-dev] [PATCH 06/23] doc: document depends
morganamilo
morganamilo at archlinux.org
Mon Dec 7 22:19:39 UTC 2020
---
lib/libalpm/alpm.h | 295 +++++++++++++++++++++++++--------------------
1 file changed, 164 insertions(+), 131 deletions(-)
diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 43a47d54..ea99a8b3 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -441,49 +441,26 @@ int alpm_extract_keyid(alpm_handle_t *handle, const char *identifier,
/** @} */
-/*
- * Enumerations
- * These ones are used in multiple contexts, so are forward-declared.
+/** @addtogroup alpm_depends Dependency
+ * @brief Functions dealing with libalpm's dependency and conflict
+ * information.
+ * @{
*/
-/** Package install reasons. */
-typedef enum _alpm_pkgreason_t {
- /** Explicitly requested by the user. */
- ALPM_PKG_REASON_EXPLICIT = 0,
- /** Installed as a dependency for another package. */
- ALPM_PKG_REASON_DEPEND = 1
-} alpm_pkgreason_t;
-
-/** Location a package object was loaded from. */
-typedef enum _alpm_pkgfrom_t {
- ALPM_PKG_FROM_FILE = 1,
- ALPM_PKG_FROM_LOCALDB,
- ALPM_PKG_FROM_SYNCDB
-} alpm_pkgfrom_t;
-
-/** Method used to validate a package. */
-typedef enum _alpm_pkgvalidation_t {
- ALPM_PKG_VALIDATION_UNKNOWN = 0,
- ALPM_PKG_VALIDATION_NONE = (1 << 0),
- ALPM_PKG_VALIDATION_MD5SUM = (1 << 1),
- ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2),
- ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3)
-} alpm_pkgvalidation_t;
-
/** Types of version constraints in dependency specs. */
typedef enum _alpm_depmod_t {
- /** No version constraint */
- ALPM_DEP_MOD_ANY = 1,
- /** Test version equality (package=x.y.z) */
- ALPM_DEP_MOD_EQ,
- /** Test for at least a version (package>=x.y.z) */
- ALPM_DEP_MOD_GE,
- /** Test for at most a version (package<=x.y.z) */
- ALPM_DEP_MOD_LE,
- /** Test for greater than some version (package>x.y.z) */
- ALPM_DEP_MOD_GT,
- /** Test for less than some version (package<x.y.z) */
- ALPM_DEP_MOD_LT
+ /** No version constraint */
+ ALPM_DEP_MOD_ANY = 1,
+ /** Test version equality (package=x.y.z) */
+ ALPM_DEP_MOD_EQ,
+ /** Test for at least a version (package>=x.y.z) */
+ ALPM_DEP_MOD_GE,
+ /** Test for at most a version (package<=x.y.z) */
+ ALPM_DEP_MOD_LE,
+ /** Test for greater than some version (package>x.y.z) */
+ ALPM_DEP_MOD_GT,
+ /** Test for less than some version (package<x.y.z) */
+ ALPM_DEP_MOD_LT
} alpm_depmod_t;
/**
@@ -492,48 +469,187 @@ typedef enum _alpm_depmod_t {
* another target in the transaction.
*/
typedef enum _alpm_fileconflicttype_t {
+ /** The conflict results with a another target in the transaction */
ALPM_FILECONFLICT_TARGET = 1,
+ /** The conflict results from a file existing on the filesystem */
ALPM_FILECONFLICT_FILESYSTEM
} alpm_fileconflicttype_t;
-/*
- * Structures
- */
-
-/** Dependency */
+/** The basic dependency type.
+ *
+ * This type is used throughout libalpm, not just for dependencies
+ * but also conflicts and providers. */
typedef struct _alpm_depend_t {
+ /** Name of the provider to satisfy this dependnecy */
char *name;
+ /** Version of the provider to match against (optional) */
char *version;
+ /** A description of why this dependency is needed (optional) */
char *desc;
+ /** A hash of name (used internally to speed up conflict checks) */
unsigned long name_hash;
+ /** How the version should match against the provider */
alpm_depmod_t mod;
} alpm_depend_t;
-/** Missing dependency */
+/** Missing dependency. */
typedef struct _alpm_depmissing_t {
+ /** Name of the package that has the dependnecy */
char *target;
+ /** The dependency that was wanted */
alpm_depend_t *depend;
- /* this is used only in the case of a remove dependency error */
+ /** If the depmissing was caused by a conflict, the name of the package
+ * that would be installed, causing the satisfying package to be removed */
char *causingpkg;
} alpm_depmissing_t;
-/** Conflict */
+/** A conflict that has occurred between two packages. */
typedef struct _alpm_conflict_t {
+ /** Hash of the first package name
+ * (used internally to speed up conflict checks) */
unsigned long package1_hash;
+ /** Hash of the second package name
+ * (used internally to speed up conflict checks) */
unsigned long package2_hash;
+ /** Name of the first package */
char *package1;
+ /** Name of the second package */
char *package2;
+ /** The conflict */
alpm_depend_t *reason;
} alpm_conflict_t;
-/** File conflict */
+/** File conflict.
+ *
+ * A conflict that has happened due to a two packages containing the same file,
+ * or a package contains a file that is already on the filesystem and not owned
+ * by that package. */
typedef struct _alpm_fileconflict_t {
+ /** The name of the package that caused the conflict */
char *target;
+ /** The type of conflict */
alpm_fileconflicttype_t type;
+ /** The name of the file that the package conflicts with */
char *file;
+ /** The name of the package that also owns the file if there is one*/
char *ctarget;
} alpm_fileconflict_t;
+/** Checks dependencies and returns missing ones in a list.
+ * Dependencies can include versions with depmod operators.
+ * @param handle the context handle
+ * @param pkglist the list of local packages
+ * @param remove an alpm_list_t* of packages to be removed
+ * @param upgrade an alpm_list_t* of packages to be upgraded (remove-then-upgrade)
+ * @param reversedeps handles the backward dependencies
+ * @return an alpm_list_t* of alpm_depmissing_t pointers.
+ */
+alpm_list_t *alpm_checkdeps(alpm_handle_t *handle, alpm_list_t *pkglist,
+ alpm_list_t *remove, alpm_list_t *upgrade, int reversedeps);
+
+/** Find a package satisfying a specified dependency.
+ * The dependency can include versions with depmod operators.
+ * @param pkgs an alpm_list_t* of alpm_pkg_t where the satisfier will be searched
+ * @param depstring package or provision name, versioned or not
+ * @return a alpm_pkg_t* satisfying depstring
+ */
+alpm_pkg_t *alpm_find_satisfier(alpm_list_t *pkgs, const char *depstring);
+
+/** Find a package satisfying a specified dependency.
+ * First look for a literal, going through each db one by one. Then look for
+ * providers. The first satisfier that belongs to an installed package is
+ * returned. If no providers belong to an installed package then an
+ * alpm_question_select_provider_t is created to select the provider.
+ * The dependency can include versions with depmod operators.
+ *
+ * @param handle the context handle
+ * @param dbs an alpm_list_t* of alpm_db_t where the satisfier will be searched
+ * @param depstring package or provision name, versioned or not
+ * @return a alpm_pkg_t* satisfying depstring
+ */
+alpm_pkg_t *alpm_find_dbs_satisfier(alpm_handle_t *handle,
+ alpm_list_t *dbs, const char *depstring);
+
+/** Check the package conflicts in a database
+ *
+ * @param handle the context handle
+ * @param pkglist the list of packages to check
+ *
+ * @return an alpm_list_t of alpm_conflict_t
+ */
+alpm_list_t *alpm_checkconflicts(alpm_handle_t *handle, alpm_list_t *pkglist);
+
+/** Returns a newly allocated string representing the dependency information.
+ * @param dep a dependency info structure
+ * @return a formatted string, e.g. "glibc>=2.12"
+ */
+char *alpm_dep_compute_string(const alpm_depend_t *dep);
+
+/** Return a newly allocated dependency information parsed from a string
+ *\link alpm_dep_free should be used to free the dependency \endlink
+ * @param depstring a formatted string, e.g. "glibc=2.12"
+ * @return a dependency info structure
+ */
+alpm_depend_t *alpm_dep_from_string(const char *depstring);
+
+/** Free a dependency info structure
+ * @param dep struct to free
+ */
+void alpm_dep_free(alpm_depend_t *dep);
+
+/** Free a fileconflict and its members.
+ * @param conflict the fileconflict to free
+ */
+void alpm_fileconflict_free(alpm_fileconflict_t *conflict);
+
+/** Free a depmissing and its members
+ * @param miss the depmissing to fre
+ * */
+void alpm_depmissing_free(alpm_depmissing_t *miss);
+
+/**
+ * Free a conflict and its members.
+ * @param conflict the conflict to free
+ */
+void alpm_conflict_free(alpm_conflict_t *conflict);
+
+
+/* End of alpm_depends */
+/** @} */
+
+/*
+ * Enumerations
+ * These ones are used in multiple contexts, so are forward-declared.
+ */
+
+/** Package install reasons. */
+typedef enum _alpm_pkgreason_t {
+ /** Explicitly requested by the user. */
+ ALPM_PKG_REASON_EXPLICIT = 0,
+ /** Installed as a dependency for another package. */
+ ALPM_PKG_REASON_DEPEND = 1
+} alpm_pkgreason_t;
+
+/** Location a package object was loaded from. */
+typedef enum _alpm_pkgfrom_t {
+ ALPM_PKG_FROM_FILE = 1,
+ ALPM_PKG_FROM_LOCALDB,
+ ALPM_PKG_FROM_SYNCDB
+} alpm_pkgfrom_t;
+
+/** Method used to validate a package. */
+typedef enum _alpm_pkgvalidation_t {
+ ALPM_PKG_VALIDATION_UNKNOWN = 0,
+ ALPM_PKG_VALIDATION_NONE = (1 << 0),
+ ALPM_PKG_VALIDATION_MD5SUM = (1 << 1),
+ ALPM_PKG_VALIDATION_SHA256SUM = (1 << 2),
+ ALPM_PKG_VALIDATION_SIGNATURE = (1 << 3)
+} alpm_pkgvalidation_t;
+
+/*
+ * Structures
+ */
+
/** Package group */
typedef struct _alpm_group_t {
/** group name */
@@ -1900,76 +2016,6 @@ int alpm_remove_pkg(alpm_handle_t *handle, alpm_pkg_t *pkg);
/** @} */
-/** @addtogroup alpm_api_depends Dependency Functions
- * Functions dealing with libalpm representation of dependency
- * information.
- * @{
- */
-
-/** Checks dependencies and returns missing ones in a list.
- * Dependencies can include versions with depmod operators.
- * @param handle the context handle
- * @param pkglist the list of local packages
- * @param remove an alpm_list_t* of packages to be removed
- * @param upgrade an alpm_list_t* of packages to be upgraded (remove-then-upgrade)
- * @param reversedeps handles the backward dependencies
- * @return an alpm_list_t* of alpm_depmissing_t pointers.
- */
-alpm_list_t *alpm_checkdeps(alpm_handle_t *handle, alpm_list_t *pkglist,
- alpm_list_t *remove, alpm_list_t *upgrade, int reversedeps);
-
-/** Find a package satisfying a specified dependency.
- * The dependency can include versions with depmod operators.
- * @param pkgs an alpm_list_t* of alpm_pkg_t where the satisfier will be searched
- * @param depstring package or provision name, versioned or not
- * @return a alpm_pkg_t* satisfying depstring
- */
-alpm_pkg_t *alpm_find_satisfier(alpm_list_t *pkgs, const char *depstring);
-
-/** Find a package satisfying a specified dependency.
- * First look for a literal, going through each db one by one. Then look for
- * providers. The first satisfier that belongs to an installed package is
- * returned. If no providers belong to an installed package then an
- * alpm_question_select_provider_t is created to select the provider.
- * The dependency can include versions with depmod operators.
- *
- * @param handle the context handle
- * @param dbs an alpm_list_t* of alpm_db_t where the satisfier will be searched
- * @param depstring package or provision name, versioned or not
- * @return a alpm_pkg_t* satisfying depstring
- */
-alpm_pkg_t *alpm_find_dbs_satisfier(alpm_handle_t *handle,
- alpm_list_t *dbs, const char *depstring);
-
-/**
- * @brief Check the package conflicts in a database
- *
- * @param handle the context handle
- * @param pkglist the list of packages to check
- *
- * @return an alpm_list_t of alpm_conflict_t
- */
-alpm_list_t *alpm_checkconflicts(alpm_handle_t *handle, alpm_list_t *pkglist);
-
-/** Returns a newly allocated string representing the dependency information.
- * @param dep a dependency info structure
- * @return a formatted string, e.g. "glibc>=2.12"
- */
-char *alpm_dep_compute_string(const alpm_depend_t *dep);
-
-/** Return a newly allocated dependency information parsed from a string
- * @param depstring a formatted string, e.g. "glibc=2.12"
- * @return a dependency info structure
- */
-alpm_depend_t *alpm_dep_from_string(const char *depstring);
-
-/** Free a dependency info structure
- * @param dep struct to free
- */
-void alpm_dep_free(alpm_depend_t *dep);
-
-/** @} */
-
/** @} */
/*
@@ -2021,19 +2067,6 @@ const char *alpm_version(void);
* */
int alpm_capabilities(void);
-/**
- * Free a fileconflict and its members.
- * @param conflict the fileconflict to free
- */
-void alpm_fileconflict_free(alpm_fileconflict_t *conflict);
-void alpm_depmissing_free(alpm_depmissing_t *miss);
-
-/**
- * Free a conflict and its members.
- * @param conflict the conflict to free
- */
-void alpm_conflict_free(alpm_conflict_t *conflict);
-
/* End of alpm_api */
/** @} */
--
2.29.2
More information about the pacman-dev
mailing list